Repository navigation
config model cannot express per-index searchControls (or the full searchControls schema) #16
Description
Activity
- added a commit that references this issue
on Aug 27, 2026 Splitting this into what shipped and what is being dropped.
Capability half — delivered by the native config format (#19, #20)
The original complaint was that
agent-config.jsoncould not express per-indexsearchControls, so a round-trip forced the primary index's controls onto every replica. A native config carries the API's owntoolsarray, so per-index controls are represented exactly as the service stores them.snapshot→update --dry-runis clean for all 12 agents on the account, including ones whose primary index carries controls while their replicas do not — which is precisely the case this issue opened on.Probing also confirmed the API accepts per-index
searchControlson create, so this is genuine support rather than read-only fidelity.Documentation half — #21
The table here was right that the documented schema was incomplete. #21 corrects it: five of eight parameters were listed, and the single description column implied they share one shape. They do not —
constraintappears only on the numeric parameters,mergeonly on the list-valued ones, anddistinct/facetscarry neither.queryandcustomare documented as present-but-never-observed rather than omitted, and the README now states the table was derived by inspecting live agents rather than from a published schema.Friendly-format parity — dropping this
The suggestion in this issue was to accept
searchControlson a replica entry, with semantics to settle around whether an omitted key inherits the shared block or means "none".I would leave that undone. The capability now exists through the native format, so this would be a convenience for one specific case: provisioning several agents from one template and wanting different controls per index within them. Nobody has asked for that, and it costs a new inheritance rule in the config model — exactly the kind of subtle "which side wins" semantics that produced the diff bugs in #12 and #13. Worth adding when someone actually needs it, as a fresh and smaller issue.
Closing with #21.
Still unknown
mergesemantics remain unobserved —nullon every index of every agent, so its meaning is a guess. Same forqueryandcustom, which stayednulleven after the search-tool panel was filled in during investigation. Each would need a dashboard control that writes them, if one exists.
Problem
build_tool()accepts a singlesearchControlskey and copies it to every index:The API stores
searchControlsper index, and the dashboard writes them that way. Observed on agent47d6a15c:searchControlstcg_cards_msft-build-2026tcg_cards_msft-build-2026_price_ascnulltcg_cards_msft-build-2026_price_descnullThere is no way to express that in
agent-config.json. A round-trip of this agent through the CLI necessarily pushes the primary's controls onto both replicas. The dry-run reports this correctly, but the underlying config model cannot represent the desired state.Note this is separate from #6, which moved
searchControlsper-index in the payload. The config model is still one shared block.Suggested fix
Accept
searchControlson a replica entry, overriding (or opting out of) the shared block:{ "index": "tcg_cards_msft-build-2026", "searchControls": { "hitsPerPage": { "exposed": true, "default": 10 } }, "replicas": [ { "index": "tcg_cards_msft-build-2026_price_asc", "description": "...", "searchControls": null }, { "index": "tcg_cards_msft-build-2026_price_desc", "description": "..." } ] }_index_entry()already handles dict-shaped replica entries, so this extends an existing path. Semantics to settle: does an omitted key inherit the shared block (convenient) or mean "none" (explicit)? Inheriting matches current behavior and is the smaller change;nullwould mean "explicitly none".Also: the documented schema is incomplete
searchControlsparameters do not share one shape. Observed across 15 agent records:hitsPerPage,pageexposed,default,constraint: {min, max}attributesToRetrieve,responseFieldsexposed,default: [],constraint,mergedistinctexposed,default(boolean) — noconstraint, nomergefacetsexposed,default: []— noconstraint, nomergequery,customconstraintappears only on the numeric parameters,mergeonly on the two list-valued ones. Any validation or docs work should not assume a uniform shape. The README'ssearchControlssection (#8) predatesdistinct/facetsbeing observed and is worth extending.mergesemantics are still unknown —nullin every record seen.