Use Toolbox in a Hosted Agent

Hosted agents access Foundry-managed tools through a Toolbox MCP endpoint. Unlike prompt agents that wire tools directly, hosted agents connect to a single MCP-compatible endpoint that exposes all configured tools. The platform handles credential injection, token refresh, and policy enforcement.

📘 For endpoint format, MCP protocol details, auth, OAuth consent handling, testing, citation pattern, and troubleshooting, see toolbox-reference.md.

>

📘 For wiring a remote tool (catalog tile or generic MCP server) into a project connection that a toolbox can attach to, see foundry-tool-catalog.md.

>

📘 For the full list of supported tool types and their per-type fields, see agent-tools.md and the per-tool tool-*.md files.

💡 **This skill is scoped to *consuming* an existing toolbox from agent code — endpoint resolution, env-var contract, payload shape gathered before agent runtime, verification, and tracing. Toolbox and connection CRUD belongs in Foundry Toolkit (VS Code) or the Foundry Portal** — those surfaces give you tool browsing, metadata, connection wizards, and validation. Use the imperative azd ai CLI only for *operational* tasks (retarget the default version, smoke-test an endpoint).

✨ Recommendation: enable Tool Search

Before adding more than ~5 tools to a toolbox, add { "type": "toolbox_search_preview" } to the toolbox. This replaces the full tools/list shown to the model with two meta-tools — tool_search (natural-language discovery) and call_tool (invoke a discovered tool) — so context cost stays flat as the toolbox grows.

• The toolbox_search_preview entry doesn't count toward the unnamed-tool-per-type limit.
• All other tools in the toolbox are hidden from the initial tools/list and surfaced only by tool_search (or by per-user auto-pinning of hot tools).
• Pin specific high-traffic tools or add ranking-only keywords via tool_configs.{tool_name} (with pin: true and additional_search_text).
• In the agent's system prompt, instruct the model to call tool_search whenever a needed capability isn't already visible.

Full configuration recipe in tool-tool-search.md and the public Tool Search (preview) docs.

Quick Reference

Resolve Toolbox Endpoint

If the user provides a toolbox name or endpoint URL, or the project already references a toolbox (e.g., in .env or agent.manifest.yaml) → use it directly.

Otherwise, ask one question:

"Would you like to provide your toolbox endpoint? (you can create one with the Foundry Toolkit in VS Code or the Foundry Portal)"

Once the user supplies the toolbox name/endpoint — either an existing one or a new one they create via the Foundry Toolkit or Foundry Portal — set it on the agent (e.g., TOOLBOX_ENDPOINT in .env) and continue with verification.

Use the env var name TOOLBOX_ENDPOINT (no FOUNDRY_ prefix). The Foundry platform reserves FOUNDRY_-prefixed env vars and may silently overwrite them at runtime — see toolbox-reference.md § Agent env contract.

When asking the question, always include the doc links inline for the manual options — the Foundry Toolkit in VS Code and the Foundry Portal — so the user knows where to go to create a tool/toolbox themselves. Don't just name the options; render them as clickable links every time.

Before printing out any step-by-step guidance for the Foundry Toolkit (VS Code) path, fetch and read Use Tool Catalog to connect tools and Toolboxes in Foundry Toolkit first, then summarize the relevant steps for them. Don't paraphrase from memory — the Toolkit UI changes; quote the current doc.

Available tool types

The full set is documented in agent-tools.md and — authoritatively — in the public Toolbox docs (Configure tools). At time of writing the supported type values are:

Adjacent (not a type in a toolbox version):

• Agent Memory — use the MemorySearchTool SDK class on prompt agents; for hosted agents, configure the memory store via the project (separate from the toolbox). See tool-memory.md.
• Routines (preview) — not a tool; an agent trigger (schedule / timer / github_issue / custom) that invokes an existing agent. See the public Routines docs.

Information to Gather Before Building a Toolbox Payload

When the user asks to "add an MCP tool" or similar, never guess. Confirm each field before generating any JSON or azure.yaml snippet:

Toolbox payload — MCP with a project connection

