Repository navigation
config model cannot express per-index searchControls (or the full searchControls schema) #16
Description
Problem
build_tool() accepts a single searchControls key and copies it to every index:
if "searchControls" in config:
for idx in tool["indices"]:
idx["searchControls"] = config["searchControls"]The API stores searchControls per index, and the dashboard writes them that way. Observed on agent 47d6a15c:
| Index | searchControls |
|---|---|
tcg_cards_msft-build-2026 |
set |
tcg_cards_msft-build-2026_price_asc |
null |
tcg_cards_msft-build-2026_price_desc |
null |
There 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 searchControls per-index in the payload. The config model is still one shared block.
Suggested fix
Accept searchControls on 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; null would mean "explicitly none".
Also: the documented schema is incomplete
searchControls parameters do not share one shape. Observed across 15 agent records:
| Parameter | Fields |
|---|---|
hitsPerPage, page |
exposed, default, constraint: {min, max} |
attributesToRetrieve, responseFields |
exposed, default: [], constraint, merge |
distinct |
exposed, default (boolean) — no constraint, no merge |
facets |
exposed, default: [] — no constraint, no merge |
query, custom |
never observed non-null |
constraint appears only on the numeric parameters, merge only on the two list-valued ones. Any validation or docs work should not assume a uniform shape. The README's searchControls section (#8) predates distinct/facets being observed and is worth extending.
merge semantics are still unknown — null in every record seen.
Activity
docs: complete the searchControls parameter table (#21)
chuckmeyer commentedon 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.chuckmeyer commentedon Aug 27, 2026
Closing manually — the
Closes #16keyword in #21 did not fire on merge. The capability half shipped in #19/#20 and the documentation half in #21, with two corrections following in the PR above.