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

The Azure Developer CLI and Visual Studio Code workflows use the Foundry toolbox sample. Its azure.yaml declares web search, code interpreter, and MCP sources for Azure REST API specifications, GitHub, Azure Language, and Microsoft Foundry. Three project connections provide the authenticated sources' credentials and identity settings.

The Python SDK workflow creates a smaller toolbox with web search and the public Microsoft Learn MCP server. It uses the sample's agent code without deploying the sample's additional connection and toolbox declarations.

Use azd 1.34.2 or later and a microsoft.foundry extension bundle that includes azure.ai.agents 1.0.0-beta.19 or later.

Install Python 3.13 or later and prepare the sample's external dependencies before initialization:

The sample doesn't create the external GitHub or Language resources. Initialization prompts for unresolved environment inputs, including the token and Language endpoint, and stores the values in the azd environment. Don't commit credentials, .env files, or .azure.

For the authentication setup, see the sample's Microsoft Entra MCP guide.

For the Python SDK path, use the Python section later in this article instead of the Azure Developer CLI or VS Code workflow. That path creates the toolbox with project_client.toolboxes.create_version(...), then uploads the hosted-agent code as a new version and points it at that toolbox by name.

Install the Python packages used in this path:

pip install "azure-ai-projects>=2.3.0" python-dotenv

You need an existing Foundry project with a deployed chat-capable model. The Python SDK path in this quickstart creates the toolbox and the hosted-agent version, but it doesn't scaffold a new Foundry project or create a model deployment for you.

For the .NET SDK path, use the C# section later in this article instead of the Azure Developer CLI or VS Code workflow. That path creates the toolbox with AgentToolboxes.CreateVersion(...), then uploads the C# hosted-agent code as a new version and points it at that toolbox by name.

You also need the .NET 10 SDK or later, and an existing Foundry project with a deployed chat-capable model.

You also need Visual Studio Code with the Microsoft Foundry Toolkit extension, signed in to Azure.

Step 1: Initialize the hosted agent

In a terminal, create an empty directory and initialize the entire sample project into it:

mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init --template "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src .

Select or create a Foundry project and enter the external input values prepared in Prerequisites. To reuse a model deployment in an existing project, add --model-deployment <existing-deployment-name> to the initialization command. Template adoption doesn't currently provide an existing-deployment picker.

The --src . option selects the project root, not an agent-source subdirectory. Stay in my-toolbox-agent, which now contains azure.yaml, for subsequent azd commands. The agent source remains under src/agent-framework-agent-with-foundry-toolbox-responses.

Review the model declaration and agent settings in azure.yaml before provisioning. To change an external input later, run azd env set <name> <value> from this project root; don't run another azd init.

For the Python agent, ensure its service in azure.yaml includes PYTHONNOUSERSITE: "1" in the existing env map before startup and deployment. Don't rely on loading this setting inside your application. For dependency compatibility guidance, see Configure Python startup.

Open the initialized project folder in Visual Studio Code. Run the following commands in its integrated terminal. This workflow uses the sample's azure.yaml to deploy the connections, toolbox, and agent together; don't create a separate toolbox with the same purpose in the Toolkit.

Step 2: Create the toolbox

The sample declares an agent-tools toolbox as an azure.ai.toolbox service. Its uses entries reference the project and connections; the agent service references the toolbox. Edit these declarations in azure.yaml to change tools or connections.

You don't need a separate toolbox.yaml or a manual azd ai toolbox create command for this workflow. The next step deploys the declarations in dependency order. Provisioning alone doesn't create the toolbox, and local agent startup doesn't create any remote dependencies.

Step 3: Provision Azure resources

An existing Foundry project might still need resources that the template declares, such as a model deployment. Review the configuration, and then provision the project's Azure resources so that its managed identity exists:

azd provision

Before deployment, grant the project's managed identity the Cognitive Services Language Owner role on the existing Language resource as described in the prerequisites. Use the project identity, not the parent Foundry account identity or your own user identity. Allow time for the role assignment to propagate.

Then deploy the connections, toolbox, and hosted agent together:

azd deploy --all

The toolbox deployment produces TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT. The agent's env declaration maps this versioned endpoint to TOOLBOX_ENDPOINT. Inspect the output from the project root:

azd env get-value TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT

Don't overwrite this binding with an endpoint for a separately created toolbox.

Step 4: Run the agent locally

First, complete provisioning, managed-identity authorization, and deployment in Step 3. A local agent still uses the remote connections and toolbox; azd ai agent run doesn't create them. The sample handles the toolbox connection, headers, and authentication for you.

1. After the remote dependencies are deployed, start the agent from the project root:

   azd ai agent run
   

   This command creates a virtual environment, installs dependencies, and serves the agent on http://localhost:8088. The service configuration supplies FOUNDRY_PROJECT_ENDPOINT, AZURE_AI_MODEL_DEPLOYMENT_NAME, and TOOLBOX_ENDPOINT. Don't replace these with placeholder values in a source .env file.

2. In a separate terminal, from the same project root, inspect the available tools and exercise web search:

   azd ai agent invoke --local "List the tools you can use."
   azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web."
   

For VS Code debugging, open the initialized project and follow the sample's VS Code instructions. For F5 or standalone Python runs, set TOOLBOX_ENDPOINT in the agent source folder's .env file to the output of:

azd env get-value TOOLBOX_AGENT_TOOLS_MCP_ENDPOINT

Also set FOUNDRY_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME to your project endpoint and model deployment name. Keep .env out of source control.

Step 5: Deploy to Foundry Agent Service

Step 3 already deploys the hosted agent. After changing tools, connections, or agent code, deploy all services together:

azd deploy --all

This command updates the toolbox and deploys the agent with the resulting versioned endpoint. The VS Code agent-only deployment workflow doesn't update the toolbox or its connections.

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

