AGENTIC MEMORY

Skills

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

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

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--microsoft-foundry 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 · 151

foundry-agent/toolbox/toolbox.md

Foundry Toolbox — Concept, API Shape & Schema

Understand

What a toolbox is

A toolbox is a managed Foundry resource: define a curated set of tools once, manage them centrally, and expose them through a single MCP-compatible endpoint any agent can consume. The platform handles credential injection, token refresh, and policy enforcement at runtime.

✅ Recommended: a toolbox is the best way to connect tools to a Foundry agent — it centralizes auth (bearer tokens, refresh, OAuth consent, per-user passthrough), enforces policy, and lets you reconfigure tools without changing agent code.

  • Build — select tools, configure auth centrally, publish a reusable toolbox.
  • Consume — connect any MCP-compatible runtime (Microsoft Agent Framework, LangGraph, GitHub Copilot, Claude Code, Copilot Studio, custom code).

For consuming from hosted-agent code, see use-toolbox-in-hosted-agent.md.

Build & use

Create & use a toolbox (happy path)

🚦 Before creating a toolbox/connection, read the boundary rules in create-hosted.md → Toolbox creation boundary.

Prerequisites

  1. RBAC — the calling identity (you, and the agent identity at runtime) needs Foundry User on the project. Grant at project scope if missing.

  2. CLI extension — install once:

    azd extension install azure.ai.toolboxes
    

The flow

Using the azd ai CLI:

  1. Create the connection (azd ai connection create ...).
  2. Create the toolbox (azd ai toolbox create) or add to an existing one (azd ai toolbox connection add).
  3. If you added to an existing toolbox, promote the new version (azd ai toolbox publish <name> <version>) — create auto-publishes its first version; later mutations don't (see Versions).
  4. Read the endpoint (azd ai toolbox show <name> --output json).
  5. azd env set TOOLBOX_ENDPOINT "<endpoint>".
  6. Reference it in the agent service's environmentVariables in azure.yaml.
  7. azd deploy.

Each tool type has its own flow — pick your tool in Supported tool types and follow its Setup guide. Full CLI surface: toolbox-azd.md.

Supported tool types

The tool type values supported inside a toolbox version. mcp's first four auth modes work for any MCP server; the last two are catalog-only (Foundry pre-wires the app/broker).

| type | Tool | authType | Connection? | Setup guide | |---|---|---|---|---| | mcp | Remote MCP server — no auth (public) | None | No | tool-mcp-noauth.md | | mcp | Remote MCP server — static key | CustomKeys | Yes (key connection) | tool-mcp-key-auth.md | | mcp | Remote MCP server — OAuth, custom app (BYO); runs as the user | OAuth2 | Yes (client_id / client_secret + reply URL) | tool-mcp-custom-oauth.md | | mcp | Remote MCP server — agent identity / project MI; runs as the agent | AgenticIdentityToken / ProjectManagedIdentity | Yes (audience + RBAC on the target) | tool-mcp-agent-identity.md | | mcp | Catalog only — OAuth, Foundry-managed connector; consent once, no BYO app | OAuth2 (Foundry-owned) | No (Foundry brokers it) | tool-mcp-managed-oauth.md; foundry-tool-catalog.md | | mcp | Catalog only — Microsoft first-party pass-through; caller's identity forwarded, no consent | UserEntraToken | Yes (via --audience) | tool-mcp-user-entra-token.md; foundry-tool-catalog.md | | openapi | REST API via an OpenAPI 3.x spec | — | Conditional (connection needs project_connection_id; managed_identity uses project MI + audience) | tool-openapi.md | | a2a_preview | Call another Foundry agent as a tool | — | Optional | tool-a2a.md | | web_search | Web search (basic Bing; custom_search_configuration for Custom Search) | — | No (basic); Yes for Custom Search | tool-web-search.md | | azure_ai_search | Azure AI Search index | — | Yes (Search service connection) | tool-azure-ai-search.md | | code_interpreter | Sandboxed Python execution | — | No | tool-code-interpreter.md | | file_search | Vector-store retrieval over uploaded files | — | No (part of the toolbox) | tool-file-search.md | | fabric_iq_preview | Microsoft Fabric data | — | Yes (Fabric IQ OAuth; tenant admin consent) | tool-fabric-iq.md | | browser_automation_preview | Browser automation | — | Yes (PlaywrightWorkspace connection) | tool-browser-automation.md | | toolbox_search_preview | Tool Search — swaps tools/list for tool_search + call_tool meta-tools | — | No | tool-tool-search.md |

Work IQ is a common Microsoft 365 MCP server with its own guide: tool-work-iq.md.

Adjacent (not a toolbox type):

  • Agent Memory — configured at the project level, separate from the toolbox. See Memory docs.
  • Routines (preview) — an agent trigger (schedule / timer / github_issue / custom). See Routines docs.

Composition rules (multiple tools in one toolbox)

At most one tool may be unnamed; name every other. See toolbox-azd.md § Multi-tool rule.

Enable Tool Search

Before adding more than ~5 tools, add { "type": "toolbox_search_preview" }. This replaces the full tools/list with two meta-tools — tool_search and call_tool — so context cost stays flat. Full behavior: tool-tool-search.md, Tool Search docs.

Versioning, endpoints & MCP protocol

Versions

  • Versions are immutable snapshots — every change produces a new version.
  • The default version is what the consumer endpoint serves.
  • The first version is auto-promoted; later ones must be promoted explicitly.

MCP endpoint URL format

| Role | Endpoint | Use | |------|----------|-----| | Consumer | {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1 | Connect agents; always serves default_version. | | Developer | {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1 | Test a version before promoting. |

?api-version=v1 is required; auth is a bearer token scoped https://ai.azure.com/.default. See mcp-protocol.md § Endpoint URL details.

MCP protocol, testing & troubleshooting

Toolboxes speak MCP (JSON-RPC 2.0 over HTTP POST). For protocol methods, tool naming, endpoint testing, and troubleshooting, see mcp-protocol.md and test-endpoint.md.

References