You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 20f0728
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md
+25-15Lines changed: 25 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -126,18 +126,20 @@ Native code-interpreter file citations are a separate tracked behavior
126
126
127
127
#### Prerequisites
128
128
129
-
1.**Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later)
129
+
1.**Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.34.2 or later)
130
130
2. Install the unified Foundry CLI extension bundle (provides `azd ai agent`, `connection`, `inspector`, `project`, `routine`, `skill`, and `toolbox`):
131
131
```bash
132
132
# If you previously installed individual extensions, uninstall them first:
133
133
# azd ext uninstall azure.ai.agents
134
134
# azd ext uninstall azure.ai.toolboxes
135
135
azd ext install microsoft.foundry
136
136
```
137
+
Requires `azure.ai.agents` 1.0.0-beta.19 or later for `-t`.
137
138
3. Authenticate:
138
139
```bash
139
140
azd auth login
140
141
```
142
+
4. Prepare a GitHub MCP Personal Access Token (PAT) and the MCP endpoint of an existing Azure Language resource before initialization. The CLI may prompt for these values. Keep the PAT out of source control. The project's managed identity needs access to the Azure Language resource, and the calling user needs access for the Foundry MCP connection.
141
143
142
144
#### Initialize the agent project
143
145
@@ -146,10 +148,12 @@ No cloning required. Create a new folder and initialize from the manifest:
146
148
```bash
147
149
mkdir my-toolbox-agent &&cd my-toolbox-agent
148
150
149
-
azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/agent.manifest.yaml
151
+
azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml
150
152
```
151
153
152
-
Follow the prompts to configure your Foundry project and model deployment. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. Initializing also sets the selected project as the active project for the `azd ai` commands that follow.
154
+
Follow the prompts to configure your Foundry project. If you don't have an existing Foundry project, `azd ai agent init` will guide you through creating one. Initializing also sets the selected project as the active project for the `azd ai` commands that follow.
155
+
156
+
Run every subsequent command from the initialized project directory containing `azure.yaml`. If initialization reports a different output directory, change to that directory first.
153
157
154
158
#### Create the toolbox with `azd ai`
155
159
@@ -159,32 +163,37 @@ Follow the prompts to configure your Foundry project and model deployment. If yo
159
163
> -[Toolbox overview](https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/toolbox/toolbox.md) — toolbox concept, API shape and schema, versions, endpoints, and MCP protocol.
160
164
> -[Use toolbox in a hosted agent](https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugins/azure-skills/skills/microsoft-foundry/foundry-agent/create/references/use-toolbox-in-hosted-agent.md) — endpoint resolution, env-var contract, payload shape, code integration patterns, and tracing.
161
165
162
-
The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. Create the toolbox once from the bundled [`toolbox.yaml`](toolbox.yaml):
166
+
The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. The initialized `azure.yaml` declares the toolbox and its connections. `azd deploy --all` below creates them. If you entered the correct dependency values during initialization, skip these commands. Use them only to correct or replace those values:
163
167
164
168
```bash
165
-
azd ai toolbox create agent-tools --from-file ./toolbox.yaml --project-endpoint https://<account>.services.ai.azure.com/api/projects/<project>
169
+
azd env set GITHUB_MCP_PAT "<your-GitHub-MCP-PAT>"
170
+
azd env set AZURE_LANGUAGE_MCP_ENDPOINT "https://<language-service>.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview"
166
171
```
167
172
168
173
The first version becomes the default automatically. Use `azd ai toolbox list`, `azd ai toolbox show agent-tools`, and `azd ai toolbox version list agent-tools` to inspect, and `azd ai toolbox delete agent-tools --force` to remove it.
169
174
170
175
To stage incremental changes safely, use `azd ai toolbox connection add/remove` and `azd ai toolbox skill add/list/remove`; each creates a new toolbox version that carries forward existing connections and skills but **doesn't** change the default. Promote a version with `azd ai toolbox publish agent-tools <version>` when you're ready to make it active.
171
176
172
-
`azd ai toolbox create` prints the toolbox's versioned MCP endpoint. Copy that endpoint and store it in your `azd` environment so the agent connects to it:
173
-
174
-
```bash
175
-
azd env set TOOLBOX_ENDPOINT "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/agent-tools/versions/1/mcp?api-version=v1"
176
-
```
177
+
The initialized project's `azure.yaml` maps `TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT`, the toolbox's versioned MCP endpoint, to the agent's `TOOLBOX_ENDPOINT`. No manual endpoint copy is needed.
177
178
178
179
#### Provision Azure resources (if needed)
179
180
180
-
If you don't already have a Foundry projectand model deployment:
181
+
Provision before deploying so that the project's managed identity exists and can be authorized:
181
182
182
183
```bash
183
184
azd provision
184
185
```
185
186
187
+
On the Azure Language resource, grant **Cognitive Services Language Owner** to the Foundry **project's system-assigned managed identity**, not the parent Foundry account identity or your own user identity. An administrator may need to perform this assignment. See the [managed-identity authorization guide](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/SUPPORTED_TOOLBOX_SCENARIOS/tools/mcp-microsoft-entra.md#step-2--authorize-the-identity) for identity lookup and role assignment instructions. Allow time for the assignment to propagate before invoking the agent.
188
+
186
189
#### Run the agent locally
187
190
191
+
Before running locally, deploy the connections, toolbox, and agent:
192
+
193
+
```bash
194
+
azd deploy --all
195
+
```
196
+
188
197
```bash
189
198
azd ai agent run
190
199
```
@@ -204,7 +213,7 @@ azd ai agent invoke --local "What tools do you have?"
204
213
Once tested locally, deploy to Microsoft Foundry:
205
214
206
215
```bash
207
-
azd deploy
216
+
azd deploy --all
208
217
```
209
218
210
219
For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent).
@@ -279,9 +288,10 @@ portal **Agent Playground** (signed-in user) and by `azd ai agent invoke` (the d
279
288
so the tools operate as that user and only act on resources the user can already access. The Foundry MCP
280
289
server requires no extra license — just access to the Foundry project.
281
290
282
-
Because the tool acts as a specific user, running the agent **locally** (`python main.py`) or calling the
283
-
endpoint with a raw token uses whatever identity that token represents (`az login` user locally, the
284
-
agent's managed identity when hosted). If that identity has no access to the target resources, the tool
291
+
This tool requires a delegated Microsoft Entra user context. Service-principal or managed-identity
292
+
credentials alone do not satisfy that requirement, even if that identity has access to the target resources.
293
+
The hosted agent can still use managed identity for its own service access when the platform forwards
294
+
the calling user's context. If the calling user has no access to the target resources, the tool
285
295
returns an authorization error even though it is discovered and called correctly.
286
296
287
297
> Some other Entra pass-through MCP servers add their **own** entitlement checks on top of the token. For
0 commit comments