Setting the file. One moment.
Subchapter 10.72
knowledge-bases/retrieve.mdMarkdown8 KBView on GitHub
One KB query; opt-in offline/agent audits.
No creation/repair/sync/connection/RBAC/effort changes or cleanup. Failures/drift: Diagnose. Never return credentials.
Standalone: Search REST retrieve with Entra auth, no MCP/agent required.
Check CLI/sign-in; preserve azure-authentication-failed or azure-cli-unavailable.
Never install/switch identity implicitly. Capture privately:
az account show --output json; for a user,
az ad signed-in-user show --query id --output tsv (no subscription flag).
Never request tokens/credentials/keys in chat. Missing verified host auth blocks; pasted tokens aren’t a remedy.
Resolve prompt/session/workspace/exact Azure readback; one focused question. Label evidence. Discovery needs no approval; run only authorized queries. Retrieval can invoke models/cost/data movement. Silence never selects identity/permissions/extra queries.
| Input | Why needed | Required? | Discovery order | Safe default | If missing or unanswered | Reconfirmation trigger |
|---|---|---|---|---|---|---|
| Search/base ID/endpoint | Target | Yes | Prompt/session/GET | None | Ask ambiguity | No writes |
| API/definition/mode | Shape | Yes | Creation/GET | None | Ask/block | None |
| Query | Retrieval | Yes | Prompt | None | Ask | None |
| Caller | Access | Yes | Identity GET | None | Block | None |
| Forwarding | Access | If needed | Source/base GET | None | Block | None |
| Original identity | Citations | Opt-in audit | Inventory | None | Unverifiable | None |
| Unrelated question | Abstention | Opt-in audit | Authorized evidence | None | Not tested | None |
| Agent/tool identity | Tool proof | Audit | GET | None | Block | None |
GET base/source definitions; connection binding is not definition evidence.
Use the API from creation evidence or ask before GET; it isn’t a returned field.
GA 2026-04-01 is extractive. Preview minimal can synthesize with a configured
KB chat model; still use intents. Preserve observed output/effort.
KB/model changes: KB setup selects chat model and separately approved deployment/configuration. No retrieval-time mutation or fallback to minimal.
Inspect source ingestionPermissionOptions in ingestion parameters; unknown
posture blocks. Permission-enabled retrieval requires per-request
x-ms-query-source-authorization, audience https://search.azure.com/.default,
separate from service auth. Forward only the verified same signed-in user’s
token; otherwise permission-forwarding-unavailable. Never persist/log tokens;
do not pass the caller token as a CLI argument. Never query unfiltered as fallback.
State target/API/mode, caller/query/forwarding, citation identity and optional
audit; mutation: none.
No mutation approval gate. Confirm acceptance questions not already authorized; do not auto-run queries. Writes need the owner’s separate plan and confirmation.
None; never retry through another resource.
Standalone: use selected endpoint/name/API and observed effort. Query is JSON
data, never shell text. GA/preview minimal use intents; preview low/medium uses
messages. Never override mode/effort/models/source selection.
Invoke by loaded skill path, not customer project; never read/copy source or replace:
python "<skill-dir>/helpers/knowledge_base_retrieve.py" --input "<request.json>"Definition GET, UTF-8 JSON:
{"operation":"get-knowledge-base","endpoint":"https://<service>.search.windows.net","name":"<kb>","api_version":"2026-08-01-preview"}Read selected sources with operation: get-knowledge-source and exact name.
Helper escapes OData; do not pre-encode. Inspect definitions/permissions; use
observed effort and explicit forwarding:
{"operation":"retrieve","endpoint":"https://<service>.search.windows.net","name":"<kb>","api_version":"2026-08-01-preview","effort":"minimal","query":"<question>","forward_permissions":false}Use the selected API. Closed inputs: no approval envelope/fingerprint/credentials.
Set forward_permissions: true only for the verified same signed-in user when
the source requires forwarding. The helper additionally checks CLI user type,
then acquires the token in memory. It never accepts a caller token as input.
Helper retains HTTP status/request ID, disables redirects, bounds bytes, never retries.
Exit 0: status: response-received, http_status, request_id, response_body;
not grounding/end-to-end proof. Exit 2: status: blocked, first code/status/request ID,
no writes/ownership/cleanup, even for ambiguous POST. No tokens/raw diagnostics.
REST results contain response, references, and optional activity; they are
not MCP result.content[]. Parse all returned text blocks and reference IDs.
Activity errors or missing grounding are incomplete, not success. HTTP 206
is rejected even with valid-looking content. No-support is valid; never fill
gaps from general knowledge.
Requested agent audits: invoke supported host; verify native per-KB
knowledge_base_retrieve call. Missing connection:
knowledge-base-mcp-endpoint-unavailable; do not substitute REST as agent proof.
Never substitute a generic index query or the generic Azure MCP Server
search_* tool group for either path.
For ordinary retrieval, check the requested answer, native references and activity; missing grounding/errors remain incomplete. No extra questions or retained bundle.
Offline audit is opt-in; default audit_status: not-requested.
No hand-authored Q&A required. Propose title/content questions only from authorized
content, not structural assessment. Approve proposed queries before execution;
never derive ground truth from audited answers. No samples/questions: defer audit.
After opt-in, follow the paired
audit contract:
python "<skill-dir>/helpers/retrieval_verify.py" --input "<private-bundle>/audit.json".
No custom parsing/raw dumps/reretrieval; exit 0 isn’t acceptance. Skipping is not a pass.
Audit original File path plus file ID or Blob/ADLS URL/path plus ETag/version;
native docName/blobUrl lack File ID/ETag: report unverified, not chunk-ID proof.
For synthesis audits, apply the shared
semantic abstention criteria,
honoring any explicit exact-output contract.
GA/preview extractive audits require no supporting extracts: do not invent a
synthesized I don't know. Structural absence isn’t semantic abstention.
Recheck identities; require
before_after_snapshot_equal: true.
Denial is inaccessible, not absence. Diagnose empty/wrong/stale output without mutation. No fabricated citations/success; failures create no ownership.
Not applicable. No resources or cleanup approval.
Verified: status: completed, outcome: knowledge-base-retrieval,
mutation: none, KB/source IDs/endpoint/API/mode, preview: true|false,
caller/forwarding, requested answer/citations, activity/tool evidence, warnings/latency,
audit_status, abstention tested/evidence and before/after equality when audited.
Otherwise return status: blocked, blocked_at, first status/message/request ID,
missing/conflicting input, safe next decision, writes_performed: [], no new
ownership and cleanup: not-applicable. Never report unavailable evidence as
verified or include credentials/raw diagnostics.
Authorities: failure/conflict/uncertainty only.