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

helpers/contracts.md

Deterministic helper contracts

Read before planning/approval; scope discovery. Owners assess content/ambiguity/roles/consent. Private output. Inspect source only on blocked/partial.

Common envelope and process contract

UTF-8 JSON:

{"schema_version":"1.0","plan":{},"approval":{"confirmed":true,"fingerprint":"sha256:<canonical-plan-digest>"}}

Canonical JSON: UTF-8, key-sorted, ASCII-escaped, compact. Approve the unchanged plan; helpers verify fingerprints. Exclude credentials, tokens, keys, SAS, passwords, content and secret-bearing connection strings. Use CLI tokens. File CU: MI or approved ARM/ENV; never retain secrets. Envelope, approval, plan, nested controls and file records are closed schemas: undeclared fields block before authentication. desired remains a complete service body. Results recursively redact secret fields. Azure Policy evaluation belongs to the creation owner, not these helpers. Bootstrap: no preflight policy reads. Bind known requirements and child fingerprint in the parent plan; no policy precheck. Never add undeclared policy/tag fields; if required settings cannot reach the supported request body, return azure-policy-setting-unsupported before creation.

Mutation commands emit compact JSON to stdout: exit 0 is completed, 2 no-write blocked, 3 written/ambiguous partial. Preserve JSON/exit status. Read same identity after ambiguous writes. Unacknowledged Search creates stay partial: resources_remaining.reused, not owned. Otherwise prove approved state/absence.

429: read recovery, plus File queue retry below.

File/Blob/ADLS and Search apply: _progress.py: stderr JSONL; --no-progress disables. Planning/discovery stays quiet. Libraries: progress=Progress("<workflow>"); children share one terminal event. Bounded activity/remaining checks, elapsed seconds and counts. Same stage: once/second; transitions/terminal: immediate. File POST: five-second heartbeat, no polling/ETA; metadata proves File ingestion; cycle updates aren't unique documents; ARM readiness isn't KB/retrieval/data-plane proof. I/O failure: progress-output-failed warning; primary failures/execution unchanged. Failed native stderr drains to null at shutdown; custom sinks untouched. Final JSON is authoritative.

File source application

python helpers/file_source.py --plan request.json: read-only; unapproved execution_input/approval_summary; exit 0 is planned, not readiness. See request/example. Require extraction_mode; optional embeddings are independent. Planning: no bootstrap/roles/uploads/cleanup/approval; owner-owned requirements. Fresh exact reuse sets execution_required/mutation_approval_required false; no approval/execution. Create: approve the unchanged envelope:

python helpers/file_source.py --input approved.json --cleanup-receipt-dir <private> --upload-receipt-dir <journal>

Require operation: reconcile-and-ingest, cleanup_approved: false, owner, source and ingestion. Children target the same endpoint/name/API/owner. Validate both before mutation; reconcile before upload/readback. ACKs/journal: resume. Reuse requires exact markers, never new files or per-file cleanup. Parent/approved upload-only routes. source uses the reconciliation shape with kind: "file"; ingestion:

{"operation":"ingest","endpoint":"https://svc.search.windows.net","name":"src","api_version":"2026-08-01-preview","local_root":"<root>","service_tier":"basic","extraction_mode":"minimal","owner":"o@x","cleanup_approved":false,"files":[{"path":"guide.txt","size":123,"mtime_ns":1700000000000000000,"sha256":"sha256:<64-hex>","media_type":"text/plain"}],"inventory_digest":"sha256:<64-hex>","expected_server_inventory_digest":"sha256:<64-hex>"}

Search resource reconciliation

python helpers/search_reconcile.py --input <approved-envelope.json>

Require operation: reconcile, outcome, resource_type, endpoint, name, api_version, action, complete approved desired, owner, and cleanup_approved: false. Use action: create, or approved action: update with expected_etag. Exact existing state is zero-write.

Blob/ADLS plans also require source_evidence with verified: true and an inventory_digest. ADLS requires path_verified: true, acl_verified: true. These attest reconciliation, not evidence collection/readiness: apply through the Blob parent. File standard: ai_services_managed_identity or ai_services_key_acquisition via File parent, or existing ai_services_api_key_environment.

KB --plan: intent/wire/approval; save unapproved execution_input, never hand-build bodies/hashes. verified_source binds verified: true, name, normalized definition_digest; fresh same-API GET must match before create/update/reuse. GA omits preview fields/models. Low/medium needs a separate chat model; model-free agent retrieval requires preview minimal/extractive.

For cleanup, plan, then use the same executor. Bind operation: delete, plan_kind: cleanup, cleanup_approved: true, expected_etag, and owned_definition_digest. Recheck ownership; verify absence.

Blob/ADLS source application

Blob/ADLS alone loads folder scope/bounds/drift/cleanup. blob_source.py --discover inventories; --plan builds unapproved artifacts or verifies approval-free reuse; --input applies the approved parent and monitors ingestion. Search reconciliation alone never proves Blob readiness.

File ingestion internals

file_source.py invokes this child after validating both plans. Standalone CLI never authorizes new uploads.

Reject path/inventory/extraction/server-state/marker drift. Sequential uploads; one final inventory. Only per-file 415 permits continuation; systemic failures stop. File 429: one bounded retry. POST: 180s; reads: 60s. Timeout/409/5xx: read proof, never POST replay. Metadata proves ingestion, not retrieval; status-only ACKs remain pending. Never return bytes/local root.

Existing Prompt Agent fallback

Only for unavailable MCP/missing connection/version operations; never authorization denial/conflicting state:

python helpers/prompt_connect.py --input <approved-envelope.json>

The plan requires operation: connect, sdk_major: 2, exact project resource ID and matching endpoint identity, connection, agent, rbac_verified, allowed_tools: ["knowledge_base_retrieve"], require_approval: "never", permission_forwarding, owner, and cleanup_approved: false. The fallback defines --plan: intent yields unapproved execution_input + summary; hashes stay internal. Legacy inputs omit dependency/version snapshots. Approve grounding changes. Forwarding is either {"mode":"not-applicable"} or {"mode":"structured-input","name":"search_auth_token"}. Reuse one complete match; multiple matches block. ARM uses Microsoft.CognitiveServices/accounts/projects/connections. Optional boolean connection.is_shared_to_all defaults to true. Fallback defines normalization/bounded warnings for creation, ambiguous-write recovery/reuse. agent_invocation: not-run isn't E2E proof.

Prompt cleanup (planner above blocks unproven connection consumers):

python helpers/prompt_cleanup.py --input <approved-envelope.json>

Bind operation: delete, plan_kind: cleanup, cleanup_approved: true, sdk_major: 2, exact project identity and agent/connection with run_owned: true, exact identity and owned_definition_digest. Connections also bind expected_etag. Delete version before connection; verify absence; preserve prior versions/project/model/KB/roles.