Use a toolbox with a hosted agent

Use Microsoft Agent Framework

The maintained Python sample uses FoundryToolbox from the Agent Framework hosting package. The class resolves the toolbox from TOOLBOX_ENDPOINT, or from FOUNDRY_PROJECT_ENDPOINT and TOOLBOX_NAME. It also authenticates MCP requests and forwards the hosted runtime's per-request call ID.

Install Python 3.12 or later, Azure Developer CLI (azd) 1.25 or later, and the microsoft.foundry extension before you initialize the sample.

1. Initialize a project from the hosted-agent toolbox sample:

   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
   

2. Set the toolbox name. The sample constructs the consumer endpoint from the project endpoint and this name:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. Run the agent locally:

   azd ai agent run
   

4. In another terminal, verify that the agent discovers the toolbox tools:

   azd ai agent invoke --local "List the tools you can use and briefly describe each one."
   

The response lists the tools that the toolbox returns from MCP tools/list. If the response contains no toolbox tools, see Troubleshoot the connection.

Use LangGraph

Use AzureAIProjectToolbox when your hosted-agent code is built with LangGraph. The integration loads the toolbox tools as LangChain tools and handles authentication to the consumer endpoint.

1. Install the LangChain Azure integration and its hosting dependencies:

   pip install "langchain-azure-ai[hosting]>=1.2.8"
   

2. Set FOUNDRY_PROJECT_ENDPOINT in the hosted-agent environment. The runtime supplies this value after deployment. Set it yourself for local development.

3. Load the tools by toolbox name:

import asyncio

from langchain_azure_ai.tools import AzureAIProjectToolbox

async def load_tools():
   toolbox = AzureAIProjectToolbox(toolbox_name="<toolbox-name>")
   tools = await toolbox.get_tools()
   print("\n".join(tool.name for tool in tools))

asyncio.run(load_tools())

The output contains the names that the toolbox returns from MCP tools/list:

<tool-name>
<tool-name>

Reference: AzureAIProjectToolbox

1. Pass the loaded tools to your LangGraph agent and run a prompt that requires one of the toolbox tools. For a complete implementation, see the LangGraph toolbox sample.

Use the Agent Framework Foundry hosting integration to register a toolbox by name. AddFoundryToolboxes constructs the consumer endpoint from FOUNDRY_PROJECT_ENDPOINT, calls MCP tools/list during startup, and adds the discovered tools to each agent request.

Install the .NET 10 SDK and Azure CLI before you run the maintained sample.

1. Start from the public hosted toolbox sample, or add the Foundry hosting package to an existing Agent Framework host.

2. Set these environment variables for local development:

   AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
   AZURE_AI_MODEL_DEPLOYMENT_NAME=<model-deployment-name>
   TOOLBOX_NAME=<toolbox-name>
   

   Foundry supplies FOUNDRY_PROJECT_ENDPOINT to the deployed container. Keep the toolbox name in TOOLBOX_NAME; other FOUNDRY_* variable names are reserved by the hosted runtime.

3. In Program.cs, register the agent with AddFoundryResponses, and then register the toolbox with AddFoundryToolboxes(credential, toolboxName). After you build the web application, call MapFoundryResponses before Run. The public sample includes the required imports, packages, agent construction, and credential setup.

4. Start the host, and then invoke it with a prompt that requires a toolbox tool. The /readiness endpoint returns an unhealthy status when the host can't enumerate the toolbox tools.

The hosted-agent toolbox integrations in this article are available for Python and .NET. To call the MCP endpoint from another runtime, use an MCP Streamable HTTP client, authenticate with a token for https://ai.azure.com/.default, and implement the hosted-agent runtime contract.

The hosted-agent toolbox integrations in this article are available for Python and .NET. To call the MCP endpoint from another runtime, use an MCP Streamable HTTP client, authenticate with a token for https://ai.azure.com/.default, and implement the hosted-agent runtime contract.

Use the Microsoft Foundry Toolkit for Visual Studio Code to scaffold a hosted-agent sample that's connected to a toolbox.

Install Visual Studio Code, the Microsoft Foundry Toolkit extension, and the extension pack for your programming language before you scaffold the project.

1. In the Activity Bar, select Foundry Toolkit.
2. Under My Resources, expand your project, and then expand Tools.
3. On the Toolboxes tab, find the toolbox, and then select Scaffold code template.
4. In the Command Palette, select a project folder.
5. Open the generated README.md, and then complete its local run and deployment steps.
6. Run a prompt that requires a toolbox tool and confirm that the agent calls the expected tool.

Pass the toolbox name to a hosted-agent sample that constructs the consumer endpoint from FOUNDRY_PROJECT_ENDPOINT:

Install Azure Developer CLI (azd) 1.25 or later and the microsoft.foundry extension before you run these commands.

1. Inspect the toolbox and its current default version:

   azd ai toolbox show <toolbox-name> --output json
   

   The output uses the endpoint property. The endpoint returned by this command identifies the selected version and is useful for testing that version.

2. Store the toolbox name in the azd environment:

   azd env set TOOLBOX_NAME <toolbox-name>
   

3. To run the hosted agent locally, use:

   azd ai agent run
   

   To deploy the hosted agent instead, use:

   azd deploy
   

If your application accepts only a complete URL, set TOOLBOX_ENDPOINT to the unversioned consumer endpoint from Choose the toolbox endpoint.