Crie e gere uma caixa de ferramentas no Foundry

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

# 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_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchToolboxTool(),
        MCPToolboxTool(
            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();

WebSearchToolboxTool webTool = new();
MCPToolboxTool mcpTool = new(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.CreateVersionAsync(
  name: "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}`);

Utilize a extensão Microsoft Foundry Toolkit para Visual Studio Code para criar e publicar uma caixa de ferramentas na vista Tools.

1. Selecione Foundry Toolkit na barra de atividades.
2. Na secção Meus Recursos, expanda o nome> do seuprojeto Ferramentas.
3. Selecione o ícone + Adicionar Caixa de Ferramentas .
4. No separador Criar uma caixa de ferramentas personalizada, introduza o nome e a descrição da caixa de ferramentas e adicione as ferramentas que pretende.
5. Para ativar o direcionamento de ferramentas com base na intenção, selecione Pesquisa de ferramentas.
6. Selecione Publicar.

Publicar uma nova caixa de ferramentas cria a sua primeira versão. Essa versão torna-se automaticamente a versão padrão.

Com o bundle de extensões unificado microsoft.foundry (ver Pré-requisitos), crie uma caixa de ferramentas em dois passos:

1. Use azd ai connection create para registar cada ligação ao projeto referenciada pela toolbox (uma chamada por registo de credencial).
2. Use azd ai toolbox create --from-file <toolbox.yaml> para criar a caixa de ferramentas. O YAML refere ligações pelo nome e nunca incorpora credenciais.

O padrão é o mesmo para todos os tipos de ligação e tipos de autenticação:

1. Defina o projeto ativo uma vez por shell:

   azd ai project set $PROJECT_ENDPOINT
   

2. Crie uma ligação com azd ai connection create. As bandeiras diferem consoante o tipo de autenticação, mas a forma de comando é sempre:

   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 e azd ai connection show <name> para inspecionar ligações e azd ai connection delete <name> --force para as remover.

3. Crie um YAML toolbox que faça referência a uma ou mais ligações existentes pelo nome. O YAML nunca incorpora credenciais:

   # 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: web_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
   

   Pelo menos um dos connections, skills, ou tools deve estar não vazio. As referências de competências devem apontar para competências que já existem no mesmo projeto Foundry; ver Usar habilidades em Foundry para as criar com azd ai skill create. Para obter detalhes sobre a configuração de ponta a ponta da pesquisa de ferramentas, consulte Utilizar a pesquisa de ferramentas.

4. Crie a caixa de ferramentas a partir desse ficheiro:

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

   A primeira versão torna-se automaticamente o padrão. Use azd ai toolbox list, azd ai toolbox show <name>, azd ai toolbox version list <name>, e azd ai toolbox delete <name> --force para gerir caixas de ferramentas.

Exemplo: servidor MCP com autenticação baseada em chaves

# 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

Na extensão Microsoft Foundry Toolkit para Visual Studio Code, copie o ponto final do consumidor da caixa de ferramentas na vista Toolboxes.

1. Selecione Foundry Toolkit na barra de atividades.
2. Na secção Meus Recursos, expanda o nome> do seuprojeto Ferramentas.
3. No separador Caixas de Ferramentas , localiza a tua caixa de ferramentas.
4. Na coluna URL do Endpoint, copie o endpoint.

O valor Endpoint URL é o endpoint consumidor da toolbox. Para construir um endpoint específico de cada versão, utilize o padrão de desenvolvimento mostrado na tabela anterior.

Instalar o SDK do cliente MCP:

pip install mcp

Liga-te à caixa de ferramentas e lista ferramentas

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 o endpoint específico da versão (/versions/{version}/mcp) para validar uma versão antes de a promover.

1. Inicializar a sessão MCP:

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. Enviar a notificação inicializada:

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. Listar as ferramentas disponíveis:

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. Chamar uma ferramenta:

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":{}}}

Instalar o SDK do cliente MCP:

npm install @modelcontextprotocol/sdk

Liga-te à caixa de ferramentas e lista ferramentas

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();

Utilize o endpoint MCP da toolbox com um exemplo base de agente alojado para validar o carregamento da toolbox no VS Code.

1. No Foundry Toolkit, em Os Meus Recursos>O nome do seu projeto>Ferramentas, localize a caixa de ferramentas que pretende testar.
2. Selecione o modelo de código do andaime.
3. Escolha uma pasta de projeto quando solicitado.
4. Siga o gerado README.md para instalar dependências, configurar variáveis de ambiente e executar a amostra localmente.
5. Usa o Agent Inspector ou executa python main.py para confirmar que as ferramentas da consola carregam e respondem.

Para validação específica da versão antes de promover uma nova versão da toolbox, use o separador Python ou REST API neste passo.

LangGraph

Requisitos do fragmento de integração alojado: Instalar langchain-azure-ai[tools]>1.2.3. O fragmento utiliza AzureAIProjectToolbox; utiliza a amostra mantida do LangGraph para o agente completo, conjunto de pacotes e ficheiros de implementação.

.env ficheiro:

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 (padrão-chave):

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Estrutura do Microsoft Agent

Instale agent-framework-foundry além do pacote pré-requisito do Azure Identity. Para a implementação completa, consulte o exemplo mantido do Agent Framework.

Utilize FoundryToolbox do SDK do Agent Framework para ligar ao endpoint da toolbox. A classe trata da autenticação da caixa de ferramentas e encaminha o contexto da chamada do agente hospedado.

.env ficheiro:

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 (padrão-chave):

from agent_framework.foundry import FoundryToolbox
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# 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"

toolbox = FoundryToolbox(
    credential,
    url=TOOLBOX_ENDPOINT,
)

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

Copilot SDK

Requisitos do fragmento de integração hospedado: Instalar o SDK do GitHub Copilot para o seu ambiente de execução. O esquema depende dos auxiliares da aplicação McpBridge e _get_toolbox_token que não estão implementados aqui. Siga os padrões existentes de endpoint da caixa de ferramentas, contrato de autenticação e integração de agente hospedado. Ainda não está disponível uma amostra completa mantida.

Use o GitHub Copilot SDK para construir um agente alimentado por toolbox que liga a invocação de ferramentas do Copilot ao endpoint MCP da Foundry toolbox.

.env ficheiro:

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 (padrão de chave — ponte MCP):

# 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"],
)

Estrutura do Microsoft Agent

Instalar Microsoft.Agents.AI.Foundry.Hosting e Azure.Identity. Para um projeto completo, consulte o exemplo público de caixa de ferramentas hospedada do Agent Framework.

Utilize AddFoundryToolboxes para registar uma ou mais caixas de ferramentas junto do agente alojado. A integração resolve o endpoint MCP gerido, autentica pedidos e inclui a saúde da caixa de ferramentas na sonda de prontidão.

Variáveis de ambiente:

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

Program.cs (padrão-chave):

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable(
    "AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME is not set.");

var credential = new DefaultAzureCredential();
AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with access to toolbox tools.",
        name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxName);

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

Utilize a extensão Microsoft Foundry Toolkit para o Visual Studio Code para criar a estrutura de um exemplo de agente alojado já configurado para a sua caixa de ferramentas.

1. Selecione Foundry Toolkit na barra de atividades.
2. Na secção Meus Recursos, expanda o nome> do seuprojeto Ferramentas.
3. No separador Caixas de Ferramentas , localize a caixa de ferramentas que pretende consumir e depois selecione modelo de código de andaime.
4. Na Paleta de Comandos, escolha uma pasta de projeto quando solicitado.
5. Abra o ficheiro gerado README.md e siga os passos de configuração, execução local e implementação da estrutura inicial.

O projeto gerado inclui o ponto de entrada do agente Hosted, ficheiros de implantação e um README.md com os passos exatos de configuração, execução e implantação.

Se quiser integrar uma toolbox num projeto de agente hospedado existente em vez de gerar uma nova amostra, use o endpoint MCP da toolbox com os padrões Python ou .NET desta secção.

Passa o endpoint da caixa de ferramentas ao teu agente

Depois de criares a toolbox, recupera o endpoint MCP dele usando azd ai toolbox show e passa esse endpoint ao código do teu agente como variável de ambiente. O agente lê a variável no arranque e usa-a para se ligar à caixa de ferramentas.

1. Obtenha o endpoint da caixa de ferramentas:

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

   O endpoint campo na resposta identifica a versão selecionada. Usa-o para testar essa versão antes da promoção. Para um agente que deve seguir default_version, constrói o endpoint do consumidor não versionado mostrado em Get the toolbox MCP endpoint.

2. Defina o endpoint como uma variável de ambiente que o seu agente lê no arranque:

   # .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. No código do teu agente, lê TOOLBOX_ENDPOINT e liga-te a ele com um cliente MCP. Utilize os padrões de integração do Python ou do .NET apresentados anteriormente nesta secção como referência para a configuração do cliente e para o token Entra (âmbito https://ai.azure.com/.default).

from azure.ai.projects.models import MCPToolboxTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    tools=[
        MCPToolboxTool(
            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"
    }
  ]
}

