From 4c35a16dad4a17f91c518e1d59cf27e5f510c3fa Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 10:06:42 +0800 Subject: [PATCH 1/9] docs: point toolbox deployment to canonical Foundry sample --- .../responses/foundry_toolbox/README.md | 184 +++--------------- 1 file changed, 25 insertions(+), 159 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index ffd619ea9a5..302c157e996 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -2,6 +2,12 @@ An [Agent Framework](https://github.com/microsoft/agent-framework) agent that uses **Foundry Toolbox** for tool discovery, hosted on Microsoft Foundry using the **Responses protocol**. Foundry Toolbox is a managed tool registry in Microsoft Foundry that lets you define tools centrally and share them across agents. +## Deploy a hosted agent + +For the runnable deployment quickstart, follow the [Foundry Toolbox hosted-agent sample in foundry-samples](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox). That sample maintains the prerequisites, project initialization, connections, toolbox provisioning, deployment, and invocation instructions together with its `azure.yaml`. + +This directory is an Agent Framework integration example for understanding and developing the framework code locally. It is not a second deployment quickstart. Follow the deployment sample in its own project directory with its own source and configuration; do not use its manifest to deploy the code in this directory. + ## Creating a Foundry Toolbox You can create a Foundry Toolbox by code. Refer to this sample for an example: [Foundry Toolbox CRUD Sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/toolboxes/sample_toolboxes_crud.py). @@ -49,49 +55,15 @@ Use the `resource` value (`https://mcp.ai.azure.com`) as the audience. > For connector-backed MCP servers (for example Microsoft 365 / WorkIQ servers such as Outlook Mail), the audience is instead published in the Foundry Tools Catalog. Look it up with the helper scripts in [`scripts/`](scripts/): run `./scripts/list-foundry-connectors.ps1 -ConnectorName ` (or `./scripts/list-foundry-connectors.sh -n `) and read `AzureActiveDirectoryResourceId` (equivalently `resourceUri`) under `properties.x-ms-connection-parameters`. Run the script with no connector name to list every connector with its name, title, and auth type. -### Creating Connections - -Before creating the toolbox, create project connections for any tools that require authentication. The connection defines the authentication details and credentials for the tool, and the toolbox references the connection to authenticate tool invocations at runtime. The following connections are needed for this sample (used in `toolbox.yaml`): - -For `ghmcppat`, run the following command to create a PAT-based connection to the GitHub MCP server: - -```powershell -azd ai connection create ghmcppat --kind remote-tool --target https://api.githubcopilot.com/mcp --auth-type custom-keys --custom-key "Authorization=Bearer " -p https://.services.ai.azure.com/api/projects/ -``` - -For `ghmcpoauth`, create an OAuth2-based connection to the GitHub MCP server: - -```powershell -azd ai connection create ghmcpoauth --kind remote-tool --target https://api.githubcopilot.com/mcp --auth-type oauth2 --connector-name foundrygithubmcp -p https://.services.ai.azure.com/api/projects/ -``` - -> This sample uses `ghmcppat` by default, but you can switch to `ghmcpoauth` in the `toolbox.yaml` file. - -For `langmcpconn`, create an agent-identity-based connection to the Azure Language MCP server: - -```powershell -azd ai connection create langmcpconn --kind remote-tool --target https://.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview --auth-type project-managed-identity --audience https://cognitiveservices.azure.com/ -p https://.services.ai.azure.com/api/projects/ -``` - -For `foundrymcpconn`, create an Entra pass-through connection to the Microsoft Foundry MCP server: - -```powershell -azd ai connection create foundrymcpconn --kind remote-tool --target https://mcp.ai.azure.com --auth-type user-entra-token --audience https://mcp.ai.azure.com -p https://.services.ai.azure.com/api/projects/ -``` - -### Creating the toolbox - -You create the toolbox once from `toolbox.yaml`, then copy the versioned MCP endpoint it prints into the `TOOLBOX_ENDPOINT` environment variable. The agent connects to that endpoint at runtime. +### Project connections -```powershell -azd ai toolbox create agent-tools --from-file ./toolbox.yaml --project-endpoint https://.services.ai.azure.com/api/projects/ -``` +The bundled `toolbox.yaml` references project connections named `ghmcppat` (or `ghmcpoauth` for OAuth2), `langmcpconn`, and `foundrymcpconn`. These connections hold the authentication configuration for the corresponding tools; they must exist in the project hosting that toolbox. See the [Foundry toolbox documentation](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) for toolbox and connection setup. For an end-to-end deployment, use the separate [foundry-samples quickstart](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) and its configuration rather than combining the two projects. ## How it works ### Model Integration -The agent uses `FoundryChatClient` from the Agent Framework to create an OpenAI-compatible Responses client. It connects to the toolbox's MCP endpoint via `MCPStreamableHTTPTool`, which discovers and invokes the toolbox's tools over MCP at runtime. The agent resolves the endpoint from the `TOOLBOX_ENDPOINT` environment variable. If that variable isn't set, it builds the unversioned (default-version) endpoint from `FOUNDRY_PROJECT_ENDPOINT` and `TOOLBOX_NAME`. +The agent uses `FoundryChatClient` from the Agent Framework to create an OpenAI-compatible Responses client. It connects to the toolbox's MCP endpoint via `FoundryToolbox`, which discovers and invokes the toolbox's tools over MCP at runtime. Set `TOOLBOX_ENDPOINT` to the toolbox's versioned MCP endpoint for local development. See [main.py](main.py) for the full implementation. @@ -120,137 +92,31 @@ connections, project roles and consent are separate setup, not offline coverage. Native code-interpreter file citations are a separate tracked behavior (microsoft/agent-framework#7916), not implemented by this lifecycle change. -## Running the agent - -### Option 1: Azure Developer CLI (`azd`) - -#### Prerequisites - -1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.25 or later) -2. Install the unified Foundry CLI extension bundle (provides `azd ai agent`, `connection`, `inspector`, `project`, `routine`, `skill`, and `toolbox`): - ```bash - # If you previously installed individual extensions, uninstall them first: - # azd ext uninstall azure.ai.agents - # azd ext uninstall azure.ai.toolboxes - azd ext install microsoft.foundry - ``` -3. Authenticate: - ```bash - azd auth login - ``` - -#### Initialize the agent project - -No cloning required. Create a new folder and initialize from the manifest: - -```bash -mkdir my-toolbox-agent && cd my-toolbox-agent - -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 -``` - -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. - -#### Create the toolbox with `azd ai` - -> [!TIP] -> If you use GitHub Copilot for Azure to scaffold a hosted agent that consumes this toolbox, the following skill references describe the same endpoint contract (env var, headers, MCP protocol, citation patterns, and troubleshooting) that the agent must implement: -> -> - [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. -> - [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. - -The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. Create the toolbox once from the bundled [`toolbox.yaml`](toolbox.yaml): - -```bash -azd ai toolbox create agent-tools --from-file ./toolbox.yaml --project-endpoint https://.services.ai.azure.com/api/projects/ -``` - -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. - -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 ` when you're ready to make it active. - -`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: - -```bash -azd env set TOOLBOX_ENDPOINT "https://.services.ai.azure.com/api/projects//toolboxes/agent-tools/versions/1/mcp?api-version=v1" -``` - -#### Provision Azure resources (if needed) - -If you don't already have a Foundry project and model deployment: - -```bash -azd provision -``` - -#### Run the agent locally - -```bash -azd ai agent run -``` - -The agent host will start on `http://localhost:8088`. - -#### Invoke the local agent +## Local framework development -In a separate terminal, from the project directory: +Use the current workspace environment described in the [Python development setup](../../../../../DEV_SETUP.md) and the [local hosting guide](../../README.md#running-the-agent-host-locally). The sample's [inline script metadata](main.py) lists its dependencies. Use workspace packages when developing the current hosting APIs; older published packages might not contain them. -```bash -azd ai agent invoke --local "What tools do you have?" -``` +Before running locally, you need an existing Foundry project, a model deployment, and a toolbox with its required project connections and permissions. Local execution does not provision these resources. Copy [`.env.example`](.env.example) to `.env` in this sample directory and set: -#### Deploy to Foundry +| Variable | Value | +| --- | --- | +| `FOUNDRY_PROJECT_ENDPOINT` | The project endpoint, such as `https://your-account.services.ai.azure.com/api/projects/your-project`. | +| `FOUNDRY_MODEL` | The model deployment name in that project. | +| `TOOLBOX_ENDPOINT` | The versioned MCP endpoint of the toolbox you want to use. | -Once tested locally, deploy to Microsoft Foundry: +Authenticate with `az login`. From the repository's `python` directory, run the local source using the configured workspace environment: -```bash -azd deploy +```powershell +uv run --no-sync python samples\04-hosting\foundry-hosted-agents\responses\foundry_toolbox\main.py ``` -For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). - -#### Invoke the deployed agent +The agent host starts on `http://localhost:8088`. Send a Responses request from another terminal: -```bash -azd ai agent invoke "What tools do you have?" +```powershell +Invoke-RestMethod -Method Post -Uri http://localhost:8088/responses -ContentType "application/json" -Body '{"input": "What tools do you have?", "store": false}' ``` -### Option 2: VS Code (Foundry Toolkit) - -#### Prerequisites - -1. **VS Code** with the **[Foundry Toolkit](https://learn.microsoft.com/en-us/azure/foundry/how-to/develop/get-started-projects-vs-code)** extension installed. -2. Sign in to Azure in VS Code. -3. The `agent-tools` toolbox must exist in your Foundry project. Create it from the bundled [`toolbox.yaml`](toolbox.yaml) (`azd ai toolbox create agent-tools --from-file ./toolbox.yaml`) or in the Foundry portal before you run the agent. - -#### Create the project - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. -2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. -3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). - -#### Run and debug the agent - -Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. - -#### Test with Agent Inspector - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. -2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. - -#### Deploy to Foundry - -1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. -2. If prompted, complete **Foundry Project Setup** to select subscription and project. -3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. -4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. -5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. - -### Creating a Foundry Toolbox - -You can create a Foundry Toolbox by code. Refer to this sample for an example: [Foundry Toolbox CRUD Sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/toolboxes/sample_toolboxes_crud.py). - -You can also create a Foundry Toolbox in the Foundry portal. Read more about it [in the Foundry toolbox documentation](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox). +The agent discovers the configured toolbox's tools and answers using the selected model. A local run uses your Azure CLI identity; it does not reproduce hosted caller identity or validate hosted deployment. See the authentication boundaries above and below. ## Troubleshooting @@ -292,7 +158,7 @@ returns an authorization error even though it is discovered and called correctly ## Next steps -- [Quickstart: Create a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent) — end-to-end walkthrough using `azd` +- [Foundry Toolbox deployment quickstart](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) — runnable project with deployment instructions and configuration - [Tool catalog](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog) — browse available tools to extend your agent (Bing Search, Azure AI Search, file search, code interpreter, and more) - [Manage hosted agents](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/manage-hosted-agent) — monitor and manage deployed agents - [Basic agent](../basic/) — minimal agent with no tools From 69a339dc833e7c2788ede201f4853d4e9c1d07ff Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 10:32:24 +0800 Subject: [PATCH 2/9] docs: limit toolbox quickstart changes to broken azd steps --- .../responses/foundry_toolbox/README.md | 180 +++++++++++++++--- 1 file changed, 155 insertions(+), 25 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 302c157e996..ad89a041853 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -2,12 +2,6 @@ An [Agent Framework](https://github.com/microsoft/agent-framework) agent that uses **Foundry Toolbox** for tool discovery, hosted on Microsoft Foundry using the **Responses protocol**. Foundry Toolbox is a managed tool registry in Microsoft Foundry that lets you define tools centrally and share them across agents. -## Deploy a hosted agent - -For the runnable deployment quickstart, follow the [Foundry Toolbox hosted-agent sample in foundry-samples](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox). That sample maintains the prerequisites, project initialization, connections, toolbox provisioning, deployment, and invocation instructions together with its `azure.yaml`. - -This directory is an Agent Framework integration example for understanding and developing the framework code locally. It is not a second deployment quickstart. Follow the deployment sample in its own project directory with its own source and configuration; do not use its manifest to deploy the code in this directory. - ## Creating a Foundry Toolbox You can create a Foundry Toolbox by code. Refer to this sample for an example: [Foundry Toolbox CRUD Sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/toolboxes/sample_toolboxes_crud.py). @@ -55,15 +49,49 @@ Use the `resource` value (`https://mcp.ai.azure.com`) as the audience. > For connector-backed MCP servers (for example Microsoft 365 / WorkIQ servers such as Outlook Mail), the audience is instead published in the Foundry Tools Catalog. Look it up with the helper scripts in [`scripts/`](scripts/): run `./scripts/list-foundry-connectors.ps1 -ConnectorName ` (or `./scripts/list-foundry-connectors.sh -n `) and read `AzureActiveDirectoryResourceId` (equivalently `resourceUri`) under `properties.x-ms-connection-parameters`. Run the script with no connector name to list every connector with its name, title, and auth type. -### Project connections +### Creating Connections + +Before creating the toolbox, create project connections for any tools that require authentication. The connection defines the authentication details and credentials for the tool, and the toolbox references the connection to authenticate tool invocations at runtime. The following connections are needed for this sample (used in `toolbox.yaml`): + +For `ghmcppat`, run the following command to create a PAT-based connection to the GitHub MCP server: + +```powershell +azd ai connection create ghmcppat --kind remote-tool --target https://api.githubcopilot.com/mcp --auth-type custom-keys --custom-key "Authorization=Bearer " -p https://.services.ai.azure.com/api/projects/ +``` + +For `ghmcpoauth`, create an OAuth2-based connection to the GitHub MCP server: + +```powershell +azd ai connection create ghmcpoauth --kind remote-tool --target https://api.githubcopilot.com/mcp --auth-type oauth2 --connector-name foundrygithubmcp -p https://.services.ai.azure.com/api/projects/ +``` + +> This sample uses `ghmcppat` by default, but you can switch to `ghmcpoauth` in the `toolbox.yaml` file. + +For `langmcpconn`, create an agent-identity-based connection to the Azure Language MCP server: + +```powershell +azd ai connection create langmcpconn --kind remote-tool --target https://.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview --auth-type project-managed-identity --audience https://cognitiveservices.azure.com/ -p https://.services.ai.azure.com/api/projects/ +``` + +For `foundrymcpconn`, create an Entra pass-through connection to the Microsoft Foundry MCP server: + +```powershell +azd ai connection create foundrymcpconn --kind remote-tool --target https://mcp.ai.azure.com --auth-type user-entra-token --audience https://mcp.ai.azure.com -p https://.services.ai.azure.com/api/projects/ +``` + +### Creating the toolbox -The bundled `toolbox.yaml` references project connections named `ghmcppat` (or `ghmcpoauth` for OAuth2), `langmcpconn`, and `foundrymcpconn`. These connections hold the authentication configuration for the corresponding tools; they must exist in the project hosting that toolbox. See the [Foundry toolbox documentation](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox) for toolbox and connection setup. For an end-to-end deployment, use the separate [foundry-samples quickstart](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) and its configuration rather than combining the two projects. +You create the toolbox once from `toolbox.yaml`, then copy the versioned MCP endpoint it prints into the `TOOLBOX_ENDPOINT` environment variable. The agent connects to that endpoint at runtime. + +```powershell +azd ai toolbox create agent-tools --from-file ./toolbox.yaml --project-endpoint https://.services.ai.azure.com/api/projects/ +``` ## How it works ### Model Integration -The agent uses `FoundryChatClient` from the Agent Framework to create an OpenAI-compatible Responses client. It connects to the toolbox's MCP endpoint via `FoundryToolbox`, which discovers and invokes the toolbox's tools over MCP at runtime. Set `TOOLBOX_ENDPOINT` to the toolbox's versioned MCP endpoint for local development. +The agent uses `FoundryChatClient` from the Agent Framework to create an OpenAI-compatible Responses client. It connects to the toolbox's MCP endpoint via `MCPStreamableHTTPTool`, which discovers and invokes the toolbox's tools over MCP at runtime. The agent resolves the endpoint from the `TOOLBOX_ENDPOINT` environment variable. If that variable isn't set, it builds the unversioned (default-version) endpoint from `FOUNDRY_PROJECT_ENDPOINT` and `TOOLBOX_NAME`. See [main.py](main.py) for the full implementation. @@ -92,31 +120,133 @@ connections, project roles and consent are separate setup, not offline coverage. Native code-interpreter file citations are a separate tracked behavior (microsoft/agent-framework#7916), not implemented by this lifecycle change. -## Local framework development +## Running the agent -Use the current workspace environment described in the [Python development setup](../../../../../DEV_SETUP.md) and the [local hosting guide](../../README.md#running-the-agent-host-locally). The sample's [inline script metadata](main.py) lists its dependencies. Use workspace packages when developing the current hosting APIs; older published packages might not contain them. +### Option 1: Azure Developer CLI (`azd`) -Before running locally, you need an existing Foundry project, a model deployment, and a toolbox with its required project connections and permissions. Local execution does not provision these resources. Copy [`.env.example`](.env.example) to `.env` in this sample directory and set: +#### Prerequisites -| Variable | Value | -| --- | --- | -| `FOUNDRY_PROJECT_ENDPOINT` | The project endpoint, such as `https://your-account.services.ai.azure.com/api/projects/your-project`. | -| `FOUNDRY_MODEL` | The model deployment name in that project. | -| `TOOLBOX_ENDPOINT` | The versioned MCP endpoint of the toolbox you want to use. | +1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.32.0 or later) +2. Install the unified Foundry CLI extension bundle (provides `azd ai agent`, `connection`, `inspector`, `project`, `routine`, `skill`, and `toolbox`): + ```bash + # If you previously installed individual extensions, uninstall them first: + # azd ext uninstall azure.ai.agents + # azd ext uninstall azure.ai.toolboxes + azd ext install microsoft.foundry + ``` +3. Authenticate: + ```bash + azd auth login + ``` +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. -Authenticate with `az login`. From the repository's `python` directory, run the local source using the configured workspace environment: +#### Initialize the agent project -```powershell -uv run --no-sync python samples\04-hosting\foundry-hosted-agents\responses\foundry_toolbox\main.py +These `azd` steps initialize and run the separate [foundry-samples deployment project](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox), not the framework source in this directory. Its `azure.yaml` manages the connections, toolbox, and hosted agent together; the manual `toolbox.yaml` setup above is for this directory's example. + +No cloning required. Create a new folder and initialize from the manifest: + +```bash +mkdir my-toolbox-agent && cd my-toolbox-agent + +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml --src . ``` -The agent host starts on `http://localhost:8088`. Send a Responses request from another terminal: +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. `--src .` keeps the generated project in the current directory; run the remaining commands there. -```powershell -Invoke-RestMethod -Method Post -Uri http://localhost:8088/responses -ContentType "application/json" -Body '{"input": "What tools do you have?", "store": false}' +#### Configure the toolbox dependencies + +> [!TIP] +> If you use GitHub Copilot for Azure to scaffold a hosted agent that consumes this toolbox, the following skill references describe the same endpoint contract (env var, headers, MCP protocol, citation patterns, and troubleshooting) that the agent must implement: +> +> - [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. +> - [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. + +The initialized `azure.yaml` declares `ghmcppat`, `langmcpconn`, `foundrymcpconn`, and the `agent-tools` toolbox. If initialization did not collect the external dependency values, set them before deployment: + +```bash +azd env set GITHUB_MCP_PAT "" +azd env set AZURE_LANGUAGE_MCP_ENDPOINT "https://.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview" +``` + +#### Provision and deploy + +```bash +azd up +``` + +This deploys the connections and toolbox before the agent. The agent's `TOOLBOX_ENDPOINT` maps to `TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT`, the versioned MCP endpoint produced by the toolbox deployment; do not create a separate toolbox or manually copy its endpoint for this project. + +#### Run the agent locally + +Run `azd up` first: local execution does not provision the connections or toolbox. + +```bash +azd ai agent run +``` + +The agent host will start on `http://localhost:8088`. + +#### Invoke the local agent + +In a separate terminal, from the project directory: + +```bash +azd ai agent invoke --local "What tools do you have?" +``` + +#### Deploy changes to Foundry + +After changing tools, connections, or agent code, redeploy all services: + +```bash +azd deploy --all +``` + +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). + +#### Invoke the deployed agent + +```bash +azd ai agent invoke "What tools do you have?" ``` -The agent discovers the configured toolbox's tools and answers using the selected model. A local run uses your Azure CLI identity; it does not reproduce hosted caller identity or validate hosted deployment. See the authentication boundaries above and below. +### Option 2: VS Code (Foundry Toolkit) + +#### Prerequisites + +1. **VS Code** with the **[Foundry Toolkit](https://learn.microsoft.com/en-us/azure/foundry/how-to/develop/get-started-projects-vs-code)** extension installed. +2. Sign in to Azure in VS Code. +3. The `agent-tools` toolbox must exist in your Foundry project. Create it from the bundled [`toolbox.yaml`](toolbox.yaml) (`azd ai toolbox create agent-tools --from-file ./toolbox.yaml`) or in the Foundry portal before you run the agent. + +#### Create the project + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Create Hosted Agent**. +2. Select this sample from the gallery. The extension scaffolds the project into a new workspace and generates `agent.yaml`, `.env`, and `.vscode/tasks.json` + `launch.json` automatically. +3. Complete the **Foundry Project Setup** to pick the subscription and Foundry project (or create a new one). + +#### Run and debug the agent + +Press **F5** to start the agent in debug mode. The agent host will start on `http://localhost:8088`. + +#### Test with Agent Inspector + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Open Agent Inspector**. +2. The Inspector connects to the running agent. Send messages to chat and view streamed responses. + +#### Deploy to Foundry + +1. Open the Command Palette (`Ctrl+Shift+P`) and run **Foundry Toolkit: Deploy Hosted Agent**. The extension opens a **Deploy Hosted Agent** wizard and reads `agent.yaml` to auto-populate settings. +2. If prompted, complete **Foundry Project Setup** to select subscription and project. +3. On the **Basics** tab, choose deployment method (**Code** or **Container**) and confirm the agent name. +4. On **Review + Deploy**, confirm runtime details, pick **CPU and Memory** size, and click **Deploy**. +5. After deployment, invoke the agent in the Agent Playground and stream live logs from the **Logs** tab. + +### Creating a Foundry Toolbox + +You can create a Foundry Toolbox by code. Refer to this sample for an example: [Foundry Toolbox CRUD Sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/toolboxes/sample_toolboxes_crud.py). + +You can also create a Foundry Toolbox in the Foundry portal. Read more about it [in the Foundry toolbox documentation](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/toolbox). ## Troubleshooting @@ -158,7 +288,7 @@ returns an authorization error even though it is discovered and called correctly ## Next steps -- [Foundry Toolbox deployment quickstart](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox) — runnable project with deployment instructions and configuration +- [Quickstart: Create a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/quickstarts/quickstart-hosted-agent) — end-to-end walkthrough using `azd` - [Tool catalog](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog) — browse available tools to extend your agent (Bing Search, Azure AI Search, file search, code interpreter, and more) - [Manage hosted agents](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/manage-hosted-agent) — monitor and manage deployed agents - [Basic agent](../basic/) — minimal agent with no tools From ced1b0a955419b5e0fb455f4a91a19cd8f21fa87 Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 10:42:44 +0800 Subject: [PATCH 3/9] docs: preserve toolbox headings and unaffected wording --- .../responses/foundry_toolbox/README.md | 26 +++++++++++-------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index ad89a041853..19fc7372878 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -142,7 +142,7 @@ Native code-interpreter file citations are a separate tracked behavior #### Initialize the agent project -These `azd` steps initialize and run the separate [foundry-samples deployment project](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox), not the framework source in this directory. Its `azure.yaml` manages the connections, toolbox, and hosted agent together; the manual `toolbox.yaml` setup above is for this directory's example. +These `azd` steps initialize and run the separate [foundry-samples deployment project](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox), not the framework source in this directory. No cloning required. Create a new folder and initialize from the manifest: @@ -152,9 +152,9 @@ mkdir my-toolbox-agent && cd my-toolbox-agent azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml --src . ``` -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. `--src .` keeps the generated project in the current directory; run the remaining commands there. +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. -#### Configure the toolbox dependencies +#### Create the toolbox with `azd ai` > [!TIP] > If you use GitHub Copilot for Azure to scaffold a hosted agent that consumes this toolbox, the following skill references describe the same endpoint contract (env var, headers, MCP protocol, citation patterns, and troubleshooting) that the agent must implement: @@ -162,25 +162,29 @@ Follow the prompts to configure your Foundry project and model deployment. If yo > - [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. > - [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. -The initialized `azure.yaml` declares `ghmcppat`, `langmcpconn`, `foundrymcpconn`, and the `agent-tools` toolbox. If initialization did not collect the external dependency values, set them before deployment: +The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. The initialized `azure.yaml` declares the toolbox and its connections; `azd up` below creates them. If initialization did not collect the external dependency values, set them before deployment: ```bash azd env set GITHUB_MCP_PAT "" azd env set AZURE_LANGUAGE_MCP_ENDPOINT "https://.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview" ``` -#### Provision and deploy +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. + +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 ` when you're ready to make it active. + +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. + +#### Provision Azure resources (if needed) + +Run this even with an existing Foundry project to create the connections and toolbox before running the agent: ```bash azd up ``` -This deploys the connections and toolbox before the agent. The agent's `TOOLBOX_ENDPOINT` maps to `TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT`, the versioned MCP endpoint produced by the toolbox deployment; do not create a separate toolbox or manually copy its endpoint for this project. - #### Run the agent locally -Run `azd up` first: local execution does not provision the connections or toolbox. - ```bash azd ai agent run ``` @@ -195,9 +199,9 @@ In a separate terminal, from the project directory: azd ai agent invoke --local "What tools do you have?" ``` -#### Deploy changes to Foundry +#### Deploy to Foundry -After changing tools, connections, or agent code, redeploy all services: +Once tested locally, deploy to Microsoft Foundry: ```bash azd deploy --all From b50184e6437bc1720fa474de5d0883e5baac647e Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 10:49:56 +0800 Subject: [PATCH 4/9] docs: remove extra deployment project clarification --- .../foundry-hosted-agents/responses/foundry_toolbox/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 19fc7372878..732607a839a 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -142,8 +142,6 @@ Native code-interpreter file citations are a separate tracked behavior #### Initialize the agent project -These `azd` steps initialize and run the separate [foundry-samples deployment project](https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox), not the framework source in this directory. - No cloning required. Create a new folder and initialize from the manifest: ```bash From 81cee8d4991fd2b1ec8b6190b2548f22d46ed5a1 Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 10:50:58 +0800 Subject: [PATCH 5/9] docs: remove semicolons from added toolbox guidance --- .../responses/foundry_toolbox/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 732607a839a..fb26a6377cd 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -138,7 +138,7 @@ Native code-interpreter file citations are a separate tracked behavior ```bash azd auth login ``` -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. +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. #### Initialize the agent project @@ -160,7 +160,7 @@ Follow the prompts to configure your Foundry project and model deployment. If yo > - [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. > - [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. -The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. The initialized `azure.yaml` declares the toolbox and its connections; `azd up` below creates them. If initialization did not collect the external dependency values, set them before deployment: +The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. The initialized `azure.yaml` declares the toolbox and its connections. `azd up` below creates them. If initialization did not collect the external dependency values, set them before deployment: ```bash azd env set GITHUB_MCP_PAT "" @@ -171,7 +171,7 @@ The first version becomes the default automatically. Use `azd ai toolbox list`, 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 ` when you're ready to make it active. -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. +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. #### Provision Azure resources (if needed) From 8741c2f57931640c13d9892b332d266fe7cfa8e0 Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 11:00:12 +0800 Subject: [PATCH 6/9] docs: align toolbox setup with Foundry sample workflow --- .../responses/foundry_toolbox/README.md | 40 +++++++++++-------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index fb26a6377cd..5b69bba604e 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -147,11 +147,13 @@ No cloning required. Create a new folder and initialize from the manifest: ```bash mkdir my-toolbox-agent && cd my-toolbox-agent -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml --src . +azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml ``` 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. +Run every subsequent command from the initialized project directory containing `azure.yaml`. If initialization reports a different output directory, change to that directory first. + #### Create the toolbox with `azd ai` > [!TIP] @@ -160,7 +162,7 @@ Follow the prompts to configure your Foundry project and model deployment. If yo > - [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. > - [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. -The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. The initialized `azure.yaml` declares the toolbox and its connections. `azd up` below creates them. If initialization did not collect the external dependency values, set them before deployment: +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: ```bash azd env set GITHUB_MCP_PAT "" @@ -175,42 +177,46 @@ The initialized project's `azure.yaml` maps `TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT`, #### Provision Azure resources (if needed) -Run this even with an existing Foundry project to create the connections and toolbox before running the agent: +Provision before deploying so that the project's managed identity exists and can be authorized: ```bash -azd up +azd provision ``` -#### Run the agent locally +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. + +#### Deploy to Foundry + +Deploy all services together so that the connections and toolbox are deployed before the agent: ```bash -azd ai agent run +azd deploy --all ``` -The agent host will start on `http://localhost:8088`. - -#### Invoke the local agent +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -In a separate terminal, from the project directory: +#### Invoke the deployed agent ```bash -azd ai agent invoke --local "What tools do you have?" +azd ai agent invoke "What tools do you have?" ``` -#### Deploy to Foundry +#### Run the agent locally -Once tested locally, deploy to Microsoft Foundry: +Complete provisioning, managed-identity authorization, and deployment above first. Local execution does not create the connections or toolbox. ```bash -azd deploy --all +azd ai agent run ``` -For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). +The agent host will start on `http://localhost:8088`. -#### Invoke the deployed agent +#### Invoke the local agent + +In a separate terminal, from the project directory: ```bash -azd ai agent invoke "What tools do you have?" +azd ai agent invoke --local "What tools do you have?" ``` ### Option 2: VS Code (Foundry Toolkit) From b3e75411d9d33d6a438e006f3060078e0bc2fe8a Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 11:09:15 +0800 Subject: [PATCH 7/9] docs: restore original toolbox section order --- .../responses/foundry_toolbox/README.md | 30 +++++++++++-------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index 5b69bba604e..e3c9f724eb6 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -185,38 +185,42 @@ azd provision 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. -#### Deploy to Foundry +#### Run the agent locally -Deploy all services together so that the connections and toolbox are deployed before the agent: +Before running locally, deploy the connections, toolbox, and agent: ```bash azd deploy --all ``` -For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). +```bash +azd ai agent run +``` -#### Invoke the deployed agent +The agent host will start on `http://localhost:8088`. + +#### Invoke the local agent + +In a separate terminal, from the project directory: ```bash -azd ai agent invoke "What tools do you have?" +azd ai agent invoke --local "What tools do you have?" ``` -#### Run the agent locally +#### Deploy to Foundry -Complete provisioning, managed-identity authorization, and deployment above first. Local execution does not create the connections or toolbox. +Once tested locally, deploy to Microsoft Foundry: ```bash -azd ai agent run +azd deploy --all ``` -The agent host will start on `http://localhost:8088`. - -#### Invoke the local agent +For the full deployment guide, see [Deploy a hosted agent](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent). -In a separate terminal, from the project directory: +#### Invoke the deployed agent ```bash -azd ai agent invoke --local "What tools do you have?" +azd ai agent invoke "What tools do you have?" ``` ### Option 2: VS Code (Foundry Toolkit) From ce7c9fc81f36ae0e165ef1e0f0983bb88137afaa Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 11:28:14 +0800 Subject: [PATCH 8/9] ci: retrigger checks From 0df94512c29e61985f7a06d9e610be6f5c26b8f3 Mon Sep 17 00:00:00 2001 From: huimiu Date: Tue, 20 Oct 2026 13:48:21 +0800 Subject: [PATCH 9/9] docs: align toolbox template flag and caller identity requirements --- .../responses/foundry_toolbox/README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md index e3c9f724eb6..78393322a1f 100644 --- a/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md +++ b/python/samples/04-hosting/foundry-hosted-agents/responses/foundry_toolbox/README.md @@ -126,7 +126,7 @@ Native code-interpreter file citations are a separate tracked behavior #### Prerequisites -1. **Azure Developer CLI (`azd`)** — [Install azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd) (1.32.0 or later) +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) 2. Install the unified Foundry CLI extension bundle (provides `azd ai agent`, `connection`, `inspector`, `project`, `routine`, `skill`, and `toolbox`): ```bash # If you previously installed individual extensions, uninstall them first: @@ -134,6 +134,7 @@ Native code-interpreter file citations are a separate tracked behavior # azd ext uninstall azure.ai.toolboxes azd ext install microsoft.foundry ``` + Requires `azure.ai.agents` 1.0.0-beta.19 or later for `-t`. 3. Authenticate: ```bash azd auth login @@ -147,10 +148,10 @@ No cloning required. Create a new folder and initialize from the manifest: ```bash mkdir my-toolbox-agent && cd my-toolbox-agent -azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml +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 ``` -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. +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. Run every subsequent command from the initialized project directory containing `azure.yaml`. If initialization reports a different output directory, change to that directory first. @@ -287,9 +288,10 @@ portal **Agent Playground** (signed-in user) and by `azd ai agent invoke` (the d so the tools operate as that user and only act on resources the user can already access. The Foundry MCP server requires no extra license — just access to the Foundry project. -Because the tool acts as a specific user, running the agent **locally** (`python main.py`) or calling the -endpoint with a raw token uses whatever identity that token represents (`az login` user locally, the -agent's managed identity when hosted). If that identity has no access to the target resources, the tool +This tool requires a delegated Microsoft Entra user context. Service-principal or managed-identity +credentials alone do not satisfy that requirement, even if that identity has access to the target resources. +The hosted agent can still use managed identity for its own service access when the platform forwards +the calling user's context. If the calling user has no access to the target resources, the tool returns an authorization error even though it is discovered and called correctly. > Some other Entra pass-through MCP servers add their **own** entitlement checks on top of the token. For