AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

foundry-iq

Foundry IQ knowledge bases. WHEN: make local or Blob documents searchable; create/diagnose KBs; triage unsupported connectors or multi-source KB creation/reconfiguration (even with classic-search terms); connect existing KB to agents (including multi-source KBs); create/reuse a Search service; retrieve from an existing knowledge base with citations; no brand words needed. Read its procedure before query/target questions. NOT: other KB providers, repository-file search, classic Azure AI Search index/query/app work with no Foundry IQ KB or connector request, generic agent creation.

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--foundry-iq at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 45

knowledge-bases/retrieve.md

Retrieve from a knowledge base

When to use

One KB query; opt-in offline/agent audits.

Do not use

No creation/repair/sync/connection/RBAC/effort changes or cleanup. Failures/drift: Diagnose. Never return credentials.

Inputs and discovery order

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 |

Decisions

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.

Proposed plan

State target/API/mode, caller/query/forwarding, citation identity and optional audit; mutation: none.

Confirmation

No mutation approval gate. Confirm acceptance questions not already authorized; do not auto-run queries. Writes need the owner's separate plan and confirmation.

Mutation

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.

Verification

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.

Failure and partial completion

Denial is inaccessible, not absence. Diagnose empty/wrong/stale output without mutation. No fabricated citations/success; failures create no ownership.

Cleanup

Not applicable. No resources or cleanup approval.

Return contract

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.

References

Authorities: failure/conflict/uncertainty only.