Mastering Toolboxes in Microsoft Foundry

When several agents - or a mix of Foundry hosted agents, Microsoft Agent Framework, LangGraph, and Copilot SDK apps - need the same governed set of tools, you don't want to re-wire those tools and their auth into every one. The pattern that scales: package the tools once behind a single versioned, governed MCP endpoint, make them discoverable, and let every runtime consume them from the same URL.

This recipe teaches that pattern with Toolboxes in Microsoft Foundry, as a reference walkthrough. The runnable core spine is short - build a toolbox version, turn on Tool Search, verify it over MCP, and consume it from Microsoft Agent Framework. Around that spine sits a catalog of every other tool type, the REST/CI path, versioning, and governance policies - optional sections you can skip on a first read.

Three pillars, all available today

Toolbox packages the full tool experience into three pillars you use together. You define a curated set of tools once, manage them centrally in Foundry, and expose them through a single MCP-compatible endpoint that any agent can consume - the platform handles credential injection, token refresh, and policy enforcement at runtime.

Because a toolbox is a managed resource, you can add, remove, or reconfigure tools without changing agent code - every agent connects to the same endpoint. Versioning gives you explicit control over when changes take effect: create and test a new version, then promote it to default; every consumer picks up the promoted version automatically, with no code changes or redeployment.

By the end, you'll be able to

• Build & curate a versioned toolbox that exposes multiple tool types behind one MCP endpoint, with per-connection identity so every consumer inherits correct, least-privilege access.
• Discover tools with Tool Search - progressive disclosure keeps a large toolbox as cheap for the model to use as a small one.
• Govern the toolbox with an RAI guardrail and a bring-your-own MCP gateway.
• Consume the same toolbox unchanged from Agent Framework, LangGraph, and the Copilot SDK.

Preview. Toolbox, Tool Search, A2A, Browser Automation, Skills, and the Work IQ / Fabric IQ tools are in preview. APIs and headers may change. Past the two required vars (PROJECT_ENDPOINT, MODEL_DEPLOYMENT), every optional section is skip-guarded - leave its env vars blank and it's skipped cleanly, so the notebook runs top-to-bottom with only a project provisioned.

1 / Prerequisites + environment

Every connection-backed tool is optional. The toolbox is created from whatever you provide; blank env vars skip their section.

Configure your environment

Set these in your shell or a local .env (loaded with python-dotenv). Only PROJECT_ENDPOINT is required to create a toolbox; MODEL_DEPLOYMENT is optional and defaults to gpt-4.1-mini (it is only used by the consumer agents in step 11).

Runtime & cost: the core spine takes a few minutes end-to-end and creates a couple of toolbox versions. Steps 11 (Agent Framework, LangGraph, Copilot SDK) invoke live web search and model inference, which bill against your Foundry project and any connection-backed tools.

# ---- Required ----
PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
MODEL_DEPLOYMENT="gpt-4.1-mini"

# ---- Optional: name of the toolbox we create/update ----
TOOLBOX_NAME="my-toolbox"

# ---- Optional: project CONNECTION IDs for the tools that need them ----
# A connection ID is the connection's name OR its full ARM resource id
# (/subscriptions/.../connections/<name>). Leave a value blank to skip that tool.
MCP_SERVER_URL=""                            # remote MCP server URL (may be APIM-fronted)
MCP_SERVER_LABEL="custom_mcp"                # label that namespaces the MCP server's tools
MCP_PROJECT_CONNECTION_ID=""                 # connection backing the MCP server (auth)
AISEARCH_PROJECT_CONNECTION_ID=""            # Azure AI Search connection (key or MI)
AISEARCH_INDEX=""                            # index name to expose
OPENAPI_PROJECT_CONNECTION_ID=""             # connection backing an OpenAPI tool (key or MI)
A2A_PROJECT_CONNECTION_ID=""                 # connection to a downstream A2A agent
A2A_ENDPOINT=""                              # optional: A2A base URL if the connection has no target
WORK_IQ_PROJECT_CONNECTION_ID=""             # Work IQ (Microsoft 365) connection (oauth2)
FABRIC_IQ_PROJECT_CONNECTION_ID=""           # Fabric IQ (Microsoft Fabric) connection (MI or oauth2)
BROWSER_AUTOMATION_PROJECT_CONNECTION_ID=""  # Azure Playwright connection (key)
BING_CUSTOM_SEARCH_PROJECT_CONNECTION_ID=""  # Bing Custom Search connection (key)
BING_CUSTOM_SEARCH_INSTANCE=""               # Bing Custom Search instance name
FILE_SEARCH_VECTOR_STORE_ID=""               # vector store id for File Search
SKILL_NAME=""                                # name of a published skill to include
SKILL_VERSION=""                             # optional: pin a skill version
RAI_POLICY_NAME=""                           # existing RAI policy for the policies section

