Create and manage a toolbox in Foundry

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, ToolSearchToolboxTool, WebSearchTool

# Create Foundry project client
endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Create toolbox version with web search and MCP tools
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchTool(),
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolSearchToolboxTool(),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

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

// Create Foundry project client
var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool());

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval
    )
));

ToolSearchToolboxTool searchTool = new() { Name = "ToolBoxSearch" };

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool, searchTool],
    description: "Toolbox with web search, MCP, and tool search"
);
Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with web search, MCP, and tool search",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    },
    {
      "type": "toolbox_search"
    }
  ]
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Create Foundry project client
const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";

const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "web_search",
      description: "Search the web for current information",
    },
    {
      type: "mcp",
      server_label: "myserver",
      server_url: "https://your-mcp-server.example.com",
      require_approval: "never",
      project_connection_id: "my-key-auth-connection",
    },
    { type: "toolbox_search" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Use the Microsoft Foundry Toolkit for Visual Studio Code extension to create and publish a toolbox from the Tools view.

1. Select Foundry Toolkit in the Activity Bar.
2. Under My Resources, expand Your project name > Tools.
3. Select the + Add Toolbox icon.
4. On the Build a Custom Toolbox tab, enter the toolbox name and description, and add the tools you want.
5. To enable intent-based tool routing, select Tool search.
6. Select Publish.

Publishing a new toolbox creates its first version. That version becomes the default version automatically.

With the unified microsoft.foundry extension bundle (see Prerequisites), create a toolbox in two steps:

1. Use azd ai connection create to register each project connection that the toolbox references (one call per credential record).
2. Use azd ai toolbox create --from-file <toolbox.yaml> to create the toolbox. The YAML references connections by name and never embeds credentials.

The pattern is the same for every connection kind and auth type:

1. Set the active project once per shell:

   azd ai project set $PROJECT_ENDPOINT
   

2. Create a connection with azd ai connection create. The flags differ per auth type, but the command shape is always:

   azd ai connection create <name> \
     --kind <remote-tool|remote-a2a|cognitive-search|GroundingWithCustomSearch> \
     --target <endpoint-url> \
     --auth-type <none|custom-keys|api-key|oauth2|user-entra-token|project-managed-identity|agentic-identity> \
     [--custom-key "Header=Value" | --key <key> | --client-id ... --client-secret ... --authorization-url ... --token-url ... | --audience <aad-resource-uri>]
   

   Use azd ai connection list and azd ai connection show <name> to inspect connections, and azd ai connection delete <name> --force to remove them.

3. Author a toolbox YAML that references one or more existing connections by name. The YAML never embeds credentials:

   # my-toolbox.yaml
   description: <human-readable description>
   connections:
     - name: <project-connection-name>   # must already exist in the project
   # Optional: add connectionless built-in tools and policies.
   tools:
     - type: web_search
       name: web
     - type: code_interpreter
       container: { type: auto }
       name: code
     # Tool search is connectionless.
     - type: toolbox_search
     # For Azure AI Search, set the index in the tool entry:
     # - type: azure_ai_search
     #   name: search
     #   azure_ai_search:
     #     indexes:
     #       - project_connection_id: <azure-ai-search-connection-name>
     #         index_name: <search-index-name>
     # For Bing Custom Search, set the instance in the tool entry:
     # - type: bing_custom_search
     #   name: bing
     #   custom_search_configuration:
     #     project_connection_id: <bing-connection-name>
     #     instance_name: <bing-instance-name>
   # Optional: attach existing project skills as MCP resources.
   skills:
     - name: <skill-name>          # uses the skill's default version
     - name: <other-skill>
       version: "2"               # pin to a specific skill version (string)
   policies:
     rai_config:
       rai_policy_name: <policy-name>    # must already exist on the project
   

   At least one of connections, skills, or tools must be non-empty. Skill references must point to skills that already exist in the same Foundry project; see Use skills in Foundry to create them with azd ai skill create. For end-to-end Tool Search setup details, see Use tool search.

4. Create the toolbox from that file:

   azd ai toolbox create <toolbox-name> --from-file ./my-toolbox.yaml
   

   The first version becomes the default automatically. Use azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name>, and azd ai toolbox delete <name> --force to manage toolboxes.

Example: MCP server with key-based auth

# 1. Create the connection
azd ai connection create my-gh-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# 2. Create the toolbox
azd ai toolbox create my-toolbox \
  --from-file ./my-toolbox.yaml \
  --no-prompt

# my-toolbox.yaml
description: GitHub MCP toolbox
connections:
  - name: my-gh-conn

In the Microsoft Foundry Toolkit for Visual Studio Code extension, copy the toolbox consumer endpoint from the Toolboxes view.

1. Select Foundry Toolkit in the Activity Bar.
2. Under My Resources, expand Your project name > Tools.
3. On the Toolboxes tab, locate your toolbox.
4. In the Endpoint URL column, copy the endpoint.

The Endpoint URL value is the toolbox consumer endpoint. To construct a version-specific endpoint, use the developer pattern shown in the previous table.

Install the MCP client SDK:

pip install mcp

Connect to the toolbox and list tools

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            # Call a tool (replace with actual tool name and arguments)
            result = await session.call_tool("<tool_name>", arguments={})
            print(result)

asyncio.run(verify_toolbox())

Use the version-specific endpoint (/versions/{version}/mcp) to validate a version before promoting it.

1. Initialize the MCP session:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. Send the initialized notification:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. List available tools:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

4. Call a tool:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<TOOL_NAME>","arguments":{}}}

Install the MCP client SDK:

npm install @modelcontextprotocol/sdk

Connect to the toolbox and list tools

import { DefaultAzureCredential } from "@azure/identity";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1";

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");

const transport = new StreamableHTTPClientTransport(
  new URL(url),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${token.token}`,
      },
    },
  },
);

const client = new Client({ name: "test", version: "1.0" });
await client.connect(transport);

// List available tools
const toolsResult = await client.listTools();
console.log(`Tools found: ${toolsResult.tools.length}`);
for (const tool of toolsResult.tools) {
  console.log(`  - ${tool.name}: ${(tool.description || "").slice(0, 80)}`);
}

// Call a tool (replace with actual tool name and arguments)
const result = await client.callTool({ name: "<tool_name>", arguments: {} });
console.log(result);

await client.close();

Use the endpoint from Step 2 together with a scaffolded hosted agent sample to validate toolbox loading in VS Code.

1. In Foundry Toolkit, under My Resources > Your project name > Tools, locate the toolbox you want to test.
2. Select Scaffold code template.
3. Choose a project folder when prompted.
4. Follow the generated README.md to install dependencies, configure environment variables, and run the sample locally.
5. Use Agent Inspector or run python main.py to confirm the toolbox tools load and respond.

For version-specific validation before you promote a new toolbox version, use the Python or REST API tab in this step.

LangGraph

See the full sample for the complete implementation.

.env file:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (key pattern):

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name=TOOLBOX_NAME)
tools = await toolbox.get_tools()

Microsoft Agent Framework

Use MCPStreamableHTTPTool from the Agent Framework SDK to connect directly to the toolbox MCP endpoint.

.env file:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (key pattern):

# Auth: wrap token provider in an httpx.Auth subclass
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
http_client = httpx.AsyncClient(
    auth=_ToolboxAuth(token_provider),
    timeout=120.0,
)

# Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_ENDPOINT)
TOOLBOX_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1"

# Connect MCPStreamableHTTPTool to the toolbox endpoint
mcp_tool = MCPStreamableHTTPTool(
    name="toolbox",
    url=TOOLBOX_ENDPOINT,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="my-toolbox-agent",
    instructions="You are a helpful assistant with access to Foundry toolbox tools.",
    tools=[mcp_tool],
)
ResponsesAgentServerHost().run()

See the full sample for the complete implementation.

Copilot SDK

Use the GitHub Copilot SDK to build a toolbox-powered agent that bridges Copilot's tool invocation to the Foundry toolbox MCP endpoint.

.env file:

GITHUB_TOKEN=<your-github-token>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

agent.py (key pattern — MCP bridge):

# 1. Open an MCP session to the toolbox endpoint
bridge = McpBridge(endpoint=TOOLBOX_ENDPOINT, token=_get_toolbox_token())
await bridge.initialize()
mcp_tools = await bridge.list_tools()

# 2. Map MCP tool list to Copilot SDK tool definitions
#    Dots in tool names are replaced with underscores (Copilot SDK requirement)
copilot_tools = [
    {
        "name": t["name"].replace(".", "_"),
        "description": t.get("description", ""),
        "parameters": t.get("inputSchema", {}),
    }
    for t in mcp_tools
]

# 3. Wire tool calls back to the MCP session
async def tool_handler(name: str, arguments: dict) -> str:
    return await bridge.call_tool(name.replace("_", ".", 1), arguments)

# 4. Run the Copilot SDK agent
agent = Agent(
    tools=copilot_tools,
    tool_handler=tool_handler,
    token=os.environ["GITHUB_TOKEN"],
)

Microsoft Agent Framework

Use ResponsesServer from the Agent Framework SDK with a custom ToolboxMcpClient to discover and invoke toolbox tools through the MCP endpoint.

Environment variables:

AZURE_OPENAI_ENDPOINT=https://<account>.services.ai.azure.com
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_MCP_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

Program.cs (key pattern):

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

// Azure OpenAI endpoint and model deployment
var openAiEndpoint = "https://<account>.services.ai.azure.com";
var deployment = "gpt-4o";  // supports all toolbox tool types

// Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_MCP_ENDPOINT)
var toolboxEndpoint = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1";

// Azure OpenAI client
var credential = new DefaultAzureCredential();
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
var chatClient = openAIClient.GetChatClient(deployment);

// Toolbox MCP client — discovers tools via tools/list, calls them via tools/call
var toolboxClient = new ToolboxMcpClient(toolboxEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

ToolboxMcpClient wraps direct JSON-RPC calls to the MCP endpoint. ToolboxHandler connects LLM tool calls back to the MCP client by using a standard tool-calling loop. For the complete implementation of both classes, see the full sample.

Use the Microsoft Foundry Toolkit for Visual Studio Code extension to scaffold a Hosted agent sample that's already wired to your toolbox.

1. Select Foundry Toolkit in the Activity Bar.
2. Under My Resources, expand Your project name > Tools.
3. On the Toolboxes tab, locate the toolbox you want to consume, and then select Scaffold code template.
4. In the Command Palette, choose a project folder when prompted.
5. Open the generated README.md and follow the setup, local run, and deployment steps for the scaffold.

The generated project includes the Hosted agent entry point, deployment files, and a README.md with the exact setup, run, and deployment steps.

If you want to integrate a toolbox into an existing hosted agent project instead of generating a new sample, use the copied endpoint from Step 2 with the Python or .NET patterns in this section.

Pass the toolbox endpoint to your agent

After you create the toolbox in Step 1, retrieve its MCP endpoint by using azd ai toolbox show and pass that endpoint to your agent code as an environment variable. The agent reads the variable at startup and uses it to connect to the toolbox.

1. Get the toolbox endpoint:

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

   The endpoint field in the response identifies the selected version. Use it to test that version before promotion. For an agent that should follow default_version, construct the unversioned consumer endpoint shown in Step 2.

2. Set the endpoint as an environment variable that your agent reads at startup:

   # .env (or however your runtime loads environment variables)
   TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1
   

3. In your agent code, read TOOLBOX_ENDPOINT and connect to it with an MCP client. Use the Python or .NET integration patterns earlier in this section as a reference for the client setup, and the Entra token (https://ai.azure.com/.default scope).

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    tools=[
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="always",  # "always" | "never"
            project_connection_id="my-connection",
        )
    ],
)

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always",
      "project_connection_id": "my-connection"
    }
  ]
}

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval
    )
));

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    require_approval: "always",
    project_connection_id: "my-connection",
  },
];

Use the Python, .NET, JavaScript, REST API, or Azure Developer CLI tab to configure require_approval in your toolbox definition. The Microsoft Foundry Toolkit for Visual Studio Code extension workflow in this article focuses on creating and consuming the toolbox in Visual Studio Code.

resources:
  - kind: toolbox
    name: my-toolbox
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        require_approval: always
        project_connection_id: my-connection

# Create a new toolbox version
toolbox_version = project.toolboxes.create_toolbox_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "<toolbox-name>",
    tools: [tool],
    description: "Updated tools v2"
);
Console.WriteLine($"Created version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Updated tools v2",
  "tools": [...]
}

const toolboxVersion = await project.toolboxes.createVersion(
  "<toolbox-name>",
  [/* tools array */],
  { description: "Updated tools v2" },
);
console.log(`Created version: ${toolboxVersion.version}`);

Use the Python, .NET, JavaScript, or REST API tab to create a new toolbox version. The Microsoft Foundry Toolkit for Visual Studio Code extension workflow in this article focuses on creating a toolbox and scaffolding a Hosted agent that consumes it.

This operation isn't supported with the Azure Developer CLI. To create a toolbox version, use the Python, .NET, REST API, or JavaScript tab.

# List all toolbox versions
versions = list(project.toolboxes.list_toolbox_versions(name="<toolbox-name>"))
for v in versions:
    print(f"{v.version} — created {v.created_at}")

List<ToolboxVersion> versions = await toolboxClient
    .GetToolboxVersionsAsync("<toolbox-name>")
    .ToListAsync();
Console.WriteLine($"Found {versions.Count} toolbox version(s).");
foreach (ToolboxVersion v in versions)
{
    Console.WriteLine($"  - {v.Name} ({v.Version})");
}

GET {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}

const versions = project.toolboxes.listVersions("<toolbox-name>");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.created_at}`);
}

