Foundry Iq Grounding

Default foundry-agentic-loop grounding uses:

1. GitHub Copilot SDK hosted agent running on Foundry hosted agents and exposing the Responses API by default.
2. Foundry Skills API for behavioral instructions; the agent downloads governed skill versions into a writable temp directory at runtime.
3. One Foundry IQ knowledge base exposed through a Foundry toolbox connection/tool, typically a CognitiveSearch or Foundry IQ grounding connection backed by Azure AI Search.
4. One governed Foundry toolbox MCP endpoint as the only runtime tool and grounding surface the agent calls.

The hosted agent should not import azure-search-documents, instantiate Search clients, or call Foundry IQ retrieval APIs by default. It bridges the toolbox MCP endpoint, lets the toolbox broker grounding/tool identity, and treats the toolbox response as the source of answer evidence and citations. Direct Search or Foundry IQ calls belong only in provisioning, ingestion, or the explicitly documented diagnostic escape hatch below.

No-bypass rule

Every enterprise answer flows through the toolbox-hosted Foundry IQ grounding tool. The app and agent must not issue ad hoc Azure AI Search queries that sidestep the knowledge base, toolbox governance, or citation contract. Direct in-code retrieval belongs only in the escape hatch.

Grounding identity

The primary toolbox path is brokered:

Generated plans should make the brokered toolbox/tool identity path the default. Runtime instance managed identity Search Reader is not part of the baseline; add it only when direct retrieval is explicitly selected for troubleshooting or unsupported-tool scenarios.

The connection’s auth mode decides who calls Search: a ProjectManagedIdentity connection calls as the project’s managed identity (one validated build needed Search Index Data Reader plus Search Service Contributor on it). When proving least privilege by removing a role, wait past the connection’s token cache before trusting continued access.

Citations and refusal

Return source document, section, and anchor/chunk id for every grounded claim. Rebuild each citation (title, section, anchor, non-routable source URI) from a retrieved document that survived filtering; never pass through provider Search URLs or citation fields the model wrote. Treat “answer with zero citations” as a refusal in the API contract.

Refusal must be deterministic. Prefer a structural signal from the grounding tool - no citations survived retrieval / reranking - rather than string-matching model prose or trusting a model-reported refusal flag. Probe raw retrieval with one supported and one unsupported query first: a toolbox Search tool can return low-scoring documents instead of an empty list. If the toolbox exposes a reranker or relevance threshold, keep it environment-configurable per corpus and apply it before synthesis so weak matches become empty evidence. Otherwise filter the tool’s structured documents by an environment-configured minimum score in the agent, reject malformed scores, and refuse when none survive.

Runtime validation

Post-deploy validation must invoke the deployed hosted agent and cover:

1. Known answer - a supported question returns the expected grounded claim.
2. Citation correctness - every supported claim cites the expected source, section, and anchor/chunk.
3. Freshness - newly ingested or updated source content becomes retrievable within the documented ingestion window.
4. No-supported-source refusal - an unsupported question returns the exact deterministic refusal with no fabricated citation.
5. Retrieval telemetry - logs/traces show the toolbox grounding call, result/citation counts, latency, and refusal reason; runtime logs show no direct Search client calls.

If a known-answer query refuses with empty citations, inspect the toolbox call result and agent logs for brokered identity, role assignment, ingestion, or retrieval failures before tuning prompts.

Escape hatch: direct in-code retrieval

Use direct in-code Search / Foundry IQ retrieval only when the toolbox path cannot support a required diagnostic or unsupported preview capability. Record it in docs/spec.md (SDD) or the root README.md (rapid), isolate it from the default agent runtime, and remove or disable it after the diagnostic is complete.

Escape-hatch implications:

• Add the direct retrieval SDK dependency only in that variant; do not include azure-search-documents in default hosted-agent dependencies.
• The call authenticates as the hosted-agent runtime instance managed identity, not agentIdentityId.
• Grant Search Index Data Reader to the runtime instance identity in a reproducible postdeploy hook because Bicep cannot assign a role to an identity that does not exist until the agent is deployed.
• Validate both auth paths if the app also runs direct retrieval in-process; the backend app identity and hosted-agent runtime identity need separate Search access.

Common direct-retrieval APIs include KnowledgeAgentRetrievalClient and SearchIndexKnowledgeSourceParams. Keep examples and troubleshooting for those APIs in this escape-hatch section so they are not mistaken for the primary architecture.

Source

• Use skills with Microsoft Foundry agents (preview) - azd (opens in a new tab)
• Curate intent-based toolbox in Foundry (preview) (opens in a new tab)
• Foundry hosted agents (opens in a new tab)