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-toolbox.md

Foundry toolbox

Reference for the foundry-agentic-loop skill: how a solution's skills, MCP tools and grounding reach its hosted agents through one Foundry toolbox. microsoft-foundry owns the command surface and tool types (its toolbox guide), azd-layout.md owns the declarative services, and copilot-sdk-with-toolbox.py is the reference consumer.

Model

  • A toolbox bundles project connections, skills and tools behind one MCP endpoint. Versions are immutable: every change creates one, and only the first becomes the default automatically.
  • A skill is a SKILL.md (front matter with name and description, then Markdown instructions) versioned in the project. Skills are in preview.
  • The consumer URL <project>/toolboxes/<name>/mcp?api-version=v1 always serves the default version, so promoting a toolbox version reaches agents without a redeploy. The developer URL .../toolboxes/<name>/versions/<v>/mcp?api-version=v1 pins one version.
  • Attached skills arrive as MCP resources (skill://<name>/SKILL.md) that follow the skill's default version unless the toolbox pins version. The agent writes them under the temp directory per request, because hosted containers are read-only except /tmp; the agent image never copies skills/.

Author

  1. Write each skill at skills/<name>/SKILL.md; its front matter name matches the folder.
  2. Build or reuse each MCP server (FastMCP over streamable HTTP, generated with python-mcp-server-generator from build-skills-catalog.md). Reach servers through connections, never hard-coded URLs or secrets. Expose Foundry IQ grounding through the toolbox too (foundry-iq-grounding.md).
  3. Compose one toolbox per capability set: skills[], connections[] (connections must already exist), and connectionless built-ins such as web_search or code_interpreter under tools[]. At most one tool may be unnamed: name built-ins with name and MCP tools with server_label. Before exceeding about five tools, add toolbox_search_preview, which counts as the unnamed tool.
  4. Agents that load skills run on the Copilot SDK and consume the toolbox like the reference agent. MAF agents follow microsoft-foundry's toolbox-in-hosted-agent guidance.

Publish

  • SDD: declare azure.ai.skill, azure.ai.connection and azure.ai.toolbox services (azd-layout.md). Deploy publishes them in uses order and writes TOOLBOX_<NAME>_MCP_ENDPOINT; map it to the agent's TOOLBOX_ENDPOINT. Without approval to upgrade older extensions, use the ordered postprovision fallback in the same file.

  • Rapid: publish with the CLI against the selected project (azd ai project set <project-endpoint>):

    azd ai skill create claims-policy --file skills/claims-policy/SKILL.md --no-prompt   # later versions: azd ai skill update
    azd ai toolbox create claims-tools --from-file toolbox.yaml --no-prompt              # writes TOOLBOX_CLAIMS_TOOLS_MCP_ENDPOINT
    
    # toolbox.yaml
    description: Claims tools
    skills:
      - name: claims-policy          # omit version to follow the skill's default
    connections:
      - name: claims-mcp-conn        # RemoteTool (MCP)
      - name: policy-search          # CognitiveSearch needs index
        index: policies
    tools:
      - type: web_search
        name: web
    
  • Change: azd ai toolbox connection add|remove and azd ai toolbox skill add|remove each create a version without changing the default; promote or roll back with azd ai toolbox publish <name> <version>. Connectionless built-ins can't be added later: recreate the toolbox with the full set. azd ai skill update <name> --set-default-version <v> rolls a skill without uploading content.

  • Extensions: azure.ai.toolboxes, azure.ai.skills and azure.ai.connections, at the minimum versions in azd-layout.md.

Consume

Follow copilot-sdk-foundry.md and the reference agent:

  • Keep the URL in TOOLBOX_ENDPOINT, never a FOUNDRY_* name, which the platform overwrites. If the written URL pins /versions/<v>/, redeploy the agents that use the toolbox after it changes; record which form each agent uses.
  • Send a token for https://ai.azure.com/.default on every request (cognitiveservices tokens get 401), Foundry-Features: Toolboxes=V1Preview, and the caller's x-agent-foundry-call-id when present.
  • initialize is optional; prompts/list and ping are unsupported. MCP-sourced tools are named <server_label>___<tool>.
  • The proxy does not enforce require_approval: approve tools in the agent's permission handler.
  • A -32006 error wrapping CONSENT_REQUIRED carries a per-user consent URL for an OAuth connection: surface it to the caller instead of retrying.
  • An HTTP 403 from the toolbox means the caller lacks Foundry User on the project; a -32007 error wrapping 403 comes from the MCP server's own auth.

Verify

  • tools/list returns the expected tools and resources/list the expected skill:// entries.
  • Hosted logs show skills written under the temp directory, and answers show each skill applied.
  • Record the toolbox name, its published default version and the URL form in the root README.md (rapid) or docs/implementation.md (SDD).

Sources: microsoft-foundry toolbox and skills guides; Toolbox; Skills.