2 / Configure clients + helpers

One AIProjectClient and one DefaultAzureCredential are reused throughout. We also define a few helpers the rest of the notebook leans on:

• env(name, required=False) - env-var lookup with a friendly error.
• skip(reason) - prints why a section is skipped and returns True, so each optional cell starts with if skip(...): ....
• mcp_token() - a bearer token scoped to https://ai.azure.com/.default, the audience the toolbox MCP endpoint expects.
• TOOLBOX_HEADERS - every call to a toolbox MCP endpoint must carry Foundry-Features: Toolboxes=V1Preview. Forgetting it is the #1 cause of 404s.
• created_resources - a tracker the cleanup section walks in reverse.

3 / Auth & identity

A toolbox tool reaches a downstream system through a project connection, and the connection's auth type decides whose identity is used. This is the single most important design decision in a toolbox - get it right and every consumer inherits correct, least- privilege access automatically.

How a hosted agent authenticates - two steps

1. Authorize the agent to the toolbox first. Before it can call the toolbox MCP endpoint at all, the hosted agent's identity must hold the Foundry user role on the project. No role → the toolbox rejects the agent. This is independent of any tool.
2. The toolbox then handles each tool's auth based on that connection's auth type:
   • For none, custom-keys, project-managed-identity, agentic-identity, and Foundry-managed oauth2, the toolbox authenticates to the tool using the connection's configured identity - the agent never sees the secret.
   • For oauth2 and user-entra-token (managed user identity passthrough), the hosted agent emits the caller / end-user token and passes it to the toolbox; the toolbox uses that token - not the agent identity - to authenticate to the tool. This is how the tool ends up acting as the real end user.

Two identities, better together

Running a toolbox behind a hosted agent puts two identities in play at once, and the platform wires them together for you:

• Agent -> toolbox (the trust boundary). The hosted agent always authenticates to the toolbox MCP endpoint with its own agent managed identity - that identity holds the Foundry user role. This is what gates access to the toolbox itself, independent of any single tool.
• Toolbox -> tool (the end-user passthrough). For oauth2 and user-entra-token connections, that same hosted agent forwards the caller's end-user Entra token, and the toolbox uses that token (OBO) to reach the downstream tool. The tool then acts as the real end user - per-user, least-privilege access with correct downstream audit.

That's the better-together story: you keep the agent's managed identity as the stable, governable boundary to the toolbox, and still get true end-user identity on the downstream data call - without writing any OAuth/token-exchange plumbing in your agent code. (For non-OBO auth types the tool runs under the connection's own identity - the project MI, an API key, or the agent's own per-project agentic-identity - and no user token is forwarded.)

Auth support is tool-type specific

Only MCP and A2A accept all six auth types (each one is defined in detail in 4e · Remote MCP server below). Every other tool type supports a narrower subset - pick a connection auth type the tool actually allows:

OAuth consent. The first call through an oauth2 connection returns a CONSENT_REQUIRED error (JSON-RPC code -32006) carrying a consent URL. Open it, consent once, then retry - we handle exactly this in the verify section.

Creating the connections (this is not an SDK-from-Python step)

A connection is a project resource an admin creates once; tools then reference it by id. You do not create connections from the toolbox SDK. The real ways to create one:

1. Foundry portal - Build -> Tools -> Connect a tool (or Management -> Connected resources -> New connection). This is the easiest path and it drives the OAuth consent UI for you.
2. Azure Developer CLI (azd) - the Foundry azd extension creates connections from the terminal or CI, e.g. azd ai connection create <name> --kind remote-tool --target <url> --auth-type <auth-type> (use --kind cognitive-search for an Azure AI Search connection). This is the source-control-friendly path.
3. Connections REST / ARM API - PUT .../projects/{p}/connections/{name} with the auth type in the body (what the portal and azd call under the hood).

The connection's auth type is chosen at creation time (narrowed per the support table above). Whatever you pick is what the tool uses at runtime - the agent code never sets auth.

The connection category depends on the tool: MCP and Fabric IQ use RemoteTool; A2A and Work IQ use RemoteA2A; Azure AI Search uses CognitiveSearch. In azd, --kind remote-tool creates a RemoteTool connection, --kind remote-a2a a RemoteA2A one, and --kind cognitive-search a CognitiveSearch one.

Two-step auth at runtime (worth internalizing before you build):

1. The hosted agent's identity must hold the Foundry user role on the project, or the toolbox rejects the call before any tool runs.
2. The toolbox then authenticates to each tool per the connection's auth type. For most types it uses the connection's configured identity; for oauth2 and user-entra-token the agent emits the caller / end-user token and the toolbox uses that token to reach the tool.

4 / Build a toolbox version (SDK)

A toolbox is a named resource; its capabilities live in immutable versions. You build a version from a list of typed tool objects plus an optional list of skills, then promote one version to default later.

project.toolboxes.create_version(
    name=TOOLBOX_NAME,
    description="...",                 # human-readable, shown in listings
    tools=[ MCPToolboxTool(...), AzureAISearchToolboxTool(...), ... ],   # one typed object per tool
    skills=[ ToolboxSkillReference(...) ],                 # SEPARATE from tools
    policies=ToolboxPolicies(...),     # optional governance - see the policies section
)

Rules that apply to every tool:

• Use the typed classes from azure.ai.projects.models. Each part below imports the exact classes it needs at the top of its own cell, so you can lift any single tool into your own code.
• Connections are referenced by project_connection_id - the connection's name or its full ARM resource id. The toolbox resolves the tool's auth from that connection.
• name + description are optional on every tool and are what Tool Search ranks on, so give each one a crisp description. (MCPToolboxTool instead uses server_label + server_description.)
• At most one unnamed tool per built-in type is allowed. Two tools of the same type without a name are rejected; give every additional tool a name (tools of different types may each go unnamed).
• Skills are NOT tools - they go in the separate skills=[...] list as ToolboxSkillReference(name=..., version=...).

Each block below is skip-guarded on its env vars, so the cells run with just the two required vars set - you'll get a Web Search + Code Interpreter toolbox. We build the tools list across the parts (run them top-to-bottom), then create the version in the final part.

Core spine vs. catalog. 4b (Web Search) is the one tool we walk end-to-end; 4c - 4l are a reference catalog of the other tool types - skim or skip them, jump to 4m to create the version, then continue to Tool Search. Every catalog cell is self-contained and skip-guarded.

4a · Start the tool and skill lists

The build is incremental: each tool part appends to a tools list (and Skills appends to a skills list). Run this once to create the two empty lists, then run the parts you need top-to-bottom. There is no shared import cell - every part imports its own classes.

4b · Web Search

📄 Docs: Web search

What it is. A built-in tool that grounds answers with live web results. No vector store, no data prep - the model decides when to search and Foundry runs the query server-side.

How it works. Plain WebSearchToolboxTool() uses Grounding with Bing (billed under its own terms, no connection needed). Pass a WebSearchConfiguration instead to scope results to a Bing Custom Search instance you own - that path runs through a key-based connection.

Key parameters (all optional unless noted):