azd ai agent invoke "List the tools you can use."

The sample uses the versioned endpoint produced by this deployment. This doesn't require promoting the toolbox version to default or redirecting other agents that use an older version.

Python SDK path

Use the following steps if you want to create the toolbox and deploy the hosted-agent version by using the Python SDK instead of the Azure Developer CLI or VS Code flow.

1. Create or choose a Foundry project

1. Open Foundry portal and create a Foundry project, or select an existing one.
2. In the project, deploy a chat-capable model such as gpt-5.4-mini.
3. Copy the project endpoint from Overview and the deployment name from Build > Deployments.

2. Download the toolbox hosted-agent sample

Clone the Foundry samples repo:

git clone https://github.com/microsoft-foundry/foundry-samples.git

Create a working folder for the deployment scripts. In that folder, create a .env file with these values:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

3. Create the toolbox with Python

Create a file named create_toolbox.py in the same working folder as .env:

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WebSearchToolboxTool
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

Run the script:

python create_toolbox.py

The sample hosted agent can resolve the toolbox either from TOOLBOX_ENDPOINT or from FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME. This path uses TOOLBOX_NAME, so you don't need to store the versioned endpoint in .env.

4. Deploy the hosted agent with Python

Create a file named deploy_toolbox_agent.py in the same working folder as .env:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                    "PYTHONNOUSERSITE": "1",
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint

        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

Run the script:

python deploy_toolbox_agent.py

This script uploads the toolbox sample as a new hosted-agent version, points the hosted agent at that version temporarily, invokes it with a Microsoft Learn question, and restores the previous endpoint configuration when it finishes.

5. Verify the toolbox-backed response

If you configure the toolbox correctly, the response shows that the hosted agent discovered the toolbox tools and answered by using Microsoft Learn documentation.

C# SDK path

Use this path to create the toolbox and deploy the C# hosted-agent sample with the .NET SDK instead of the Azure Developer CLI or VS Code workflow.

1. Create or choose a Foundry project

1. Open Foundry portal and create a Foundry project, or select an existing one.
2. In the project, deploy a chat-capable model such as gpt-4o.
3. Copy the project endpoint from Overview and the deployment name from Build > Deployments.

2. Download the toolbox hosted-agent sample

Clone the Foundry samples repo:

git clone https://github.com/microsoft-foundry/foundry-samples.git

The C# hosted-agent sample is under samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. The deployment code in the next steps sets these environment variables on the container:

3. Create the toolbox with C#

Create a .NET console app and install the packages. Toolbox APIs are in preview, so install the prerelease Azure.AI.Projects package:

dotnet new console --name create-toolbox
cd create-toolbox
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Replace Program.cs with the following code and set endpoint to your project endpoint:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AgentToolboxes toolboxes = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ToolboxVersion created = toolboxes.CreateVersion(
    name: toolboxName,
    tools:
    [
        new WebSearchToolboxTool { Name = "web_search", SearchContextSize = WebSearchToolSearchContextSize.Medium },
        new MCPToolboxTool(serverLabel: "mslearn")
        {
            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
        },
    ],
    description: "Toolbox with web search and Microsoft Learn MCP.");
Console.WriteLine($"Created toolbox version {created.Version} for {created.Name}");

Run the app:

dotnet run

The sample hosted agent resolves the toolbox from FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME, so you don't need to store the versioned endpoint.

4. Deploy the hosted agent with C#

Create a second console app for the deployment code:

dotnet new console --name deploy-toolbox-agent
cd deploy-toolbox-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

Replace Program.cs with the following code. Set endpoint, chatModel, and samplePath to your values. samplePath is the full path to the foundry-toolbox-server-side-dotnet-agent-framework source folder you cloned in Step 2:

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var toolboxName = "my-toolbox";
var agentName = "toolbox-agent";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-toolbox-server-side\src\foundry-toolbox-server-side-dotnet-agent-framework";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-toolbox-server-side.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("TOOLBOX_NAME", toolboxName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);
    ResponseResult response = responsesClient.CreateResponse(
        "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation.");
    Console.WriteLine(response.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

Run the app:

dotnet run

This code uploads the toolbox sample as a new hosted-agent version, points the hosted agent at that version temporarily, invokes it with a Microsoft Learn question, and restores the previous endpoint configuration when it finishes.

5. Verify the toolbox-backed response

If you configure the toolbox correctly, the response shows that the hosted agent discovered the toolbox tools and answered by using Microsoft Learn documentation.

Delete the toolbox. Replace <deployed-toolbox-name> with the name of the toolbox created for this quickstart:

azd ai toolbox list
azd ai toolbox delete <deployed-toolbox-name> --force

After you delete the toolbox, its endpoint stops working. Stop the local agent and remove any endpoint you added to src/agent-framework-agent-with-foundry-toolbox-responses/.env for VS Code debugging.

The delete command clears the generated endpoint value from your azd environment. Running azd deploy --all again recreates the toolbox declared in azure.yaml.

Delete the agent and its Azure resources:

azd down

Delete the toolbox by name:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

If you created a dedicated resource group or project for this quickstart, delete it from the Azure portal after you no longer need the toolbox, chat deployment, or hosted agent.

The deployment code already deletes the hosted agent version and restores the previous endpoint configuration when it finishes. To delete the toolbox, add this code to a console app that has the Azure.AI.Projects (prerelease) and Azure.Identity packages installed:

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.AgentAdministrationClient.GetAgentToolboxes().Delete(toolboxName);
Console.WriteLine($"Deleted toolbox '{toolboxName}'.");

If you created a dedicated resource group or project for this quickstart, delete it from the Azure portal after you no longer need the toolbox, chat deployment, or hosted agent.