{
  "name": "<TOOLBOX_NAME>",
  "description": "MCP server with key or OAuth auth",
  "tools": [
    {
      "type": "mcp",
      "server_label": "<LABEL>",
      "server_url": "<SERVER_URL>",
      "require_approval": "never",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

Toolbox payload — public MCP (no auth)

{
  "name": "api-specs",
  "description": "Public MCP server, no connection needed",
  "tools": [
    {
      "type": "mcp",
      "server_label": "api_specs",
      "server_url": "https://gitmcp.io/Azure/azure-rest-api-specs",
      "require_approval": "never"
    }
  ]
}

Toolbox payload — large toolbox with Tool Search

{
  "name": "big-toolbox",
  "description": "Many tools — model uses tool_search to discover",
  "tools": [
    { "type": "toolbox_search_preview" },
    { "type": "web_search" },
    { "type": "azure_ai_search", "name": "docs_index", "project_connection_id": "search-conn", "index_name": "docs" },
    {
      "type": "mcp", "server_label": "github", "server_url": "<github-mcp-url>",
      "project_connection_id": "gh-conn",
      "tool_configs": {
        "search_issues": { "pin": true, "additional_search_text": "GitHub issues bug tracking" },
        "*":             { "additional_search_text": "GitHub repositories code" }
      }
    }
  ]
}

Declarative path via azd

If the project already uses azd ai agent init, prefer declaring the toolbox in azure.yaml so azd deploy provisions it and injects TOOLBOX_ENDPOINT automatically:

# Declare secret parameters first; azd will prompt for the value on `azd up`
# (or read it from `AZURE_<NAME>` env vars) and never store it in plaintext.
params:
  - name: github_pat
    type: securestring

resources:
  - kind: connection
    name: <CONNECTION_NAME>
    target: <MCP_SERVER_URL>
    category: remoteTool
    credentials:
      type: CustomKeys
      keys:
        # Header name comes from the catalog entry's x-ms-connection-parameters.
        # {{ github_pat }} is resolved from the `params` block above.
        Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    tools:
      - type: toolbox_search_preview   # recommended for any toolbox > ~5 tools
      - type: web_search
      - type: mcp
        server_label: <LABEL>
        server_url: <MCP_SERVER_URL>
        project_connection_id: <CONNECTION_NAME>

See azd params reference for the full parameter syntax.

Operational helpers via azd ai CLI

The azd ai CLI also exposes agent connection create, toolbox create, toolbox list, and toolbox delete. Prefer Foundry Toolkit (VS Code) or the Foundry Portal for those — the UI gives you tool browsing, connection wizards, and validation. The two commands below are the ones the skill should still drive directly because they're *operational*, not setup.

All commands require --project-endpoint <PROJECT_ENDPOINT> (the value of PROJECT_ENDPOINT, e.g. https://<account>.services.ai.azure.com/api/projects/<project>). To avoid repeating it, export it once:

>

$PE = "https://<account>.services.ai.azure.com/api/projects/<project>"

Retarget the default version — azd ai toolbox update

Each toolbox version is immutable. The version an agent actually hits is the one marked * in version list — i.e. the default version. Use update to point that pointer at any existing version (e.g. rollback to a known-good version after a bad publish).

# Inspect first — current default is marked with '*'
azd ai toolbox version list my-toolbox --project-endpoint $PE

# Retarget the default
azd ai toolbox update my-toolbox --default-version 20 --project-endpoint $PE --no-prompt

# Verify (Default version / Shown version / Endpoint all reflect the new value)
azd ai toolbox show my-toolbox --project-endpoint $PE

• --default-version is the only field update accepts today.
• Validated: switched default-tb from version 21 → 20 → 21; both show and the computed MCP endpoint (.../toolboxes/<name>/versions/<n>/mcp?api-version=v1) tracked the change immediately.

End-to-end smoke test

After the toolbox is created (via Toolkit / Portal / azd), hit the MCP endpoint directly to confirm the tool is reachable before pointing an agent at it:

$TOK = az account get-access-token --resource "https://ai.azure.com" --query accessToken -o tsv
$H   = @{
  Authorization      = "Bearer $TOK"
  "Content-Type"     = "application/json"
  "Foundry-Features" = "Toolboxes=V1Preview"
}
$URL = "$PE/toolboxes/my-toolbox/mcp?api-version=v1"
$body = @{ jsonrpc = "2.0"; id = 1; method = "tools/list"; params = @{} } | ConvertTo-Json
(Invoke-RestMethod -Method POST -Uri $URL -Headers $H -Body $body).result.tools | Select-Object name

?api-version=v1 and the Foundry-Features: Toolboxes=V1Preview header are both required.

Code Integration Patterns

The sample repo provides integration patterns for both Python and C#. Read the sample code and adapt it to the user's project.

Python samples:

C# (.NET) samples:

Notes (apply to all patterns, both Python and C#):

• Auth: Inject a bearer token with scope https://ai.azure.com/.default on every request (Python: httpx.Auth subclass; C#: DefaultAzureCredential + BearerTokenAuthenticationPolicy).
• Header: Always include Foundry-Features: Toolboxes=V1Preview.
• MCP client: Pass load_prompts=False — the toolbox endpoint does not support prompts/list.
• Endpoint: Construct from {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1.
• Multi-tool toolboxes: at most one tool per unnamed type, and unique server_label per MCP tool (see toolbox-reference.md). toolbox_search_preview doesn't count toward this limit.
• Tool naming: MCP-sourced tools are prefixed {server_label}.{tool_name}; all other tool types use the entry's name field value (or the default tool name).

💡 Tip: If MCP tools have require_approval: "always" in _meta.tool_configuration, the agent runtime must ask the user for confirmation before invoking. The toolbox endpoint does not enforce this — your agent code is responsible.

Tracing

All toolbox samples emit OpenTelemetry traces. No code changes are required to enable export to Azure Monitor — it's purely a configuration step.

• Local development: set APPLICATIONINSIGHTS_CONNECTION_STRING in the agent's .env.
• Deployed: the platform injects APPLICATIONINSIGHTS_CONNECTION_STRING automatically when the Foundry project is linked to an Application Insights resource.
• Per-framework instrumentation hooks (already present in the samples):
• maf — main.py calls enable_instrumentation().
• langgraph / azd — auto-instrumented by azure-ai-agentserver-core[tracing].
• Viewing traces: Azure Portal → Application Insights → Investigate → Transaction search (per-trace) or Application map (dependency graph).