Skip to content

Commit 20f0728

Browse files
authored
Python: fix Foundry Toolbox quickstart commands and setup steps (#9550)
* docs: point toolbox deployment to canonical Foundry sample * docs: limit toolbox quickstart changes to broken azd steps * docs: preserve toolbox headings and unaffected wording * docs: remove extra deployment project clarification * docs: remove semicolons from added toolbox guidance * docs: align toolbox setup with Foundry sample workflow * docs: restore original toolbox section order * ci: retrigger checks * docs: align toolbox template flag and caller identity requirements
1 parent 4c191ff commit 20f0728

1 file changed

Lines changed: 25 additions & 15 deletions

File tree

  • python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox

‎python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md‎

Lines changed: 25 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -126,18 +126,20 @@ Native code-interpreter file citations are a separate tracked behavior
126126

127127
#### Prerequisites
128128

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)
130130
2. Install the unified Foundry CLI extension bundle (provides `azd ai agent`, `connection`, `inspector`, `project`, `routine`, `skill`, and `toolbox`):
131131
```bash
132132
# If you previously installed individual extensions, uninstall them first:
133133
# azd ext uninstall azure.ai.agents
134134
# azd ext uninstall azure.ai.toolboxes
135135
azd ext install microsoft.foundry
136136
```
137+
Requires `azure.ai.agents` 1.0.0-beta.19 or later for `-t`.
137138
3. Authenticate:
138139
```bash
139140
azd auth login
140141
```
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.
141143

142144
#### Initialize the agent project
143145

@@ -146,10 +148,12 @@ No cloning required. Create a new folder and initialize from the manifest:
146148
```bash
147149
mkdir my-toolbox-agent && cd my-toolbox-agent
148150

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
150152
```
151153

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.
153157

154158
#### Create the toolbox with `azd ai`
155159

@@ -159,32 +163,37 @@ Follow the prompts to configure your Foundry project and model deployment. If yo
159163
> - [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.
160164
> - [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.
161165
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:
163167

164168
```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"
166171
```
167172

168173
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.
169174

170175
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.
171176

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.
177178

178179
#### Provision Azure resources (if needed)
179180

180-
If you don't already have a Foundry project and model deployment:
181+
Provision before deploying so that the project's managed identity exists and can be authorized:
181182

182183
```bash
183184
azd provision
184185
```
185186

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+
186189
#### Run the agent locally
187190

191+
Before running locally, deploy the connections, toolbox, and agent:
192+
193+
```bash
194+
azd deploy --all
195+
```
196+
188197
```bash
189198
azd ai agent run
190199
```
@@ -204,7 +213,7 @@ azd ai agent invoke --local "What tools do you have?"
204213
Once tested locally, deploy to Microsoft Foundry:
205214

206215
```bash
207-
azd deploy
216+
azd deploy --all
208217
```
209218

210219
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
279288
so the tools operate as that user and only act on resources the user can already access. The Foundry MCP
280289
server requires no extra license — just access to the Foundry project.
281290

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
285295
returns an authorization error even though it is discovered and called correctly.
286296

287297
> Some other Entra pass-through MCP servers add their **own** entitlement checks on top of the token. For

0 commit comments

Comments
 (0)