Use the Python, .NET, JavaScript, or REST API tab to list toolbox versions.

# The current default version is marked with *
azd ai toolbox version list <toolbox-name>

# Get a specific toolbox version
version_obj = project.toolboxes.get_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

ToolboxVersion versionObj = await toolboxClient.GetToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Retrieved toolbox: {versionObj.Name} ({versionObj.Id})");

GET {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

const versionObj = await project.toolboxes.getVersion(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Retrieved version: ${versionObj.version}`);

Use the Python, .NET, JavaScript, or REST API tab to get a specific toolbox version.

azd ai toolbox version get <toolbox-name> <version_id>

# Promote a version to default
toolbox = project.toolboxes.update(
    toolbox_name="<toolbox-name>",
    default_version="<version_id>",
)
print(f"Active version: {toolbox.default_version}")

ToolboxRecord record = await toolboxClient.UpdateToolboxAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Active version: {record.DefaultVersion}");

PATCH {project_endpoint}/toolboxes/<toolbox-name>?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "default_version": "<version_id>"
}

default_version can't be empty. Replace it with a new version.

const toolbox = await project.toolboxes.update(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Active version: ${toolbox.default_version}`);

Use the Python, .NET, JavaScript, or REST API tab to promote a toolbox version to default.

Toolbox versions are immutable. Use publish to make any existing version the new default:

# Roll back or forward to a specific version
azd ai toolbox publish <toolbox-name> <version_id> --no-prompt

publish is the only path that changes default_version from the CLI; mutating verbs (connection add/remove, skill add/remove) always create a new version without promoting it.

# Delete a toolbox version
project.toolboxes.delete_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

await toolboxClient.DeleteToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);

