Quickstart: Build a toolbox and use it with a hosted agent

Build a Foundry toolbox that combines web search and the Microsoft Learn MCP server, then consume it from a Python hosted agent that connects over the Model Context Protocol.

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

In this quickstart, you build a toolbox that combines two tools behind one managed endpoint:

• Web search, which grounds responses in real-time public web results.
• The Microsoft Learn MCP server, which grounds responses in official Microsoft documentation. It’s a public endpoint that requires no authentication.

You then consume the toolbox from a hosted agent written in Python. The toolbox exposes one MCP endpoint, so the agent connects to a single URL and discovers every tool at runtime. You can change the tools later without changing agent code.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help build the toolbox endpoint, connect it to a hosted agent, and adjust the sample tools.

Prerequisites

This quickstart builds on the hosted-agent toolchain. Complete the Prerequisites in the hosted agent quickstart first, which cover the Azure subscription, project roles, Python, the Azure Developer CLI (azd), and the microsoft.foundry extension.

Step 1: Initialize the hosted agent

Initialize a hosted agent from the Foundry toolbox sample, which connects to a toolbox over MCP and exposes its tools to the model. You create the toolbox (my-toolbox) in the next step and point the agent at its endpoint. Run these commands in an empty directory.

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 src/toolbox-agent

Follow the prompts to select your project and an existing model deployment. When you’re prompted to Select container resource allocation, choose 1 core, 2Gi memory. The agent’s container image needs more than the default tier. The --src flag scaffolds the agent into src/toolbox-agent.

Agent manifests (agent.manifest.yaml) and standalone agent definitions (agent.yaml) are deprecated. As of the Foundry azd extensions (azure.ai.agents 1.0.0-beta.1), all hosted agent configuration lives in a single azure.yaml. See Author azure.yaml for hosted agents.

Step 2: Create the toolbox

Create the toolbox, and then copy the MCP endpoint it returns. Set that endpoint as an environment variable in later steps.

The sample’s azure.yaml defines the toolbox as an azure.ai.toolbox service and wires it to the hosted agent service with uses:. If you change the toolbox configuration, edit the toolbox service in azure.yaml, not src/toolbox-agent/agent.yaml.

First, point the toolbox commands at the Foundry project you selected during initialization. Reuse the endpoint that initialization already stored in your azd environment:

azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value FOUNDRY_PROJECT_ENDPOINT)"

Step 3: Provision Azure resources

The agent reads the toolbox’s MCP endpoint from the TOOLBOX_ENDPOINT environment variable, which azure.yaml resolves from your azd environment. You set that value in the next steps. Provision the agent’s Azure resources:

azd provision

Step 4: Run the agent locally

1. Point the local agent at your toolbox by setting these values in the .env file in src/toolbox-agent. Paste the endpoint you copied in Step 2:

   FOUNDRY_MODEL_NAME=<your-model-deployment-name>
   TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>
   

   azd ai agent run injects FOUNDRY_PROJECT_ENDPOINT and reads the .env file for local runs. The sample handles the toolbox connection, headers, and authentication for you.

2. Start the agent:

   azd ai agent run
   

   This command creates a virtual environment, installs dependencies, and serves the agent on http://localhost:8088. Preview packages can produce pip warnings during setup. These warnings are nonblocking.

3. In a separate terminal, send prompts that exercise the tools:

   azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
   azd ai agent invoke --local "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation."
   

Step 5: Deploy to Foundry Agent Service

Store the endpoint you copied in Step 2 in your azd environment, which azure.yaml resolves at deploy time. Then build and deploy the agent container:

azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy

When the command finishes, the output shows links to the agent playground and the agent endpoint. Invoke the deployed agent:

azd ai agent invoke "What's new in Microsoft Foundry? Use the Microsoft Learn documentation."

Clean up resources

Delete the resources when you’re finished so you stop incurring charges.

Troubleshooting

Issue	Solution
tools/list returns no Microsoft Learn tools	Confirm the mslearn tool in toolbox.yaml points at https://learn.microsoft.com/api/mcp.
The agent starts but reports TOOLBOX_ENDPOINT is set but empty or has no tools	Set TOOLBOX_ENDPOINT to the versioned endpoint from Step 2 in .env for local runs, and run azd env set TOOLBOX_ENDPOINT "<endpoint>" before you deploy.
Calls to the toolbox endpoint fail with an authorization error	Confirm every request includes an Entra token scoped to https://ai.azure.com/.default. The sample handles this for you.
Connection refused on local run	Ensure no other process is using port 8088.

What you learned

In this quickstart, you:

• Built a toolbox that combines web search and the Microsoft Learn MCP server behind one endpoint.
• Consumed the toolbox from a hosted agent that connects over the Model Context Protocol by using Azure Developer CLI, the Python SDK, or the .NET SDK.
• Ran the agent locally or validated it remotely and deployed it to Foundry Agent Service.

Next step

Add a Foundry IQ knowledge base to a hosted agent

Related content

• What are hosted agents?
• Curate an intent-based toolbox in Foundry
• Web search tool
• Connect agents to Model Context Protocol servers
• Quickstart: Deploy your first hosted agent