• search_context_size - "low" | "medium" | "high"; how much retrieved context to feed the model (bigger = more grounding, more tokens). Service default is medium.
• user_location - WebSearchApproximateLocation(country=, region=, city=, timezone=) to bias results geographically.
• custom_search_configuration - a WebSearchConfiguration(project_connection_id=, instance_name=) (both required) to use Bing Custom Search instead of the public index.
• name, description - used by Tool Search ranking.

Create the connection (only for the custom-search path; key-based) in the portal under Build -> Tools -> Connect a tool, or with azd ai connection create ... --auth-type api-key, then pass its id as WebSearchConfiguration.project_connection_id. The default public web search needs no connection.

4c · Code Interpreter

📄 Docs: Code Interpreter

What it is. A sandboxed Python runtime the model can use to do math, parse text, transform data, and generate files or charts - anything better done by running code than by guessing.

How it works. The model writes Python; Foundry executes it in an isolated container and feeds results back. To analyze your own data, upload files first with the Files API and attach them by id; files the code generates (charts, CSVs) come back as container-file citations you can download. No connection is required - Code Interpreter is fully hosted.

Upload a file with the project's OpenAI client (purpose="assistants"), then attach it:

openai = project.get_openai_client()
file = openai.files.create(purpose="assistants", file=open("data.csv", "rb"))
# attach to the tool: AutoCodeInterpreterToolParam(file_ids=[file.id])

Download a generated file - the run's response annotations carry a container_file_citation with file_id + container_id; fetch the bytes with:

content = openai.containers.files.content.retrieve(file_id=file_id, container_id=container_id)
with open("chart.png", "wb") as f:
    f.write(content.read())

Key parameters (all optional):

• container - either a container id string, or an AutoCodeInterpreterToolParam(file_ids=[...]) to attach uploaded files to the sandbox. Omit it to let the service auto-provision a default sandbox.
• name, description - used by Tool Search ranking.

4d · File Search

📄 Docs: File Search

What it is. Retrieval-augmented grounding over your own documents. You load files into one or more vector stores; the tool retrieves the most relevant chunks for each query.

How it works. Create a vector store, upload your files into it, and pass the store id. Use the project's OpenAI client (project.get_openai_client()) for both steps:

openai = project.get_openai_client()
vector_store = openai.vector_stores.create(name="ProductInfoStore")
with open("product_info.md", "rb") as fh:
    openai.vector_stores.files.upload_and_poll(vector_store_id=vector_store.id, file=fh)
# then: FileSearchToolboxTool(vector_store_ids=[vector_store.id])

vector_store_ids is required, so this part skips unless you supply FILE_SEARCH_VECTOR_STORE_ID (or set FILE_SEARCH_FILE to create a store below). No connection is needed - the vector store is a project resource.

Key parameters:

• vector_store_ids - required list[str]; the stores to search.
• max_num_results - optional int (1-50); cap on retrieved chunks.
• filters - optional metadata filter (ComparisonFilter / CompoundFilter).
• name, description - used by Tool Search ranking.

4e · Remote MCP server

📄 Docs: Model Context Protocol

What it is. A bridge to any external Model Context Protocol server, so every tool that server exposes becomes callable from your toolbox. This is the most common way to bring third-party or in-house tools into Foundry.

How it works. You give it a server_label (namespaces the remote tools in tools/list) and a server_url (the MCP endpoint). Auth and allow-listing come from the connection named by project_connection_id. MCP accepts all six auth types.

Key parameters:

• server_label - required str; the prefix used to identify this server's tools.
• server_url - required str; the MCP endpoint URL.
• project_connection_id - connection holding the auth; None means a public/no-auth server.
• require_approval - "never" | "always", or an MCPToolRequireApproval(always=, never=) filter to gate specific tools.
• allowed_tools - a list[str] (or MCPToolFilter(tool_names=, read_only=)) to curate a subset.
• server_description, headers - description for ranking; extra HTTP headers per call.

The six connection auth types (MCP and A2A support all of them). Each is configured on the connection at creation time - never in the tool code:

Create the connection (admin, once - portal Build -> Tools -> Connect a tool, or azd):

azd ai connection create my-mcp --kind remote-tool --target https://api.example.com/mcp --auth-type oauth2