DELETE {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

await project.toolboxes.deleteVersion(
  "<toolbox-name>",
  "<version_id>",
);

Use the Python, .NET, JavaScript, or REST API tab to delete a toolbox version.

This operation isn't supported with the Azure Developer CLI. To delete a toolbox version, use the Python, .NET, REST API, or JavaScript tab.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WebSearchTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchTool()],
    policies={
        "rai_config": {
            "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
        }
    },
)
print(f"Created version: {toolbox_version.version}")

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with guardrail",
  "tools": [{ "type": "web_search" }],
  "policies": {
    "rai_config": {
      "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
    }
  }
}

#pragma warning disable AAIP001
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

var toolboxVersion = toolboxClient.CreateToolboxVersion(
    toolboxName: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchTool()],
    policies: new ToolboxPolicies
    {
        RaiConfig = new RaiConfig { RaiPolicyName = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>" }
    });
Console.WriteLine($"Created version: {toolboxVersion.Version}");

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [{ type: "web_search" }],
  {
    description: "Toolbox with guardrail",
    policies: {
      rai_config: {
        rai_policy_name: "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>",
      },
    },
  },
);
console.log(`Created version: ${toolboxVersion.version}`);

name: my-toolbox
description: Toolbox with guardrail
policies:
  rai_config:
    rai_policy_name: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>
