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

You can create a Foundry Toolbox by code. Refer to this sample for an example: Foundry Toolbox CRUD Sample.

You can also create a Foundry Toolbox in the Foundry portal. Read more about it in the Foundry toolbox documentation.

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.

You can connect to MCP servers in Foundry Toolbox that use different authentication methods. This sample demonstrates the following authentication methods:

• 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
• 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.
• OAuth2 authentication (managed): The tool requires OAuth2 to authenticate. Sample MCP server: https://api.githubcopilot.com/mcp (GitHub MCP server) with OAuth2 for authentication.
• 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.
• 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.

Definitions of these authentication methods can be found in the 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.

There are also Non-MCP tools in the toolbox that support different authentication methods. Learn more at the Foundry sample repository.

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.

See main.py for the full implementation.

1. Azure Developer CLI (azd) — Install azd
2. Install the AI agent extension:

   azd ext install azure.ai.agents

3. Authenticate:

   azd auth login

No cloning required. Create a new folder and initialize from the manifest:

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.

If you don't already have a Foundry project and model deployment:

azd provision

Running azd provision for this sample will also create a Foundry Toolbox with the tools specified in agent.manifest.yaml.

azd ai agent run

The agent host will start on http://localhost:8088.

In a separate terminal, from the project directory:

azd ai agent invoke --local "What tools do you have?"

Once tested locally, deploy to Microsoft Foundry:

azd deploy

For the full deployment guide, see Deploy a hosted agent.

azd ai agent invoke "What tools do you have?"

1. VS Code with the Foundry Toolkit extension installed.
2. Sign in to Azure in VS Code.

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

Press F5 to start the agent in debug mode. The agent host will start on http://localhost:8088.

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.

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.

You can create a Foundry Toolbox by code. Refer to this sample for an example: Foundry Toolbox CRUD Sample.

You can also create a Foundry Toolbox in the Foundry portal. Read more about it in the Foundry toolbox documentation.

• Quickstart: Create a hosted agent — end-to-end walkthrough using azd
• Tool catalog — browse available tools to extend your agent (Bing Search, Azure AI Search, file search, code interpreter, and more)
• Manage hosted agents — monitor and manage deployed agents
• Basic agent — minimal agent with no tools
• Add local tools — sample with locally-defined Python tool functions
• Build multi-agent workflows — sample with chained agent pipelines