Setting the file. One moment.
Subchapter 10.53
helpers/kb-contracts.mdMarkdown8 KBView on GitHub
Use for KB creation/reuse or the explicit model-free agent transition. The KB owner resolves goals, source readiness, access and costs; common contracts govern approval and execution. No helper source inspection, hand-built /models or hash scripts on the normal path. Reuse supplied choices instead of asking another questionnaire.
desiredpython helpers/search_reconcile.py --plan <kb-intent.json>Closed UTF-8 input, at most one MiB:
{"schema_version":"1.0","endpoint":"https://svc.search.windows.net","name":"docs-kb","owner":"operator@example.com","source_name":"docs-file","api_version":"2026-08-01-preview","reasoning_effort":"minimal","output_mode":"extractiveData"}All shown fields are required. name/source_name are exact names, not patterns;
owner is workflow metadata, not wire data. Names are URL-encoded, never code.
action defaults to create-or-reuse. Renaming after collision needs approval.
| Choice | Supported shape |
|---|---|
| API | 2026-04-01 for Blob minimal/extractive; 2026-08-01-preview for File/ADLS, reasoning/synthesis or agents |
| Reasoning/output | Preview minimal/low/medium: extractiveData or answerSynthesis; GA minimal/extractive only |
| Model | Omit/null for minimal/extractive; one explicit model below for low/medium or synthesis |
| Optional text | description, retrieval_instructions, answer_instructions: text/null, each at most 4096 characters; instructions preview-only |
| Optional controls | Existing closed data_movement, rbac, network objects from common contracts |
No implicit API/mode/model choice, escalation or CU/vector inference. Source processing and embeddings remain unchanged. Unknown fields and invalid choices block before authentication. No keys, secret environments, model provisioning, network/RBAC changes or model calls.
Use resolved deployment/model choices, not guesses or a hardcoded default:
{"schema_version":"1.0","endpoint":"https://svc.search.windows.net","name":"docs-kb-synthesis","owner":"operator@example.com","source_name":"docs-file","api_version":"2026-08-01-preview","reasoning_effort":"low","output_mode":"answerSynthesis","model":{"endpoint":"https://models.services.ai.azure.com","deployment":"chat-deployment","model":"gpt-4.1-mini","auth":"system-assigned","prerequisites":{"deployment":"<verified deployment/model reference>","identity":"<verified Search identity/role reference>","network":"<verified reachability reference>"}}}model accepts only those five fields. Prerequisites are nonempty text, at most
4096 characters each: owner attestations, not helper proof of capacity/readiness/access.
Use a supported Azure OpenAI chat model, exact public-cloud account endpoint and deployment.
The Search system identity needs model access. CU/embeddings are not KB chat.
For medium or minimal synthesis, change reasoning_effort accordingly; retain
the model. Minimal synthesis adds model cost without query planning; use intents,
not messages, for retrieval. Never auto-escalate or change extractive defaults.
The helper generates the complete wire definition, including:
{"name":"docs-kb-synthesis","knowledgeSources":[{"name":"docs-file"}],"retrievalReasoningEffort":{"kind":"low"},"outputMode":"answerSynthesis","models":[{"kind":"azureOpenAI","azureOpenAIParameters":{"resourceUri":"https://models.services.ai.azure.com","deploymentId":"chat-deployment","modelName":"gpt-4.1-mini","authIdentity":null}}]}No apiKey. Only minimal/extractive omits models. GA omits preview fields/models.
New artifacts bind
kb_plan_version: "1.0" and kb_model (null or the selected choice) to that wire
definition. Existing approved artifacts retain their fingerprints; preview
minimal/synthesis is now admitted with one model.
Masked/nonempty keys or a different model identity in KB readback block; they
cannot be hidden by generic definition normalization.
Only selected Search GET knowledgesources('{source}') and
GET knowledgebases('{name}'), using the requested API and signed-in CLI token.
Source GETs bracket KB observation; existing KBs are reread for ETag/definition
stability. Three GETs for an absent KB, four for existing; no resource enumeration,
status polling, uploads, retrieval, PUT/PATCH/DELETE or writes to local artifacts.
These observations are not locks or ingestion/retrieval proof.
The source must exist and return the exact selected File/Blob/ADLS definition.
The helper derives verified_source name/normalized definition digest from
those reads; never supply or fabricate it in the intent. Finish source-owner
readiness and prerequisite verification before mutation approval.
Exit 0: status: planned, execution_input, plan_fingerprint,
approval_summary, read request IDs and writes_performed: [].
Save only execution_input in a private UTF-8 JSON file. It already contains
the complete plan and computed fingerprint, with approval.confirmed: false.
Do not wrap it again, edit its generated body or calculate a fingerprint.
Summaries omit prerequisite references; retain private artifact data privately.
An exact existing KB is observed reuse, not a prediction: stable name/definition/
ETag, action: reuse, execution_required: false,
mutation_approval_required: false. Do not execute an unapproved envelope just
to repeat this read-only verification. Continue authorized retrieval; ingestion
and retrieval remain explicitly unverified by planning.
Otherwise present concrete actions/source/mode/model, access, cost/data movement,
acceptance and cleanup. An already-confirmed concrete plan is not a reason to
repeat choice questions; confirm any material difference before proceeding.
Only actual approval of the unchanged generated plan permits setting its existing
approval.confirmed to true; preserve the supplied fingerprint. Tool permission,
bootstrap consent or a proposed future source does not establish that approval.
The planner never infers consent from the input.
python helpers/search_reconcile.py --input <approved-envelope.json>Apply freshly verifies the source binding, conditional create or current ETag
update, exact readback and keyless model auth. Source/KB drift blocks; regenerate
the proposal and review changes, never hand-repair nested JSON/hashes.
Exit 2 is structured blocked/no-write; post-write failures are 3/partial
with retained ownership. No automatic retries of writes or cleanup.
An updated KB remains pre-existing/reused, including failed or ambiguous
post-write verification; an update never establishes creation ownership.
This is optional KB-side model-free normalization, not an MCP prerequisite.
Never downgrade a valid reasoning/synthesis KB to connect an agent.
For the owner’s existing model-free GA/extractive KB transition, set
action: agent-minimal-transition, preview API, minimal effort and extractive
output. Omit model and optional text changes. The source/KB must exist and match.
Existing absent/minimal/low effort is allowed only without models and synthesis;
the summary discloses prior mode fields, including an observed default low.
Only the two preview mode fields change, guarded by the current ETag; unrelated
fields/models remain. The update needs separate concrete approval.
An equivalent KB is reuse. Verify actual agent MCP invocation separately from GA REST retrieval.
Authorities: failure/conflict/uncertainty only. preview KB wire/model fields (opens in a new tab), KB creation and model access (opens in a new tab).