tools:
  - type: web_search

Guardrail configuration isn't yet available in the VS Code extension. Use the REST API, SDK, or Azure Developer CLI to configure guardrails.

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Foundry-Features: Skills=V1Preview

{
  "description": "Toolbox with a skill reference",
  "tools": [],
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting"
    }
  ]
}

To pin a specific version:

{
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting",
      "version": "v1"
    }
  ]
}

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="v1"),  # pin to v1
    ],
)
print(f"Created toolbox version: {toolbox_version.id}")

#pragma warning disable AAIP001
// Reuse the AgentToolboxes client (toolboxClient) from Step 1.
ToolboxSkillReference skillRef = new("greeting");
// To pin a version: new ToolboxSkillReference("greeting") { Version = "v1" }

ToolboxVersion toolboxVersion = toolboxClient.CreateToolboxVersion(
    name: "my-toolbox",
    tools: [],
    skills: [skillRef],
    description: "Toolbox with a skill reference"
);
Console.WriteLine($"Created toolbox version: {toolboxVersion.Id}");

const toolboxVersion = await project.beta.toolboxes.createVersion(
  "my-toolbox",
  [],
  {
    description: "Toolbox with a skill reference",
    skills: [
      { type: "skill_reference", name: "greeting" },
      // { type: "skill_reference", name: "greeting", version: "v1" },  // pin to v1
    ],
  },
);
console.log(`Created toolbox version: ${toolboxVersion.id}`);