MCPToolboxTool mcpTool = new(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 o separador Python, .NET, JavaScript, API REST ou Azure Developer CLI para configurar require_approval na definição da sua caixa de ferramentas. O fluxo de trabalho da extensão Microsoft Foundry Toolkit for Visual Studio Code neste artigo foca-se na criação e consumo da caixa de ferramentas no 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_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "<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 o separador Python, .NET, JavaScript ou API REST para criar uma nova versão da caixa de ferramentas. O fluxo de trabalho da extensão Microsoft Foundry Toolkit for Visual Studio Code neste artigo foca-se na criação de uma caixa de ferramentas e na estruturação de um agente alojado que a consome.

Esta operação não é suportada pela CLI do Azure Developer. Para criar uma versão da caixa de ferramentas, use o separador Python, .NET, REST ou JavaScript.

# 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 o separador Python, .NET, JavaScript ou API REST para listar versões da toolbox.

# 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 o separador Python, .NET, JavaScript ou API REST para obter uma versão específica da caixa de ferramentas.

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 Não pode estar vazio. Substitua-o por uma nova versão.

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

Utilize o separador Python, .NET, JavaScript ou REST API para promover uma versão da caixa de ferramentas para predefinição.

As versões da caixa de ferramentas são imutáveis. Usar publish para tornar qualquer versão existente como o novo padrão:

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

publish é o único caminho que muda default_version da CLI; verbos mutantes (connection add/remove, skill add/remove) criam sempre uma nova versão sem a promover.

# 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 o separador Python, .NET, JavaScript ou REST API para eliminar uma versão da toolbox.

Esta operação não é suportada pela CLI do Azure Developer. Para eliminar uma versão de toolbox, use o separador Python, .NET, REST API, ou JavaScript.

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

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

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchToolboxTool()],
    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.CreateVersion(
  name: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchToolboxTool()],
    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.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

