AGENTIC MEMORY

Skills

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

← Back to Skills

foundry-agentic-loop

Build agentic solutions on Microsoft Foundry, GitHub and Azure: hosted agents, toolbox tools and skills, Foundry IQ grounding and a React/FastAPI app. Three modes: rapid prototyping in an existing Foundry project; spec-driven development (SDD), where the foundry-agentic-loop-workflow runs Specify, Implement, Verify and Deploy to create the Foundry project and deploy with azd, or one phase runs alone; and Improve, which refines this skill and the workflow from past runs. Use for Agentic Loop requests and canvas actions, or end-to-end agent solutions from architecture to Azure deployment. Not for isolated Azure administration or unrelated UI edits.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

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 github--foundry-agentic-loop at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, 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 · 41

references/foundry-iq-grounding.md

Foundry IQ grounding

Reference for the foundry-agentic-loop skill: how a GitHub Copilot SDK hosted agent grounds enterprise answers through a Foundry IQ knowledge base by consuming a governed Foundry toolbox MCP endpoint. foundry-agentic-loop decides that grounding is Foundry IQ; this file holds the access path, identity, refusal, validation, and escape-hatch guidance. Defer index/knowledge-base provisioning and role selection to microsoft-foundry and its rbac sub-skill.

Primary pattern: hosted agent + toolbox MCP

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:

| Retrieval path | Authenticates as | Grant needed | | --- | --- | --- | | Toolbox MCP grounding tool - a Foundry IQ / CognitiveSearch connection attached to the toolbox | Hosted-agent agent identity (agentIdentityId) via Agent Service-brokered tool identity | Search / knowledge-base data-plane role on agentIdentityId; repeat after publish because agent identity can change | | Direct in-code retrieval escape hatch - agent code calls Search / Foundry IQ APIs with DefaultAzureCredential | Hosted-agent runtime instance managed identity | Search Index Data Reader on the Search service, granted in postdeploy after the runtime identity exists |

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