The Azure Developer CLI supports skill references in two places: declaratively as a top-level skills: block in the azd ai toolbox create --from-file YAML, and imperatively with the azd ai toolbox skill add/list/remove verbs. Each reference takes a name (required) and an optional version (string). Omit version to follow the skill's default_version; pin a version string to lock the toolbox to an immutable snapshot.

Declare skills when you create the toolbox

# my-toolbox.yaml
description: Toolbox with skill references
connections:
  - name: my-gh-conn
skills:
  - name: greeting              # follows the skill's default version
  - name: review-checklist
    version: "2"               # pin to skill version 2

azd ai toolbox create my-toolbox --from-file ./my-toolbox.yaml --no-prompt

Add, list, and remove skills on an existing toolbox

# Add a skill (follows default version)
azd ai toolbox skill add my-toolbox greeting

# Add a skill pinned to a specific version
azd ai toolbox skill add my-toolbox review-checklist@2

# Add multiple skills from a file (same shape as the create YAML's skills block)
azd ai toolbox skill add my-toolbox --from-file ./skills.yaml

# List skill references on the current default version
azd ai toolbox skill list my-toolbox --output table

# Remove a skill (--force skips the confirmation prompt; multiple names allowed)
azd ai toolbox skill remove my-toolbox greeting --force

