1# Tools and Toolboxes (azd ai)
2 
3How to attach tools (web search, Azure AI Search, MCP, A2A) to a hosted agent using `azd ai toolbox` and `azd ai agent connection`.
4 
5A **toolbox** is a curated bundle of connection-backed tools that Foundry exposes as a single MCP-compatible endpoint. The agent connects to one URL and discovers every tool inside. `azd deploy` does NOT auto-create toolboxes -- you drive the lifecycle explicitly.
6 
7> 🚦 **Toolbox creation gate:** before creating a toolbox/connection, you MUST read the boundary rules in [create-hosted.md → Toolbox creation boundary](../create-hosted.md#toolbox-creation-boundary) and follow them, then continue with the rest of this file.
8 
9## Install the extension once
10 
11```bash
12azd extension install azure.ai.toolboxes
13```
14 
15## The flow (every recipe)
16 
171. Create the **connection** (`azd ai agent connection create ...`).
182. Create or update the **toolbox** (`azd ai toolbox create` / `connection add`).
193. Read the endpoint (`azd ai toolbox show <name> --output json`).
204. `azd env set TOOLBOX_<NAME>_MCP_ENDPOINT "<endpoint>"`.
215. Reference it in `<service-dir>/agent.yaml` `environment_variables[]`.
226. `azd deploy`.
23 
24## Env var naming convention
25 
26Uppercase the toolbox name, collapse non-alphanumeric to `_`, prefix `TOOLBOX_`, suffix `_MCP_ENDPOINT`. Examples: `agent-tools` -> `TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT`, `agent.tools.v2` -> `TOOLBOX_AGENT_TOOLS_V2_MCP_ENDPOINT`.
27 
28## Endpoint URL shapes
29 
30- `{project}/toolboxes/{name}/versions/{version}/mcp?api-version=v1` -- version-pinned. What `azd ai toolbox show` returns.
31- `{project}/toolboxes/{name}/mcp?api-version=v1` -- default version (consumer). Always serves `default_version`.
32 
33To auto-pick up new default versions without redeploying, drop the `/versions/<ver>` segment and store the consumer URL.
34 
35## CLI surface
36 
37| Command | What it does |
38|---------|--------------|
39| `azd ai toolbox create <name> --from-file <path>` | Create toolbox + publish v1. File must list at least one connection. |
40| `azd ai toolbox connection add <toolbox> <connection> [--index ...] [--instance-name ...]` | Attach one; new default version. |
41| `azd ai toolbox connection add <toolbox> --from-file <path>` | Attach many in one call; ONE new version. |
42| `azd ai toolbox connection remove <toolbox> <connection>` | Detach; new default version. Refuses to leave zero tools. |
43| `azd ai toolbox show <name> [--version <ver>]` | Show toolbox + MCP endpoint URL. |
44| `azd ai toolbox list` | List toolboxes. |
45| `azd ai toolbox version list <toolbox>` | List versions. |
46| `azd ai toolbox update <name> --default-version <ver>` | Re-point default (rollback). |
47| `azd ai toolbox delete <name> [--version <ver>] [--force]` | Delete toolbox or one version. |
48 
49Every mutation publishes a new immutable version and promotes it to default.
50 
51## `--from-file` shape
52 
53```yaml
54description: research toolbox    # only on `create`
55connections:
56  - name: my-mcp                 # RemoteTool
57  - name: my-search              # CognitiveSearch -- needs index
58    index: products
59  - name: my-bing                # GroundingWithCustomSearch -- needs instance_name
60    instance_name: docs-config
61  - name: my-a2a                 # RemoteA2A
62```
63 
64## Recipe: GitHub MCP
65 
66```bash
67# 1. Connection
68azd ai agent connection create github-mcp-conn \
69  --kind remote-tool \
70  --target https://api.githubcopilot.com/mcp \
71  --auth-type custom-keys \
72  --custom-key Authorization="Bearer ghp_xxx..."
73 
74# 2. Toolbox (initial create needs a file; otherwise use `connection add`)
75cat > tools.json <<EOF
76{ "description": "GitHub MCP", "connections": [{ "name": "github-mcp-conn" }] }
77EOF
78azd ai toolbox create agent-tools --from-file tools.json
79 
80# 3. Wire the env var
81ENDPOINT=$(azd ai toolbox show agent-tools --output json | jq -r .endpoint)
82azd env set TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT "$ENDPOINT"
83```
84 
85Add the env var to `<service-dir>/agent.yaml`:
86 
87```yaml
88environment_variables:
89  - name: TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT
90    value: ${TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT}
91```
92 
93Then `azd deploy`.
94 
95## Recipe: Azure AI Search RAG
96 
97```bash
98azd ai agent connection create my-search-conn \
99  --kind cognitive-search \
100  --target https://my-search.search.windows.net/ \
101  --auth-type api-key --key "<search-admin-key>"
102 
103azd ai toolbox connection add agent-tools my-search-conn --index contoso-outdoors
104```
105 
106For multiple indexes, add multiple entries with different `index` values.
107 
108## Recipe: A2A peer agent
109 
110```bash
111azd ai agent connection create peer-agent-conn \
112  --kind remote-a2a \
113  --target https://other-agent.foundry-account.westus2.azure.com/ \
114  --auth-type none
115 
116azd ai toolbox connection add agent-tools peer-agent-conn
117```
118 
119For authenticated peers, use `--auth-type project-managed-identity --audience https://ai.azure.com/.default`.
120 
121## Recipe: multi-tool toolbox in one call
122 
123```yaml
124# tools.yaml
125description: "GitHub MCP + AI Search + A2A peer."
126connections:
127  - name: github-mcp-conn
128  - name: my-search-conn
129    index: contoso-outdoors
130  - name: peer-agent-conn
131```
132 
133```bash
134azd ai toolbox create agent-tools --from-file tools.yaml
135# OR (existing toolbox): azd ai toolbox connection add agent-tools --from-file tools.yaml
136```
137 
138One new default version regardless of how many connections you attach in one call.
139 
140## Tools the CLI does NOT manage today
141 
142`azd ai toolbox` only handles connection-backed tools (`RemoteTool`, `CognitiveSearch`, `RemoteA2A`, `GroundingWithCustomSearch`). These built-ins have no connection and are NOT addable via this CLI: `web_search`, `code_interpreter`, `file_search`, `function`, `toolbox_search_preview`.
143 
144To include any built-in in a toolbox today, use the Python / .NET / JS SDK or call the REST API directly.
145 
146## Required header (agent code)
147 
148Every MCP request to the toolbox endpoint must include:
149 
150```http
151Foundry-Features: Toolboxes=V1Preview
152```
153 
154Token scope: `https://ai.azure.com/.default`. RBAC: the calling identity (developer + agent identity at runtime) needs **Foundry User** on the Foundry project.
155 
156## Agent code (Python, Microsoft Agent Framework)
157 
158```python
159import os, httpx
160from azure.identity import DefaultAzureCredential
161from agent_framework.tools.mcp import MCPStreamableHTTPTool
162 
163_credential = DefaultAzureCredential()
164 
165def _inject_auth(request: httpx.Request) -> None:
166    # Per-request token refresh -- static tokens expire in ~1 hour.
167    token = _credential.get_token("https://ai.azure.com/.default").token
168    request.headers["Authorization"] = f"Bearer {token}"
169    request.headers["Foundry-Features"] = "Toolboxes=V1Preview"
170 
171tool = MCPStreamableHTTPTool(
172    name="github",                    # becomes server_label prefix
173    url=os.environ["TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT"],
174    httpx_client=httpx.AsyncClient(event_hooks={"request": [_inject_auth]}),
175    load_prompts=False,               # Foundry doesn't implement prompts/list
176    approval_mode="never_require",    # for require_approval:always tools
177)
178```
179 
180Install: `pip install httpx azure-identity agent-framework`.
181 
182## MCP client gotchas
183 
184- **Always stream.** Non-streaming is not supported.
185- **Don't call `prompts/list`.** Returns `500`. Pass `load_prompts=False`.
186- **Don't `send_ping()`** with generic clients (returns `500`). Agent Framework handles this.
187- **Tool names are prefixed with `server_label`.** `name="myserver"` -> tools appear as `myserver.<tool>`.
188- **`require_approval`** is the client's responsibility -- the toolbox proxy does NOT enforce it. Pass `approval_mode="never_require"` or wire an approval handler.
189 
190## Verify the wire end-to-end
191 
192```bash
193azd ai toolbox list --output json
194azd ai toolbox show agent-tools --output json
195azd deploy
196azd ai agent invoke "list the tools you have access to"
197```
198 
199## Troubleshooting
200 
201| Symptom | Likely cause |
202|---------|--------------|
203| `TOOLBOX_<NAME>_MCP_ENDPOINT` not set | Run `azd ai toolbox show` + `azd env set`. |
204| Env var missing in deployed agent | Add to `agent.yaml` `environment_variables[]`, `azd deploy`. |
205| `400` mentioning `Toolboxes` | Missing `Foundry-Features: Toolboxes=V1Preview` header. |
206| `401` on MCP calls | Expired / wrong-scope token. Use `https://ai.azure.com/.default`; refresh per request. |
207| `403 Forbidden` | Caller missing `Foundry User` role. |
208| `500` on `prompts/list` / ping | Disable in MCP client (`load_prompts=False`). |
209| Empty response, tool never called | `require_approval: always` with no handler. Pass `approval_mode="never_require"`. |
210| `tools/list` returns zero | Bad credentials, or toolbox version still provisioning. |
211| Tool names don't match | Use `{server_label}.{tool_name}`. |
212