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
Copy file name to clipboardExpand all lines: samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/README.md
+28-61Lines changed: 28 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,27 +8,21 @@ You can create a Foundry Toolbox by code. Refer to this sample for an example: [
8
8
9
9
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).
10
10
11
-
> If you set up a project with this sample and provision the resources using `azd provision`, a Foundry Toolbox will be created with the specified tools in [`agent.manifest.yaml`](agent.manifest.yaml).
11
+
This sample consumes a toolbox over its MCP endpoint. It bundles a [`toolbox.yaml`](toolbox.yaml) that defines two connectionless tools behind one endpoint:
12
12
13
-
### Authentication Methods
13
+
-**Web search**, which grounds responses in real-time public web results.
14
+
- The **Microsoft Learn MCP server** (`https://learn.microsoft.com/api/mcp`), a public endpoint that grounds responses in official Microsoft documentation and requires no authentication.
14
15
15
-
You can connect to MCP servers in Foundry Toolbox that use different authentication methods. This sample demonstrates the following authentication methods:
16
+
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.
16
17
17
-
-**No authentication**: The tool does not require any authentication. The agent can invoke the tool without providing any credentials. Sample MCP server: `https://gitmcp.io/Azure/azure-rest-api-specs`
18
-
-**Key-based authentication**: The tool requires a key to authenticate. Sample MCP server: `https://api.githubcopilot.com/mcp` (GitHub MCP server) with a Personal Access Token (PAT) for authentication.
19
-
-**OAuth2 authentication (managed)**: The tool requires OAuth2 to authenticate. Sample MCP server: `https://api.githubcopilot.com/mcp` (GitHub MCP server) with OAuth2 for authentication.
20
-
-**Agent identity authentication**: The tool requires an agent identity token to authenticate. Sample MCP server: `https://{foundry-resource-name}.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview` (Azure Language MCP server) with agent identity for authentication.
21
-
-**Entra Pass-through authentication**: The tool requires an Entra pass-through token to authenticate. Sample MCP server: Microsoft Outlook MCP server with Entra pass-through for authentication.
22
-
23
-
> Definitions of these authentication methods can be found in the [agent.manifest.yaml](agent.manifest.yaml) file in this sample. The GitHub MCP connection defaults to using a PAT for authentication in this sample, but you can switch to OAuth2 by changing the `project_connection_id` field in the `agent.manifest.yaml` file and following the instructions in the comments.
24
-
25
-
There are also Non-MCP tools in the toolbox that support different authentication methods. Learn more at the [Foundry sample repository](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/SUPPORTED_TOOLBOX_SCENARIOS.md).
18
+
> [!NOTE]
19
+
> To attach tools that need credentials (MCP servers with API keys or OAuth, Azure AI Search, Bing Custom Search, and more), create a project connection first and reference it from `toolbox.yaml`. For connection-backed examples, see the [`langgraph-toolbox`](../../../bring-your-own/responses/langgraph-toolbox/README.md) and [`langgraph-toolbox-user-identity`](../../../bring-your-own/responses/langgraph-toolbox-user-identity/README.md) samples, and the [supported toolbox scenarios](https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/SUPPORTED_TOOLBOX_SCENARIOS.md).
26
20
27
21
## How it works
28
22
29
23
### Model Integration
30
24
31
-
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 endpoint URL is provided through the `FOUNDRY_TOOLBOX_ENDPOINT` environment variable.
25
+
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 latest-version endpoint from `FOUNDRY_PROJECT_ENDPOINT` and `TOOLBOX_NAME`.
32
26
33
27
See [main.py](main.py) for the full implementation.
34
28
@@ -51,6 +45,18 @@ See [main.py](main.py) for the full implementation.
51
45
azd auth login
52
46
```
53
47
48
+
#### Initialize the agent project
49
+
50
+
No cloning required. Create a new folder and initialize from the manifest:
51
+
52
+
```bash
53
+
mkdir my-toolbox-agent &&cd my-toolbox-agent
54
+
55
+
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
56
+
```
57
+
58
+
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.
59
+
54
60
#### Create the toolbox with `azd ai`
55
61
56
62
> [!TIP]
@@ -59,60 +65,22 @@ See [main.py](main.py) for the full implementation.
59
65
> -[Toolbox reference](https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/skills/microsoft-foundry/foundry-agent/create/references/toolbox-reference.md) — endpoint format, MCP protocol, OAuth consent handling, citation patterns, and troubleshooting.
60
66
> -[Use toolbox in a hosted agent](https://github.com/microsoft/GitHub-Copilot-for-Azure/blob/main/plugin/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.
61
67
62
-
This sample's agent reads a `TOOLBOX_ENDPOINT` URL at startup. `azd ai agent init` + `azd provision` will create the toolbox declared in [`agent.manifest.yaml`](agent.manifest.yaml) automatically. If you prefer to create the toolbox directly with `azd` (for reuse across agents or to manage versions out-of-band), use the unified `microsoft.foundry` extension:
63
-
64
-
1. Point `azd` at your Foundry project (once per shell):
2. (Connections.) The tools used in this sample — `web_search` and `code_interpreter` — are built-in and do not require project connections, so this step is skipped here. For a connection-backed example (MCP servers with API keys, OAuth, etc.), see the [`langgraph-toolbox`](../../../bring-your-own/responses/langgraph-toolbox/README.md) sample.
72
-
73
-
3. Author a `toolbox.yaml` describing the tools:
68
+
The agent reads the toolbox's MCP endpoint from `TOOLBOX_ENDPOINT`. Create the toolbox once from the bundled [`toolbox.yaml`](toolbox.yaml):
74
69
75
-
```yaml
76
-
# toolbox.yaml
77
-
description: Web search + code interpreter for the agent-framework Foundry-toolbox sample
78
-
tools:
79
-
- type: web_search
80
-
name: web_search
81
-
- type: code_interpreter
82
-
name: code_interpreter
83
-
container:
84
-
type: auto
85
-
```
86
-
87
-
4. Create the toolbox from that file:
88
-
89
-
```bash
90
-
azd ai toolbox create agent-tools --from-file ./toolbox.yaml
91
-
```
92
-
93
-
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.
70
+
```bash
71
+
azd ai toolbox create my-toolbox --from-file ./toolbox.yaml
72
+
```
94
73
95
-
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.
74
+
The first version becomes the default automatically. Use `azd ai toolbox list`, `azd ai toolbox show my-toolbox`, and `azd ai toolbox version list my-toolbox` to inspect, and `azd ai toolbox delete my-toolbox --force`to remove it.
96
75
97
-
5. Retrieve the MCP endpoint and pass it to the agent. The agent uses `client.get_toolbox("agent-tools")`, which resolves through `TOOLBOX_ENDPOINT`:
76
+
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 my-toolbox <version>` when you're ready to make it active.
98
77
99
-
```bash
100
-
azd ai toolbox show agent-tools --output json # returns the MCP endpoint URL
101
-
azd env set TOOLBOX_ENDPOINT "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/agent-tools/mcp?api-version=v1"
102
-
```
103
-
104
-
#### Initialize the agent project
105
-
106
-
No cloning required. Create a new folder and initialize from the manifest:
78
+
`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:
107
79
108
80
```bash
109
-
mkdir my-toolbox-agent &&cd my-toolbox-agent
110
-
111
-
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
81
+
azd env set TOOLBOX_ENDPOINT "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1"
112
82
```
113
83
114
-
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.
115
-
116
84
#### Provision Azure resources (if needed)
117
85
118
86
If you don't already have a Foundry project and model deployment:
@@ -121,8 +89,6 @@ If you don't already have a Foundry project and model deployment:
121
89
azd provision
122
90
```
123
91
124
-
> Running `azd provision` for this sample will also create a Foundry Toolbox with the tools specified in [`agent.manifest.yaml`](agent.manifest.yaml).
125
-
126
92
#### Run the agent locally
127
93
128
94
```bash
@@ -161,6 +127,7 @@ azd ai agent invoke "What tools do you have?"
161
127
162
128
1.**VS Code** with the **[Foundry Toolkit](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.azure-ai-foundry)** extension installed.
163
129
2. Sign in to Azure in VS Code.
130
+
3. The `my-toolbox` toolbox must exist in your Foundry project. Create it from the bundled [`toolbox.yaml`](toolbox.yaml) (`azd ai toolbox create my-toolbox --from-file ./toolbox.yaml`) or in the Foundry portal before you run the agent.
Copy file name to clipboardExpand all lines: samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/agent.manifest.yaml
+7-56Lines changed: 7 additions & 56 deletions
Original file line number
Diff line number
Diff line change
@@ -17,63 +17,14 @@ template:
17
17
environment_variables:
18
18
- name: AZURE_AI_MODEL_DEPLOYMENT_NAME
19
19
value: "{{AZURE_AI_MODEL_DEPLOYMENT_NAME}}"
20
-
- name: TOOLBOX_NAME
21
-
value: "agent-tools"
22
-
# Parameters are declared as a map of name -> definition. azd looks for an env
23
-
# var matching the parameter name (e.g. github_pat) to resolve secret values for
24
-
# `azd ai agent init --no-prompt`. The array/`properties` form does NOT bind
25
-
# secret parameters to env vars, so it fails no-prompt init — use the map form.
26
-
parameters:
27
-
mcp_endpoint:
28
-
# `azd ai agent init -m` will prompt for this value when initializing the agent manifest
29
-
secret: false
30
-
description: URL of the public MCP server (e.g. https://gitmcp.io/Azure/azure-rest-api-specs) that does not require authentication
31
-
github_pat:
32
-
# `azd ai agent init -m` will prompt for this value when initializing the agent manifest.
33
-
# Only needed when the GitHub MCP connection is configured to use the `github-mcp-pat-conn`
34
-
# PAT-based connection below; if you use the `github-mcp-oauth-conn` OAuth2 connection
35
-
# instead, you can leave this empty.
36
-
secret: true
37
-
description: GitHub Personal Access Token used to authenticate with the GitHub MCP server (only needed when using the PAT connection; press Enter if using OAuth2 instead)
20
+
# Full MCP endpoint of the toolbox the agent consumes. Create the toolbox
21
+
# from the bundled toolbox.yaml, then copy the versioned endpoint it prints
22
+
# and store it in your azd environment before you run or deploy:
23
+
# azd ai toolbox create my-toolbox --from-file ./toolbox.yaml
24
+
# azd env set TOOLBOX_ENDPOINT "<endpoint-from-output>"
25
+
- name: TOOLBOX_ENDPOINT
26
+
value: "{{TOOLBOX_ENDPOINT}}"
38
27
resources:
39
28
- kind: model
40
29
id: gpt-4.1
41
30
name: AZURE_AI_MODEL_DEPLOYMENT_NAME
42
-
- kind: connection
43
-
# A connection that uses a GitHub Personal Access Token (PAT) to authenticate with the GitHub MCP server
44
-
name: github-mcp-pat-conn
45
-
category: RemoteTool
46
-
authType: CustomKeys
47
-
target: https://api.githubcopilot.com/mcp
48
-
credentials:
49
-
type: CustomKeys
50
-
keys:
51
-
Authorization: "Bearer {{ github_pat }}"
52
-
- kind: connection
53
-
# A connection that uses OAuth2 to authenticate with the GitHub MCP server
54
-
name: github-mcp-oauth-conn
55
-
category: RemoteTool
56
-
authType: OAuth2
57
-
target: https://api.githubcopilot.com/mcp
58
-
connectorName: foundrygithubmcp
59
-
credentials:
60
-
type: OAuth2
61
-
clientId: managed
62
-
clientSecret: managed
63
-
- kind: toolbox
64
-
name: agent-tools
65
-
tools:
66
-
- type: web_search
67
-
name: web_search
68
-
- type: code_interpreter
69
-
name: code_interpreter
70
-
- type: mcp
71
-
# This MCP tool doesn't require authentication
72
-
server_label: noauth_mcp
73
-
server_url: "{{ mcp_endpoint }}"
74
-
require_approval: "never"
75
-
- type: mcp
76
-
# This MCP tool uses the GitHub MCP server with a PAT for authentication or OAuth2
77
-
server_label: github
78
-
project_connection_id: github-mcp-pat-conn # use `github-mcp-oauth-conn` for OAuth2 authentication
![foundry-samples-repo-sync[bot]](https://avatars.githubusercontent.com/u/42854725?v=4&size=40){kind=avatar}
0 commit comments