Then pass its name/id as project_connection_id.

4f · Azure AI Search

📄 Docs: Azure AI Search

What it is. Grounded retrieval over an Azure AI Search index - your enterprise knowledge base, with keyword, semantic, or vector ranking.

How it works. The tool wraps a nested resource: AzureAISearchToolResource(indexes=[...]) holding one AISearchIndexResource that names the connection, the index, and the query mode. The connection supports key or project-managed-identity auth.

Key parameters (on AISearchIndexResource):

• project_connection_id - the AI Search connection.
• index_name - the index to query.
• query_type - an AzureAISearchQueryType: SIMPLE (BM25 keyword), SEMANTIC, VECTOR, VECTOR_SIMPLE_HYBRID, or VECTOR_SEMANTIC_HYBRID.
• top_k - number of documents to retrieve; filter - an OData filter string.

AzureAISearchToolResource.indexes is capped at one index per tool.

Create the connection (custom-keys or project-managed-identity):

azd ai connection create my-search --kind cognitive-search --target https://<svc>.search.windows.net --auth-type project-managed-identity

4g · OpenAPI

📄 Docs: OpenAPI specified tools

What it is. Turns any REST API described by an OpenAPI spec into agent-callable functions - one function per operation - without writing a wrapper.

How it works. You hand the loaded spec dict to an OpenApiFunctionDefinition, which also carries the auth. The most common auth is a project connection via OpenApiProjectConnectionAuthDetails -> OpenApiProjectConnectionSecurityScheme(project_connection_id=...). Supports key or project-managed-identity. (Other auth variants: OpenApiAnonymousAuthDetails for public APIs, OpenApiManagedAuthDetails for a managed-identity audience.)

Key parameters (on OpenApiFunctionDefinition):

• name - required function name.
• spec - required the OpenAPI document as a dict (e.g. jsonref.loads(open(path).read())).
• auth - required one of the auth-details classes above.
• description - shown to the model and used by Tool Search; default_params - params you pre-fill.

Create the connection (key-based or project-managed-identity) in the portal under Connect a tool, or with azd ai connection create ... --auth-type custom-keys; pass its id as project_connection_id.

4h · A2A (agent-to-agent)

📄 Docs: Agent-to-agent (A2A)

What it is. Lets your toolbox delegate to another agent that speaks the open Agent-to-Agent (A2A) protocol - useful for composing specialist agents (billing, HR, search) into one surface.

How it works. You reference the remote agent by connection only - no agent-card URL needed. The tool fetches the agent's capability card from the default path (/.well-known/agent-card.json) at the connection's target. Set base_url only when the connection has no target endpoint, or agent_card_path to override the card location. Accepts all six auth types.

Key parameters (all optional):

• project_connection_id - the connection to the A2A server (carries auth + target).
• base_url - the agent's base URL, when not supplied by the connection.
• agent_card_path - defaults to /.well-known/agent-card.json.
• name, description - used by Tool Search ranking.

Create the connection (admin, once - all six auth types apply):

azd ai connection create my-a2a --kind remote-tool --target https://agent.example.com --auth-type oauth2

4i · Work IQ (preview)

📄 Docs: Connect agents to Microsoft 365 with Work IQ · Enable Work IQ in your tenant

What it is. A Microsoft-managed tool that reasons over the signed-in user's Microsoft 365 work context - mail, chats, meetings, and documents - so the agent can answer "what did my team decide about X?" style questions.

How it works. Foundry routes each tool call to Work IQ over the Agent-to-Agent (A2A) protocol, authenticating On-Behalf-Of (OBO) the signed-in user - so requests run with that user's Microsoft 365 permissions and sensitivity labels. Delegated Entra auth is the only option; application-only auth is not supported. The project connection is therefore authType: OAuth2 / category: RemoteA2A, targeting https://workiq.svc.cloud.microsoft/a2a/.