A configuração do corrimão de proteção ainda não está disponível na extensão VS Code. Use a REST API, SDK ou Azure Developer CLI para configurar 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"
    }
  ]
}

Para fixar uma versão específica:

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

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="1"),  # pin to version 1
    ],
)
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 = "1" }

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

const toolboxVersion = await project.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}`);

A CLI do Azure Developer suporta referências a competências em dois locais: declarativamente, como um bloco de nível superior skills: no YAML azd ai toolbox create --from-file, e imperativamente, com os verbos azd ai toolbox skill add/list/remove. Cada referência tem uma name (obrigatória) e uma opcional version (string). Omitir version seguir a habilidade default_version; fixar uma string de versão para bloquear a caixa de ferramentas a um instantâneo imutável.

Declara as competências quando criares a caixa de ferramentas

# 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

Adicione, liste e remova competências numa caixa de ferramentas existente

# 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 mostra apenas a versão padrão. As habilidades fixadas mostram a sua versão; As habilidades não fixadas mostram (default). Para inspecionar as competências de uma versão pendente, execute azd ai toolbox show <toolbox> --version <n> --output json e leia a matriz skills.

Os nomes das habilidades devem coincidir ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (letras minúsculas, dígitos e hífens; máximo 64 caracteres; sem hífen inicial ou final). Um @ final em <name>@<version> (uma versão vazia) é rejeitado.

As referências de competências não são atualmente configuráveis através da extensão VS Code. Use a API REST ou SDK para configurar as competências.

Validar a descoberta de competências

Depois de associar competências a uma versão da toolbox, verifique que consegue descobri-las através do endpoint MCP da toolbox, utilizando o SDK MCP para Python:

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

As competências aparecem como recursos MCP com URIs no formato skill://{name}.

Consumir competências de um agente (Microsoft Agent Framework, .NET)

No .NET, utilize AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) do SDK do Microsoft Agent Framework para descobrir capacidades baseadas em MCP a partir de um endpoint de toolbox e injetá-las como AIContextProviders no agente. O agente carrega então as instruções de cada competência em tempo de execução quando o modelo decide que são relevantes. O Program.cs seguinte aloja o agente com a camada de alojamento de Respostas (AddFoundryResponses e 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.
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);
    }
}

Para o exemplo completo, incluindo ficheiros de projeto e passos de implementação, consulte o exemplo Skills in Toolbox.