skill list shows only the default version. Pinned skills show their version; unpinned skills show (default). To inspect skills on a pending version, run azd ai toolbox show <toolbox> --version <n> --output json and read the skills array.

Skill names must match ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (lowercase letters, digits, and hyphens; max 64 characters; no leading or trailing hyphen). A trailing @ in <name>@<version> (an empty version) is rejected.

Skill references aren't currently configurable through the VS Code extension. Use the REST API or SDK to configure skills.

Validate skill discovery

After attaching skills to a toolbox version, verify that you can discover them through the toolbox MCP endpoint by using the MCP Python SDK:

import asyncio
from azure.identity import DefaultAzureCredential
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def list_skills():
    credential = DefaultAzureCredential()
    token = credential.get_token("https://ai.azure.com/.default").token
    toolbox_url = "{endpoint}/toolboxes/my-toolbox/mcp?api-version=v1"
    headers = {
        "Authorization": f"Bearer {token}",
    }
    async with streamablehttp_client(toolbox_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            resources = await session.list_resources()
            for resource in resources.resources:
                print(f"Skill: {resource.uri} - {resource.name}")

asyncio.run(list_skills())

Skills appear as MCP resources with URIs in the format skill://{name}.

Consume skills from an agent (Microsoft Agent Framework, .NET)

In .NET, use AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) from the Microsoft Agent Framework SDK to discover MCP-based skills from a toolbox endpoint and inject them as AIContextProviders on the agent. The agent then loads each skill's instructions at runtime when the model decides it's relevant. The following Program.cs hosts the agent with the Responses hosting layer (AddFoundryResponses and MapFoundryResponses).

using System.Net.Http.Headers;
using Azure.AI.Projects;
using Azure.Core;
using Azure.Identity;
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Load .env file if present (for local development).
Env.TraversePath().Load();

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.");

string deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.");

string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME environment variable is not set.");

// Build the Foundry Toolbox MCP URL from the project endpoint and toolbox name.
string toolboxMcpServerUrl = $"{projectEndpoint.TrimEnd('/')}/toolboxes/{toolboxName}/mcp?api-version=v1";

TokenCredential credential = new DefaultAzureCredential();

// HttpClient that attaches a fresh Foundry bearer token to every request.
// CheckCertificateRevocationList = true satisfies CA5399.
using var httpClient = new HttpClient(
    new BearerTokenHandler(credential, "https://ai.azure.com/.default")
    {
        CheckCertificateRevocationList = true,
    });

Console.WriteLine($"Connecting to Foundry Toolbox '{toolboxName}' MCP server...");

// Connect to the Foundry Toolbox MCP endpoint.
// The Foundry-Features: Toolboxes=V1Preview opt-in header is required while the
// toolbox MCP surface is in preview.
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new HttpClientTransportOptions
        {
            Endpoint = new Uri(toolboxMcpServerUrl),
            Name = toolboxName,
            TransportMode = HttpTransportMode.StreamableHttp,
        },
        httpClient));

// AgentSkillsProvider implements progressive disclosure over the MCP-discovered skills:
// names and descriptions are advertised in the system prompt, and the full skill body
// (and any supplementary resources) is loaded on demand when the model decides it is
// relevant.
var skillsProvider = new AgentSkillsProviderBuilder()
    .UseMcpSkills(mcpClient)
    .Build();

AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "foundry-toolbox-mcp-skills",
        Description = "Agent that discovers MCP-based skills from a Foundry Toolbox and exposes them via AgentSkillsProvider.",
        ChatOptions = new ChatOptions
        {
            ModelId = deployment,
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

// HttpClientHandler that attaches a fresh Foundry bearer token to every outgoing request.
internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : HttpClientHandler
{
    private readonly TokenRequestContext _tokenContext = new([scope]);

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}

For the complete sample, including project files and deployment steps, see the Skills in Toolbox sample.