Because it's OBO, you must supply your own Microsoft Entra app registration - Work IQ only supports "bring your own Entra app." A connection that isn't backed by a correctly configured app (for example, missing the WorkIQAgent.Ask scope) is accepted by create_version but fails at runtime with errors like TokenAudience is required for OBO or Failed to fetch agent card: 404.

⚠️ You can't reuse someone else's preview connection - each tenant registers its own Entra app.

Prerequisites

• Foundry Project Manager role (to create the connection) plus Foundry User role for the developer, the agent runtime identity, and every user involved in the OAuth flow.
• A Microsoft 365 Copilot license for each user who calls Work IQ.
• A Microsoft Entra Global Administrator to grant admin consent.
• A project endpoint without VNet restriction (VNet integration isn't supported).
• Your tenant enabled for Work IQ - a one-time az ad sp create --id fdcc1f02-fc51-4226-8753-f668596af7f7 (or the Graph Explorer equivalent) provisions the Work IQ service principal so the WorkIQAgent.Ask permission becomes selectable.

Step 1 - Register your own Entra app (Entra admin center -> Entra ID -> App registrations -> New registration):

1. Set Supported account types = Accounts in this organizational directory only (single tenant), Register, then copy the Application (client) ID.
2. API permissions -> Add a permission -> APIs my organization uses -> search Work IQ (app ID fdcc1f02-fc51-4226-8753-f668596af7f7) -> Delegated permissions -> WorkIQAgent.Ask -> Add permissions, then Grant admin consent (requires Global Administrator).
3. Certificates & secrets -> New client secret; copy the secret Value (shown only once).
4. Copy the Directory (tenant) ID from the Entra ID overview.

Step 2 - Create the Work IQ connection in Foundry (Foundry portal -> your project -> Settings -> Connections -> New connection -> Work IQ), using the values from your app. Connection fields can't be edited after creation.

You can also create the connection with the ARM REST API: PUT .../connections/{name}?api-version=2025-04-01-preview with authType: OAuth2, category: RemoteA2A, target: https://workiq.svc.cloud.microsoft/a2a/.

Step 3 - Add the redirect URI back. After you save, Foundry returns an OAuth redirect URL (properties.oauthRedirectUrl) - paste it into the app registration under Authentication -> Add a platform -> Web.

Key SDK parameters:

• project_connection_id - required str; the Work IQ connection you created above.
• name, description - used by Tool Search ranking.

4j · Fabric IQ (preview)

📄 Docs: Fabric IQ

What it is. A Microsoft-managed tool for governed analytics and ontology over Microsoft Fabric - it reaches Fabric's data agent / MCP surface so the agent can query lakehouse data and semantic models under Fabric's governance.

How it works. Backed by an MCP server on the Fabric side; you supply the connection and optionally a server_label/server_url. Its connection requires delegated user auth - oauth2 or user-entra-token (OBO); application-only project-managed-identity is not supported. Set require_approval to "never" for unattended use.

Key parameters:

• project_connection_id - required str; the Fabric IQ connection.
• require_approval - "never" | "always" or an MCPToolRequireApproval filter; set "never" for unattended use.
• server_label, server_url - optional MCP server identity (falls back to the connection).
• name, description - used by Tool Search ranking.

Create the connection (oauth2 or user-entra-token - delegated OBO):

azd ai connection create my-fabriciq --kind remote-tool --target <fabric-iq-endpoint> --auth-type user-entra-token

4k · Browser Automation (preview)

📄 Docs: Browser Automation

What it is. Lets the agent drive a real browser (via Playwright Workspaces) to complete multi-step web tasks - navigate, click, fill forms, read pages - when no API exists.

How it works. The tool needs a connection to a Playwright Workspaces resource, nested two levels deep: BrowserAutomationToolParameters(connection=BrowserAutomationToolConnectionParameters( project_connection_id=...)). The connection is key-based.

Key parameters:

• browser_automation_preview - required BrowserAutomationToolParameters, whose connection.project_connection_id (required) points at the Playwright connection.
• name, description - used by Tool Search ranking.

Create the connection (key/token-based, to a Playwright Workspaces resource):

azd ai connection create my-browser --kind PlaywrightWorkspace --target <playwright-endpoint> --auth-type api-key

4l · Skills (the separate skills= list)

📄 Docs: Skills · Attach skills to a toolbox

What it is. A skill is a reusable, published SKILL.md file of behavioral instructions (name + description + instruction body; no tools are packaged inside), following the Agent Skills spec - registered once and reused across toolboxes and agents.

How it works. Skills are registered out-of-band with project.beta.skills.create(name, inline_content=SkillInlineContent(description=, instructions=)) (or upload a ZIP/SKILL.md for multi-file packaging); a separate update-default call then promotes a version to default. In a toolbox a skill is not a tool - you reference it in the separate skills= list with ToolboxSkillReference(name, version). Omit version to track the skill's default version; pin it to freeze on an immutable version.

Key parameters (ToolboxSkillReference):

• name - required str; the published skill name.
• version - optional; None = default version, a value = pinned immutable version.

Consuming over MCP. Once attached, a skill is not a callable tool - it surfaces as an MCP Resource on the same toolbox endpoint, following the Skills-for-MCP extension (SEP-2640). Any MCP client calls resources/list once at connect time to discover attached skills, then resources/read to download each SKILL.md body - no Foundry SDK required. Frameworks layer the Agent Skills progressive-disclosure pattern on top: advertise skill names/descriptions in the system prompt, then load the full body on demand. We consume the live resources over MCP in section 10b.

4m · Create the version

Pass the assembled tools and skills to create_version. The toolbox is auto-created on the first call; every call mints a new immutable version id. tools is required; skills, description, metadata, and policies are optional.

5 / The REST API path (declarative / CI) (optional reference)

The SDK above is a thin wrapper over the toolboxes REST API. When you want to ship a toolbox from CI - or from a language without an SDK - call the API directly. The whole build is one POST .../toolboxes/{name}/versions, and promoting a default is one PATCH .../toolboxes/{name}.

The request body is exactly the JSON the typed classes serialize to, so you can keep a versioned JSON manifest in source control. Every call needs the bearer token (scope https://ai.azure.com/.default) and the Foundry-Features: Toolboxes=V1Preview header.

azd (the Foundry extension) handles connections and agent provisioning, but a toolbox is authored with the SDK above or this REST API - there is no azd ai toolbox command. Create connections with azd ai connection create (or the portal) as covered in the auth section.

6 / Tool Search - the headline feature

📄 Docs: Enable tool search in a toolbox

A real toolbox can hold dozens or hundreds of tools. Sending every tool definition to the model on every turn is slow, expensive, and hurts accuracy. Tool Search fixes this: instead of listing all tools, Foundry shows the model two meta-tools and lets it search for capability on demand.

How it works

1. Enable it by adding a toolbox_search_preview tool to the version.
2. tools/list now returns just tool_search and call_tool (+ any pinned tools).
3. The model calls tool_search(query, limit?); Foundry ranks the toolbox's un-pinned tools by semantic match on each tool's name + description and returns only the hits. (Pinned and auto-pinned tools are already in tools/list, so search covers the rest.)
4. The model invokes a returned tool via call_tool(name, args). Returned tools persist for the rest of the turn, and the model may search again for later steps.

Controlling the flexibility / control trade-off

Prompt tip. Tell the model in its system prompt: "You have a tool_search tool. Search for a capability before assuming it doesn't exist; you may search multiple times per turn." Without this nudge, weaker models sometimes give up instead of searching.

7 / Versioning (optional reference)

Versions are immutable - you never edit a version, you create a new one. A single version is the default, and the default is what the consumer endpoint serves. This gives you safe, atomic rollouts: build a new version, test it on its pinned per-version URL, then flip the default.

8 / Policies & governance (optional reference)

"Governed by default" comes from three independent control points. Only the first is a field on the toolbox; the other two are standard Azure mechanisms you compose around it.

Only the RAI guardrail is a toolbox field, and it screens every tool's inputs/outputs. APIM is your own gateway that you point an MCP tool at, so it governs the MCP-server tools that route through it; Azure Policy is authored separately by an admin and bites at connection-creation time, not when the toolbox is built.

9 / Get the toolbox MCP endpoint

There are two MCP URLs. Use the developer URL to test a specific version in isolation; ship the consumer URL - it always serves the current default, so promoting a new version upgrades every consumer with no code change.

Both require the bearer token (scope https://ai.azure.com/.default) and the Foundry-Features: Toolboxes=V1Preview header on every request.

10 / Verify over MCP

Let's talk to the live endpoint with a raw MCP client to prove Tool Search is in effect. We list tools/list on both the pinned non-search version (before) and the search-first default (after): the before set is every tool, while the after set collapses to just tool_search, call_tool, and any pinned tools - reproducible before/after evidence for the progressive-disclosure claim (tool count and input-schema payload size). Then we run a tool_search -> call_tool round-trip and read each tool's _meta.tool_configuration (which carries require_approval).

We use the mcp SDK's streamable-HTTP client, passing the bearer token and the mandatory preview header. If a tool's connection uses oauth2, the first call returns CONSENT_REQUIRED (-32006) with a consent URL - we surface it so you can consent and retry.

10b / Consume skills over MCP (resources)

📄 Docs: Attach skills to a toolbox · Skills in Toolbox sample (MAF, C#)

Skills attached to a toolbox surface as MCP Resources (SEP-2640), not tools - so they never show up in tools/list. The same raw MCP session lists them with resources/list and downloads each SKILL.md body with resources/read. This is exactly how any MCP client - GitHub Copilot, Claude Code, or your own agent harness - loads a toolbox skill without the Foundry SDK. A framework such as Microsoft Agent Framework wraps this in a skills provider (advertise -> load -> read), but underneath it is just these two MCP calls.

11 / Consume the toolbox

The whole point of one governed endpoint is that any MCP client can use it unchanged. Here are three: Microsoft Agent Framework, LangGraph, and the Copilot SDK. Each just needs the consumer URL, a bearer token, and the preview header.

12 / Host MAF / LangGraph as a Foundry hosted agent (optional reference)

The MAF and LangGraph agents above run locally. The same agent code can run as a Foundry hosted agent - Foundry manages the runtime, scaling, and (critically) the agent identity that flows through the toolbox connections.

Wrap the agent in a ResponsesAgentServerHost and the hosted runtime serves it at a Responses endpoint. Because the toolbox is referenced by its consumer URL, nothing about the tool wiring changes between local and hosted - only the identity the connections see (the agent's managed identity instead of your az login).

13 / Clean up

Best-effort teardown of what this notebook created - toolbox versions, then the toolbox itself. Connections are left in place (they're often shared); delete throwaways in the Foundry portal or with azd ai connection delete <name>.

Failure modes

Toolboxes sit on top of identity, connections, and preview APIs, so most breakage is an auth or a version mismatch rather than a logic bug. The ones you'll hit first:

14 / Next steps

You worked the full pattern end-to-end, and hit each objective:

• Built a versioned toolbox that exposes multiple tool types behind one MCP endpoint.
• Configured per-connection identity so each consumer inherits least-privilege access.
• Enabled Tool Search so the toolbox stays cheap for the model no matter how many tools it holds.
• Consumed the same toolbox unchanged from Agent Framework, LangGraph, and the Copilot SDK.

From here:

• Tune Tool Search - measure how often the model searches vs. uses pinned tools, then adjust pin / additional_search_text and your system prompt.
• Lock down identity - move shared custom-keys connections to agentic-identity or user-entra-token so each agent/user is least-privilege.
• Add an RAI policy - author one in the portal and set rai_config.rai_policy_name.
• Ship declaratively - commit the my-toolbox.json manifest and wire the REST POST /toolboxes/{name}/versions + PATCH (promote default) calls into CI.
• Go hosted - package the MAF or LangGraph agent as a Foundry hosted agent so connections run under a managed agent identity.

Reference docs

• Toolboxes in Microsoft Foundry
• Tool Search
• Microsoft Agent Framework
• Model Context Protocol