Criar e gerenciar uma caixa de ferramentas na Foundry

Warning

Ao se conectar a ferramentas não Foundry, você pode incorrer em custos e os dados podem ser enviados fora do limite de conformidade do Foundry e processados de acordo com os termos e as políticas de tratamento de dados aplicáveis. Consulte a documentação da ferramenta para saber como gerenciar o acesso à ferramenta.

Este artigo mostra como criar uma caixa de ferramentas, adicionar e configurar ferramentas, verificar se elas são carregadas, integrar a caixa de ferramentas a um agente hospedado e gerenciar versões da caixa de ferramentas. Para obter uma introdução conceitual às caixas de ferramentas, consulte o que é a Caixa de Ferramentas na Foundry?. Para obter as opções de sintaxe e autenticação de configuração de ferramentas para cada tipo de ferramenta, consulte Configurar ferramentas.

Pré-requisitos

  • Um projeto ativo Microsoft Foundry.

  • RBAC: atribua a função Foundry User no projeto do Foundry a cada identidade aplicável ao seu cenário:

    • Desenvolvedor (sempre necessário) – a identidade que cria, atualiza e gerencia versões da caixa de ferramentas.
    • Identidade do agente (necessária se estiver usando um agente de prompt) – a identidade gerenciada do agente que chama ferramentas em runtime.
    • Usuário final (obrigatório apenas para fluxos OAuth) — qualquer usuário cuja identidade é encaminhada por proxy por meio de conexões OAuth ou UserEntraToken (por exemplo, fluxos MCP baseados em OAuth ou fluxos de token Entra do usuário (passagem de identidade do usuário gerenciado)).

    Para obter instruções passo a passo para atribuir a função De usuário do Foundry a uma identidade de agente, consulte Atribuir permissões à identidade do agente.

  • Seu projeto Foundry precisa estar em uma das regiões com suporte. Tipos de ferramentas individuais em uma caixa de ferramentas são limitados ainda mais por região e modelo– nem todos os tipos de ferramentas estão disponíveis em todas as regiões ou em cada modelo. Consulte a compatibilidade de região e modelo.

  • Visual Studio Code (VS Code).

  • Instale a extensão Microsoft Foundry Toolkit for Visual Studio Code no Marketplace do Visual Studio Code.

  • Python SDK:pip install azure-ai-projects azure-identity

  • .NET SDK: instale o conjunto de pacotes de visualização coerente e Azure Identidade:

    dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.AI.Projects.Agents --version 2.1.0-beta.4
dotnet add package Azure.AI.Extensions.OpenAI --version 2.1.0-beta.4
dotnet add package Azure.Identity

  • SDK do JavaScript: npm install @azure/ai-projects @azure/identity

  • CLI do Desenvolvedor do Azure: Instale a CLI do Desenvolvedor do Azure (azd, 1.25 ou versão posterior) e o pacote unificado de extensões da CLI do Foundry:

    # Install the unified bundle (provides azd ai agent, connection, inspector,
# project, routine, skill, and toolbox).
azd ext install microsoft.foundry

Importante

  • Uma caixa de ferramentas dá suporte no máximo a uma ferramenta sem um name campo (Pesquisa na Web, Pesquisa de IA do Azure , Interpretador de Código, Pesquisa de Arquivos). Para incluir mais de uma instância do mesmo tipo de ferramenta, defina uma única name em cada instância para diferenciá-las. Incluir duas instâncias do mesmo tipo sem um `name` resulta em um erro `invalid_payload`. Para obter detalhes, consulte Vários tipos de ferramentas.
  • Adicione uma description a cada ferramenta em sua caixa de ferramentas para ajudar o modelo a selecionar a ferramenta certa para cada solicitação.
  • Examine cuidadosamente a documentação de cada ferramenta para saber mais sobre configuração de ferramentas individuais, limitações e avisos.

Se você estiver usando o GitHub Copilot para Azure para gerar a estrutura de um agente hospedado que consome o conjunto de ferramentas, as referências de habilidades a seguir descrevem o mesmo contrato de endpoint (variável de ambiente, cabeçalhos, protocolo MCP, padrões de citação e solução de problemas) que o agente deve implementar:

  • Referência do Toolbox para orientações sobre formato de endpoint, protocolo MCP, gerenciamento do consentimento OAuth, padrões de citação e solução de problemas.
  • Use a caixa de ferramentas em um agente hospedado para encontrar orientações sobre resolução de endpoints, contrato de variáveis de ambiente, estrutura do payload, padrões de integração de código e rastreamento.

Caminho rápido

  1. Criar:Crie uma versão da caixa de ferramentas com uma ou mais ferramentas. Mantenha cada snippet focado em uma tarefa e dentro de 30 linhas; use os exemplos mantidos vinculados para aplicativos completos.
  2. Publicar ou selecionar uma versão: A primeira versão se torna o padrão automaticamente. Para versões posteriores, teste e promova uma versão quando estiver pronto para torná-la o padrão.
  3. Conecte e use: Copie o endpoint do consumidor da caixa de ferramentas e, em seguida, integre-o ao seu agente.
  4. Verifique: Use o ponto de extremidade específico da versão para listar as ferramentas disponíveis e, em seguida, executar uma solicitação de agente que chama uma ferramenta esperada.

Suporte a funcionalidades

SDKs e ferramentas dão suporte a operações de gerenciamento de caixa de ferramentas, conforme mostrado na tabela a seguir.

Operação SDK do Python API REST SDK .NET SDK para JavaScript Azure Developer CLI Kit de Ferramentas Foundry
Atualizar, listar, obter e excluir ferramentas da caixa de ferramentas ✔️ ✔️ ✔️ ✔️ N/A ✔️
Criar versão da caixa de ferramentas ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Lista de versões da caixa de ferramentas, obter e excluir ✔️ ✔️ ✔️ ✔️ N/A Não. A interface do usuário mostra apenas a versão mais recente.
Barreira de proteção (política RAI) ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Você também pode gerenciar caixas de ferramentas conversando com o Servidor MCP do Foundry. Consulte Gerenciar caixas de ferramentas com o Servidor MCP do Foundry.

Você pode adicionar as ferramentas a seguir a uma caixa de ferramentas. Esta tabela mostra o SDK e o suporte a ferramentas para cada ferramenta e se a ferramenta também pode ser anexada diretamente a um agente (fora de uma caixa de ferramentas). Para ver como ocorre o tráfego de cada ferramenta quando seu projeto usa isolamento de rede, consulte Isolamento de rede para um conjunto de ferramentas.

Tool Em uma caixa de ferramentas Integração de ferramentas diretas SDK do Python API REST SDK .NET SDK para JavaScript Azure Developer CLI Kit de Ferramentas Foundry
MCP (Protocolo de Contexto do Modelo) ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Pesquisa na Web ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Pesquisa de IA do Azure  ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Interpretador de código ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Pesquisa de arquivo ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Openapi ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ Não
Agente a agente (A2A) ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ Não
Automação do navegador ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ Não
Fabric IQ ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Qi de trabalho ✅ Sim ✅ Sim ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Pesquisa de ferramentas ✅ Sim ❌ Não ✔️ ✔️ ✔️ ✔️ ✔️ ✔️
Habilidades ✅ Sim ❌ Não ✔️ ✔️ ✔️ ✔️ ✔️ Não

A disponibilidade da ferramenta também depende da região e do modelo do projeto. Antes de implantar uma caixa de ferramentas, verifique se a região de destino dá suporte aos tipos de ferramentas que você planeja usar. Consulte o suporte à Ferramenta por região e modelo.

Criar uma versão da caixa de ferramentas

Crie uma versão da caixa de ferramentas com base nas ferramentas necessárias.

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"
    }
  ]
}

Nota

Use o escopo do token https://ai.azure.com/.default ao obter o token de portador.

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 a extensão Microsoft Foundry Toolkit for Visual Studio Code para criar e publicar uma caixa de ferramentas na exibição Tools.

  1. Selecione o Foundry Toolkit na Barra de Atividades.
  2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
  3. Selecione o ícone + Adicionar Caixa de Ferramentas .
  4. Na guia Criar uma Caixa de Ferramentas Personalizada , insira o nome e a descrição da caixa de ferramentas e adicione as ferramentas desejadas.
  5. Para habilitar o roteamento de ferramentas baseado em intenção, selecione a pesquisa de ferramentas.
  6. Selecione Publicar.

A publicação de uma nova caixa de ferramentas cria sua primeira versão. Essa versão se torna a versão padrão automaticamente.

Captura de tela do Foundry Toolkit mostrando o nome da caixa de ferramentas, a descrição, as ferramentas e a ação Publicar.

Com o pacote de extensão unificado microsoft.foundry (consulte Pré-requisitos), crie uma caixa de ferramentas em duas etapas:

  1. Use azd ai connection create para registrar cada conexão do projeto que a caixa de ferramentas referencia (uma chamada por registro de credenciais).
  2. Use azd ai toolbox create --from-file <toolbox.yaml> para criar a caixa de ferramentas. O YAML faz referência a conexões por nome e nunca insere credenciais.

O padrão é o mesmo para cada tipo de conexão e tipo de autenticação:

  1. Defina o projeto ativo uma vez por shell:

    azd ai project set $PROJECT_ENDPOINT

  2. Criar uma conexão com azd ai connection create. Os sinalizadores diferem por 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> inspecione as conexões e azd ai connection delete <name> --force remova-as.

  3. Crie um arquivo YAML de caixa de ferramentas que faça referência a uma ou mais conexões existentes por nome. O YAML nunca insere 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 de connections, skillsou tools deve ser não vazio. As referências de habilidade devem apontar para habilidades que já existem no mesmo projeto do Foundry; consulte Usar habilidades no Foundry para criá-las com azd ai skill create. Para detalhes sobre a configuração completa da busca de ferramentas, consulte Usar a busca de ferramentas.

  4. Crie a caixa de ferramentas desse arquivo:

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

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

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

# 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

Obter o ponto de extremidade MCP da caixa de ferramentas

Existem dois padrões de endpoint dependendo da sua função:

Papel Ponto de extremidade Quando usar
Desenvolvedor da caixa de ferramentas {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1 Teste ou valide uma versão específica antes de promovê-la para o padrão.
Usuário do Toolbox {project_endpoint}/toolboxes/{toolbox_name}/mcp?api-version=v1 Conecte agentes à caixa de ferramentas. Sempre atende à default_version. A primeira versão criada é definida automaticamente como o padrão.

Substitua os espaços reservados por seus próprios valores:

  • {project_endpoint} é o endpoint do seu projeto do Foundry, no formato https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>. Copie-o da página Visão geral do seu projeto no portal do Foundry ou da coluna URL do ponto de extremidade na exibição Caixas de ferramentas do Microsoft Foundry Toolkit for Visual Studio Code.
  • {toolbox_name} e {version} são o nome da caixa de ferramentas e a versão que você criou em Criar uma versão da caixa de ferramentas.

Dica

Conecte os agentes ao ponto de extremidade do consumidor da caixa de ferramentas ponto de extremidade. Ele sempre fornece o default_version, para que você possa promover novas versões sem alterar o código do agente nem reimplantá-lo. Reserve o endpoint toolbox developer (específico da versão) para testar uma versão antes de promovê-la.

Nota

A primeira versão de uma nova caixa de ferramentas é promovida automaticamente para default_version (v1). Se você precisar alterar o padrão posteriormente, consulte Promover uma versão para padrão.

Na extensão Microsoft Foundry Toolkit for Visual Studio Code, copie o ponto de extremidade de consumidor da caixa de ferramentas da exibição Caixas de ferramentas.

  1. Selecione o Foundry Toolkit na Barra de Atividades.
  2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
  3. Na guia Caixas de Ferramentas , localize sua caixa de ferramentas.
  4. Na coluna URL do Ponto de extremidade, copie o ponto de extremidade .

O valor de URL do Ponto de extremidade é o ponto de extremidade do consumidor da caixa de ferramentas. Para construir um endpoint específico para uma versão, use o padrão do desenvolvedor mostrado na tabela anterior.

Verificar a disponibilidade da ferramenta

Antes de executar o agente completo, confirme se a caixa de ferramentas carrega as ferramentas esperadas usando um SDK de cliente MCP no ponto de extremidade . Use o ponto de extremidade específico da versão para validar uma versão antes de promovê-la para padrão.

Instale o SDK do cliente MCP:

pip install mcp

Conectar à caixa de ferramentas e listar 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())

Nota

Use a guia API REST para verificar a disponibilidade da ferramenta no .NET, ou use o SDK do cliente MCP em Python.

Utilize o endpoint específico da versão (/versions/{version}/mcp) para validar uma versão antes de promovê-la.

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

Instale o SDK do cliente MCP:

npm install @modelcontextprotocol/sdk

Conectar à caixa de ferramentas e listar 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();

Use o endpoint MCP da toolbox com um exemplo de agente hospedado com scaffolding para validar o carregamento da toolbox no VS Code.

  1. No Foundry Toolkit, em Meus Recursos>Seu nome de projeto>Ferramentas, localize a caixa de ferramentas que você deseja testar.
  2. Selecione o modelo de código Scaffold.
  3. Escolha uma pasta de projeto quando solicitado.
  4. Siga as dependências README.md geradas, para instalar, configurar variáveis de ambiente e executar o exemplo localmente.
  5. Use o Inspetor do Agente ou execute python main.py para confirmar se as ferramentas da caixa de ferramentas carregam e respondem.

Para a validação de versão específica antes de promover uma nova versão da toolbox, use a aba Python ou API REST nesta etapa.

Nota

Use a guia API REST para verificar a disponibilidade da ferramenta ou use o SDK do cliente MCP Python.

Verificar – inicializar: HTTP 200. Se você ignorar a etapa de inicialização, as chamadas subsequentes falharão.

Verificação — tools/list:

  • len(tools) > 0 — vazio significa que a versão da caixa de ferramentas não foi provisionada corretamente.

  • Cada ferramenta tem name, descriptione inputSchema. Para convenções de nomenclatura de ferramentas, consulte a especificação do MCP.

  • inputSchema tem um campo properties (alguns servidores MCP omitem esse campo, o que interrompe o OpenAI).

  • Os nomes de ferramentas são espaçados por tipo de ferramenta:

    Tipo de ferramenta Formato de nome da ferramenta Example
    MCP {server_label}.{tool_name} myserver.some_tool
    OpenAPI {openapi_name}.{operationId} weatherapi.getForecast
    A2A O name (nome do agente) da ferramenta ou o nome da conexão quando name não for informado. myagent
    Todos os outros tipos de ferramentas O name valor do campo ou o nome da ferramenta padrão web_search

  • As ferramentas MCP incluem um _meta.tool_configuration bloco que contém configurações de runtime, como require_approval. Consulte Exigir aprovação da ferramenta.

  • Observe os nomes de parâmetro exatos para a etapa de chamada (por exemplo query vs queries).

Verificar - tools/call:

  • Nenhum campo de nível error superior. Se estiver presente, inspecione error.code. Para obter códigos de erro MCP padrão, consulte a especificação do MCP:
    • -32006 → É necessário consentimento OAuth (extraia a URL de error.message).
    • Outros códigos → falha no lado do servidor.
  • result.content[] contém entradas com "type": "text" - esta é a saída da ferramenta.
  • Para a Pesquisa de IA, verifique result.structuredContent.documents[] para metadados de partes (title, url, id, score).
  • Para pesquisa de arquivos, verifique result.content[].resource._meta para metadados de partes (title, file_id, document_chunk_id, score).
  • Para Pesquisa na Web, verifique result.content[].resource._meta.annotations[] se há citações de URL (type, , url, title, start_index, end_index).
  • Para Fabric IQ, consulte result.structuredContent.documents[] para ver trechos de citação. Cada documento inclui os campos title e url, que remetem ao item do Fabric (Ontologia, agente de dados ou modelo semântico do Power BI) usado para fundamentar a resposta.
  • "ServerError" Fique atento ao conteúdo do texto – a ferramenta foi executada, mas encontrou um erro interno.

Exemplos de argumentos específicos da ferramenta tools/call

Tipo de ferramenta Argumentos
Pesquisa de IA {"query": "search text"}
Pesquisa de Arquivo {"queries": ["search text"]} — ou {"queries": ["search text"], "vector_store_ids": ["<VECTOR_STORE_ID>"]} quando o repositório de vetores é passado dinamicamente
Interpretador de Código {"code": "print(2 ** 100)"}
Pesquisa na Web {"search_query": "weather in seattle"}
A2A {"message": {"parts": [{"type": "text", "text": "Hello"}]}}
Inteligência de Tecidos Varia de acordo com a ferramenta exposta — normalmente {"query": "..."} para ferramentas de consulta
QI de trabalho {"message": {"parts": [{"type": "text", "text": "Hello"}]}}
MCP {"query": "what is agent service"}

Integrar a caixa de ferramentas ao seu agente

LangGraph

Requisitos do fragmento de integração hospedado: Instale langchain-azure-ai[tools]>1.2.3. Este fragmento usa AzureAIProjectToolbox; use o exemplo mantido do LangGraph para o agente completo, o conjunto de pacotes e os arquivos de implantação.

.env arquivo:

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 de chave):

from langchain_azure_ai.tools import AzureAIProjectToolbox

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

Importante

A classe langchain_azure_ai.tools.AzureAIProjectToolbox requer langchain-azure-ai[tools]>1.2.3.

Estrutura do agente do Microsoft

Requisitos do fragmento de integração hospedado: Instale agent-framework-foundry e httpx além do pacote de pré-requisito Azure Identity. O fragmento depende de um _ToolboxAuth componente auxiliar e da configuração do cliente e do host ao redor dele. Use o exemplo atualizado do Agent Framework, que fornece o conjunto completo de pacotes e o encapsulamento de autenticação do kit de ferramentas.

Use o MCPStreamableHTTPTool do SDK do Agent Framework para se conectar diretamente ao ponto de extremidade do MCP da caixa de ferramentas.

.env arquivo:

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 de chave):

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

SDK do Copilot

Requisitos para fragmento de integração hospedada: Instale o SDK do GitHub Copilot para seu ambiente de execução. O esquema depende de McpBridge e _get_toolbox_token auxiliares pertencentes ao aplicativo que não são implementados aqui. Siga o endpoint e o contrato de autenticação existentes do toolbox e os padrões de integração de agente hospedado. Uma amostra completa mantida ainda não está disponível.

Use o SDK do GitHub Copilot para criar um agente com suporte à caixa de ferramentas que conecta a invocação de ferramentas do Copilot ao ponto de extremidade do MCP da caixa de ferramentas do Foundry.

Nota

O SDK do Copilot rejeita nomes de ferramentas que contêm pontos. A ponte substitui automaticamente . por _ em nomes de ferramentas. Por exemplo, myserver.get_info torna-se myserver_get_info.

.env arquivo:

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 agente do Microsoft

Requisitos do fragmento de integração hospedado: Este fragmento usa tipos dos pacotes Azure.AI.AgentServer.Responses, Azure.AI.OpenAI, Azure.Identity, Microsoft.Extensions.DependencyInjection e OpenAI. ToolboxMcpClient, ToolboxHandlere AgentConfig são auxiliares personalizados que não estão definidos aqui. Para uma integração mantida com as referências do pacote e a configuração completa do host, use o exemplo de caixa de ferramentas hospedada do Agent Framework público.

Use ResponsesServer do SDK do Agent Framework com um ToolboxMcpClient personalizado para descobrir e invocar ferramentas da caixa de ferramentas através do ponto de extremidade do MCP.

Variáveis de ambiente:

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

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 encapsula chamadas JSON-RPC diretas para o ponto de extremidade do MCP. ToolboxHandler conecta as chamadas da ferramenta LLM de volta ao cliente MCP usando um loop de chamada de ferramenta padrão.

Nota

Os exemplos de integração para esta etapa estão disponíveis apenas para Python e .NET.

Nota

Os exemplos de integração para esta etapa estão disponíveis apenas para Python e .NET.

Use a extensão do Microsoft Foundry Toolkit for Visual Studio Code para fazer o scaffolding da amostra do agente hospedado já conectado à caixa de ferramentas.

  1. Selecione o Foundry Toolkit na Barra de Atividades.
  2. Em Meus Recursos, expanda o nome do projeto>Ferramentas.
  3. Na guia Caixa de ferramentas, localize a caixa de ferramentas que deseja consumir e selecione Modelo de código de scaffold.
  4. Na Paleta de Comandos, escolha uma pasta de projeto quando solicitado.
  5. Abra o arquivo gerado README.md e siga as etapas de instalação, execução em ambiente local e implantação do scaffold.

O projeto gerado inclui o ponto de entrada do agente hospedado, os arquivos de implantação e um README.md com as etapas exatas de configuração, execução e implantação.

Se você quiser integrar uma caixa de ferramentas a um projeto de agente hospedado existente em vez de gerar um novo exemplo, use o ponto de extremidade MCP da caixa de ferramentas com os padrões Python ou .NET nesta seção.

Passar o ponto de extremidade da caixa de ferramentas para seu agente

Depois de criar a caixa de ferramentas, recupere seu ponto de extremidade MCP usando azd ai toolbox show e passe esse ponto de extremidade para o código do agente como uma variável de ambiente. O agente lê a variável na inicialização e a usa para se conectar à caixa de ferramentas.

  1. Obtenha o ponto de extremidade da caixa de ferramentas:

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

    O endpoint campo na resposta identifica a versão selecionada. Use-a para testar essa versão antes da promoção. Para um agente que deve seguir default_version, construa o ponto de extremidade de consumidor não inverso mostrado em Obter o ponto de extremidade MCP da caixa de ferramentas.

  2. Defina o ponto de extremidade como uma variável de ambiente que seu agente lê na inicialização:

    # .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 agente, leia TOOLBOX_ENDPOINT e conecte-se a ele com um cliente MCP. Use os padrões de integração do Python ou do .NET mencionados anteriormente nesta seção como referência para a configuração do cliente e o token do Entra (escopo https://ai.azure.com/.default).

Gerenciar os requisitos de aprovação da ferramenta

A caixa de ferramentas retorna um _meta.tool_configuration objeto em cada entrada de ferramenta retornada por tools/list. Quando uma ferramenta tem require_approval definido como "always", o runtime do agente deve apresentar a ação pendente ao usuário e aguardar a confirmação antes de invocar a ferramenta. O endpoint MCP não bloqueia tools/call. A aplicação é inteiramente de responsabilidade do ambiente de runtime.

Depois que a caixa de ferramentas for criada e testada, conecte-a a um agente. O padrão de integração depende do tipo de agente:

  • Agente hospedado (seu próprio código em execução no Foundry Agent Service): consulte Usar um kit de ferramentas com um agente hospedado para ver os padrões de integração e os requisitos de aprovação em tempo de execução do Agent Framework, LangGraph, Visual Studio Code e Azure Developer CLI.

Configurar require_approval em uma ferramenta

Defina require_approval quando você cria uma versão da caixa de ferramentas. Os exemplos da ferramenta MCP em Criar uma versão da caixa de ferramentas mostram os valores "always" e "never". Para defini-lo por meio do SDK:

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 a guia Python, .NET, JavaScript, API REST ou CLI do Desenvolvedor do Azure para configurar require_approval na definição da sua caixa de ferramentas. Neste artigo, o fluxo de trabalho da extensão Microsoft Foundry Toolkit for Visual Studio Code se concentra em criar e usar a 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

Gerenciar versões da caixa de ferramentas

Nota

Você só pode excluir versões da caixa de ferramentas por meio do SDK do Python, do SDK .NET, do SDK do JavaScript e da API REST. A Azure Developer CLI oferece suporte às operações de listar, obter e publicar (promoção da versão padrão).

As versões de caixas de ferramentas são instantâneos imutáveis da configuração das ferramentas de uma caixa de ferramentas. Cada chamada ao ponto de extremidade de criação gera um novo ToolboxVersionObject. O ToolboxObject pai tem um campo default_version que controla qual versão o ponto de extremidade do MCP atende. A criação de uma nova versão não a promove automaticamente – você decide quando atualizar default_version. Esse processo permite que você configure alterações, teste uma nova versão de forma independente e promova-a para produção em sua própria agenda.

Nota

Para a Azure Developer CLI, cada operação de mutação direcionada à versão padrão atual – azd ai toolbox connection add/remove e azd ai toolbox skill add/remove – cria uma versão da caixa de ferramentas nova que encaminha todas as conexões e habilidades previamente anexadas com a alteração solicitada aplicada. Nenhum desses comandos altera default_version automaticamente; execute azd ai toolbox publish <toolbox-name> <version> quando quiser ativar a nova versão. Para inspecionar uma versão pendente (não padrão), use azd ai toolbox show <name> --version <n>.

Objeto Campos de chave Descrição
ToolboxObject id name, default_version O contêiner da caixa de ferramentas. default_version aponta para a versão ativa.
ToolboxVersionObject id, name, version, description, , created_at, tools[], policies Um instantâneo imutável da lista de ferramentas da caixa de ferramentas em um ponto no tempo. policies.rai_config.rai_policy_name especifica o guardrail opcional aplicado a esta versão.

Criar uma nova versão

Cada chamada de criação produz uma nova versão. Se a caixa de ferramentas ainda não existir, o processo a criará automaticamente. Quando você cria a primeira versão de uma nova caixa de ferramentas, a versão padrão é v1 até que você atualize manualmente para outra versão.

# 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 a guia Python, .NET, JavaScript ou API REST para criar uma nova versão da caixa de ferramentas. Neste artigo, o fluxo de trabalho da extensão Microsoft Foundry Toolkit para Visual Studio Code se concentra na criação de uma caixa de ferramentas e na geração da estrutura de um agente hospedado que consome essa caixa de ferramentas.

Essa operação não tem suporte com a CLI do desenvolvedor do Azure. Para criar uma versão da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

A resposta é um ToolboxVersionObject que contém o novo identificador version.

Listar versões

# 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 a guia Python, .NET, JavaScript ou API REST para listar versões da caixa de ferramentas.

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

Obter uma versão específica

# 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 a guia 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>

Promover uma versão para o padrão

O endpoint MCP sempre atende o default_version. Para alternar qual versão está ativa, atualize a caixa de ferramentas:

# 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}`);

Use a guia Python, .NET, JavaScript ou API REST para promover uma versão da caixa de ferramentas como padrão.

As versões da caixa de ferramentas são imutáveis. Use publish para tornar qualquer versão existente 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 de mutação (connection add/remove, skill add/remove) sempre criam uma nova versão sem promovê-la.

Excluir uma versão

# 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 a aba Python, .NET, JavaScript ou REST API para excluir uma versão da caixa de ferramentas.

Essa operação não tem suporte com a CLI do desenvolvedor do Azure. Para excluir uma versão da caixa de ferramentas, use a guia Python, .NET, REST API ou JavaScript.

Gerenciar caixas de ferramentas com o Servidor MCP do Foundry

O Servidor MCP do Foundry (versão prévia) expõe o gerenciamento de caixas de ferramentas como ferramentas MCP, para que você possa recuperar, versão, atualizar e excluir caixas de ferramentas de um cliente MCP, como GitHub Copilot em Visual Studio Code. Para configurar o servidor, consulte Introdução ao Servidor MCP do Foundry (versão prévia).

Tool Access Descrição
toolbox_get leitura Recupera um kit de ferramentas e sua versão padrão atual.
toolbox_version_get leitura Listar versões da caixa de ferramentas ou recuperar uma versão específica.
toolbox_version_create gravação Crie uma versão da caixa de ferramentas imutável. Se a caixa de ferramentas não existir, essa ferramenta também a criará.
toolbox_update gravação Crie ou atualize uma caixa de ferramentas, incluindo sua versão padrão.
toolbox_delete gravação Excluir uma caixa de ferramentas.
toolbox_version_delete gravação Exclua uma versão específica da caixa de ferramentas.

As mesmas regras de controle de versão se aplicam como com os SDKs. A criação de uma versão para uma caixa de ferramentas existente não altera a versão padrão. Para promover uma versão, chame toolbox_update com defaultVersion definido como a nova versão. Antes de excluir a versão padrão atual, defina outra versão como o padrão.

Prompts de exemplo:

  • "Mostre-me a customer-support-tools caixa de ferramentas."
  • Baixe a versão 2 de customer-support-tools.
  • "Criar uma nova versão de customer-support-tools."
  • "Defina a versão 2 customer-support-tools como padrão."
  • "Defina a versão 1 customer-support-tools como o padrão e exclua a versão 2."
  • "Excluir a old-support-tools caixa de ferramentas".

Para obter a referência completa da ferramenta, consulte as ferramentas disponíveis e os prompts de exemplo para o Servidor MCP do Foundry.

Configurar ferramentas

Escolha o tipo de ferramenta e o padrão de autenticação que correspondem ao seu cenário. Selecione a aba para seu SDK preferido ou método de implantação.

A aba azd de cada ferramenta abaixo mostra o YAML declarativo da caixa de ferramentas. Para criar uma caixa de ferramentas imperativamente sem um projeto de agente, use o azd ai toolbox create --from-file fluxo de trabalho e aplique os dados por ferramenta mostrados nas seções a seguir. Para implantar uma caixa de ferramentas com um agente hospedado, modele-a como um azure.ai.toolbox serviço azure.yaml e conecte o agente a ela com uses: ou toolboxes:.

Vários tipos de ferramentas

Uma única caixa de ferramentas pode agrupar diferentes tipos de ferramentas. O exemplo a seguir combina Pesquisa na Web, Pesquisa de IA do Azure  e um servidor MCP em uma caixa de ferramentas:

{
  "description": "Web search, knowledge base search, and custom MCP server",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "azure_ai_search",
      "name": "my_aisearch",
      "description": "Search internal product documentation",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    }
  ]
}

Nota

Cada tipo de ferramenta (web_search, azure_ai_search, code_interpreter, file_search) pode aparecer no máximo uma vez sem o campo name. Para incluir várias instâncias do mesmo tipo, defina uma única name em cada instância. Confira o próximo exemplo.

Restrições de várias ferramentas

Você pode incluir, no máximo, uma instância de cada tipo de ferramenta integrada sem um campo name em uma caixa de ferramentas. Se você incluir duas instâncias do mesmo tipo sem um name, a API retornará:

400 invalid_payload: Multiple tools without identifiers found...

Duas instâncias do mesmo tipo de ferramenta

Use o name campo para incluir várias instâncias do mesmo tipo de ferramenta em uma caixa de ferramentas. Cada instância nomeada é tratada como uma ferramenta separada e deve ter um nome exclusivo.

{
  "description": "Two Azure AI Search indexes in a single toolbox",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "product-search",
      "description": "Search product catalog and specifications",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<PRODUCT_INDEX_NAME>",
            "project_connection_id": "<PRODUCT_CONNECTION_NAME>"
          }
        ]
      }
    },
    {
      "type": "azure_ai_search",
      "name": "support-search",
      "description": "Search support tickets and troubleshooting guides",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<SUPPORT_INDEX_NAME>",
            "project_connection_id": "<SUPPORT_CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

Cada tipo de ferramenta tem sua própria configuração de caixa de ferramentas : tipos de autenticação de conexão, snippets de SDK por idioma e qualquer comportamento específico da caixa de ferramentas. Esses detalhes residem no artigo de referência de cada ferramenta. Consulte a tabela de suporte a recursos para obter um link para cada ferramenta.

Para comportamentos específicos de cada ferramenta — como o armazenamento vetorial dinâmico do File Search (sobrescrita de parâmetro) ou envios de arquivos no nível do recurso para o Code Interpreter e o File Search — consulte o artigo correspondente de cada ferramenta.

Configurar proteções

Aplique uma política de proteção nomeada a uma versão do conjunto de ferramentas para aplicar a filtragem responsável de conteúdo de IA nas entradas e saídas das ferramentas. O mecanismo de proteção opera na camada de ferramentas, independentemente de qualquer filtro de conteúdo em nível de modelo.

Faça referência a um guardrail pelo nome da política, que você configura no portal do Foundry em Guardrails. Defina policies.rai_config.rai_policy_name como o nome da política ao criar uma versão da caixa de ferramentas.

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 Guardrail ainda não está disponível na extensão do VS Code. Use a API REST, o SDK ou a CLI do Desenvolvedor Azure para configurar os guardrails.

Adicionar habilidades a uma caixa de ferramentas

Anexe habilidades a uma versão da caixa de ferramentas para disponibilizá-las aos agentes no ponto de extremidade MCP da caixa de ferramentas. Cada referência de habilidade especifica o nome da habilidade e uma versão opcional. Omita version para usar o default_version da habilidade; fixe uma cadeia de caracteres version para usar um instantâneo imutável.

Uma versão da caixa de ferramentas pode conter ferramentas, habilidades ou ambos. Os exemplos a seguir criam uma versão de caixa de ferramentas que contém uma única referência de habilidade. Para adicionar habilidades a uma caixa de ferramentas que já tem ferramentas, inclua a mesma tools que você usou em Criar uma versão da caixa de ferramentas, junto com o array skills.

Importante

As habilidades associadas a uma caixa de ferramentas devem existir no mesmo projeto Foundry. Não há suporte para referências entre projetos.

Quando um agente ou cliente MCP se conecta ao endpoint do toolbox, as habilidades ficam disponíveis como Recursos MCP. A estrutura de cliente ou agente do MCP deve dar suporte ao protocolo MCP Resources para descobrir e carregar habilidades automaticamente. Para verificar se as habilidades são localizáveis, chame resources/list no ponto de extremidade MCP do toolbox e confirme se os nomes das habilidades aparecem na resposta.

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 dá suporte a referências a habilidades em dois lugares: declarativamente, como um bloco skills: de nível superior no YAML azd ai toolbox create --from-file, e imperativamente com os verbos azd ai toolbox skill add/list/remove. Cada referência usa um name (obrigatório) e um opcional version (cadeia de caracteres). Omita version para seguir o default_version da habilidade; fixe uma cadeia de caracteres de versão para bloquear a caixa de ferramentas em um instantâneo imutável.

Declarar habilidades ao criar 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

Adicionar, listar e remover habilidades em uma 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 sua versão; as habilidades não fixadas mostram (default). Para inspecionar as habilidades de uma versão pendente, execute azd ai toolbox show <toolbox> --version <n> --output json e leia o array skills.

Importante

skill add e skill remove criam, cada um, uma nova versão da caixa de ferramentas que encaminha todas as conexões e habilidades vinculadas anteriormente, já com a alteração solicitada aplicada. Eles não promovem a nova versão como padrão, portanto, as alterações não são visíveis para clientes MCP até que você execute azd ai toolbox publish <toolbox> <version>. Para alterar a versão fixada de uma habilidade já anexada — por exemplo, atualizar greeting da v1 para a v2 — execute três comandos em ordem: skill remove, depois publish a nova versão e, em seguida, skill add <name>@<new-version> (skill add bloqueia duplicatas quando verificado em relação à versão padrão atual).

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

No momento, as referências de habilidade não são configuráveis por meio da extensão do VS Code. Use a API REST ou o SDK para configurar habilidades.

Validar a descoberta de habilidades

Depois de anexar habilidades a uma versão da caixa de ferramentas, verifique se é possível localizá-las por meio do endpoint MCP da caixa de ferramentas usando o SDK Python do MCP:

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 habilidades aparecem como recursos do MCP com URIs no formato skill://{name}.

Consumir habilidades de um agente (Microsoft Agent Framework, .NET)

No .NET, use AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) do SDK do Microsoft Agent Framework para descobrir habilidades baseadas em MCP de um ponto de extremidade de caixa de ferramentas e injetá-las como AIContextProviders no agente. Em seguida, o agente carrega as instruções de cada habilidade em tempo de execução quando o modelo decide que ela é relevante. O Program.cs a seguir hospeda o agente com a camada de hospedagem do Responses (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 obter o exemplo completo, incluindo arquivos de projeto e etapas de implantação, consulte o exemplo habilidades na caixa de ferramentas.

Lembrete

A ferramenta reminder_preview permite que um agente hospedado se agende para ser executado novamente em um momento futuro. Quando o agente chama essa ferramenta, ele especifica um atraso em minutos. Após esse atraso, o Foundry invoca novamente o mesmo agente na mesma conversa.

Solucionar problemas

Sintoma Causa provável Corrigir
tools/list retorna zero ferramentas para ferramentas do MCP ou do A2A Credenciais de conexão inválidas ou ausentes para o servidor MCP remoto ou agente A2A. A caixa de ferramentas não consegue recuperar os manifestos das ferramentas do ponto de extremidade remoto sem uma autenticação válida. Verifique se o project_connection_id existe em seu projeto do Foundry e se as credenciais estão corretas. Tente se conectar diretamente ao servidor MCP para testar a configuração de autenticação. Se estiver usando a identidade gerenciada (PMI, identidade do agente ou MI), verifique as atribuições de função RBAC corretas para o chamador no recurso de destino.
tools/list retorna zero ferramentas para ferramentas OpenAPI Especificação OpenAPI inválida. A caixa de ferramentas constrói o manifesto da ferramenta a partir da especificação, que falhará se a especificação estiver malformada. Valide o conteúdo de especificação do OpenAPI. Verifique se ele está em conformidade com o OpenAPI 3.0 ou 3.1 e inclui valores e esquemas de parâmetro válidospathsoperationId. Se estiver usando autenticação de identidade gerenciada, verifique também as atribuições de função RBAC no serviço de destino.
tools/list retorna menos ferramentas do que o esperado O allowed_tools filtro contém nomes de ferramentas incorretos ou mal escritos. Os nomes de ferramentas diferenciam maiúsculas de minúsculas e devem seguir a especificação do MCP para nomes de ferramentas (sem espaços em branco ou caracteres especiais). Remova allowed_tools temporariamente e chame tools/list para obter a lista de ferramentas completa. Use os nomes exatos da resposta para definir valores para allowed_tools.
tools/list retorna zero ferramentas (outros tipos de ferramentas) Kit de ferramentas não totalmente configurado ou tipo de ferramenta sem suporte na região. Para ferramentas internas (Pesquisa na Web, Pesquisa de IA, Interpretador de Código, Pesquisa de Arquivos), os manifestos da ferramenta são construídos no lado do servidor e não exigem autenticação – se retornarem vazios, a versão da caixa de ferramentas poderá ainda não ser provisionada. Aguarde 10 segundos e tente novamente.
400 Multiple tools without identifiers Dois tipos de ferramentas sem nome em uma caixa de ferramentas Manter no máximo um tipo sem nome; adicione server_label a todas as ferramentas do MCP.
CONSENT_REQUIRED (código -32006) A conexão OAuth requer o consentimento do usuário Abra a URL de consentimento em um navegador e conclua o fluxo OAuth e tente novamente.
401 em chamadas do MCP Token expirado ou escopo incorreto Use o escopo https://ai.azure.com/.default e atualize o token.
Nomes de ferramentas que não correspondem Os nomes de ferramentas DO MCP são prefixados com server_label Usar {server_label}.{tool_name} formato (por exemplo, myserver.get_info).
500 em send_ping() O servidor MCP da caixa de ferramentas não implementa o método MCP ping . Não ligue send_ping(). Se seu framework o chamar automaticamente (por exemplo, o MCPStreamableHTTPTool._ensure_connected() do Microsoft Agent Framework), desative a verificação de ping ou substitua o método por uma operação nula.
500 em prompts/list O servidor MCP do Foundry não implementa prompts/list. Passe load_prompts=False (ou equivalente) para o construtor do cliente MCP.
500 com não-streaming tools/call Não há suporte para o modo não streaming (stream=False) para endpoints MCP da toolbox. Sempre use stream=True ao chamar ferramentas MCP da caixa de ferramentas.
500 em tools/list Erro de servidor transitório Tente novamente após alguns segundos.
Variáveis de ambiente substituídas em runtime A plataforma reserva todas as variáveis de ambiente prefixadas FOUNDRY_ e pode substituir silenciosamente valores definidos pelo usuário. Renomeie variáveis de ambiente personalizadas para evitar o FOUNDRY_ prefixo (por exemplo, use TOOLBOX_MCP_ENDPOINT em vez de FOUNDRY_TOOLBOX_ENDPOINT).

A ferramenta de lembrete está disponível somente para agentes hospedados. Você não pode usar a ferramenta de lembretes com agentes de prompt.

Para obter instruções completas de instalação, exemplos de uso e limitações, consulte a ferramenta Lembrete para agentes de auto-agendamento.

Compatibilidade de região e modelo

A disponibilidade da caixa de ferramentas depende de dois fatores além da região do projeto:

  • Região: alguns tipos de ferramentas não estão disponíveis em todas as regiões que dão suporte ao serviço do agente. Por exemplo, uma região que suporta o endpoint da caixa de ferramentas pode não suportar todos os tipos de ferramentas incorporados.

Antes de implantar uma caixa de ferramentas, verifique se sua região de destino dá suporte aos tipos de ferramentas que você planeja usar. Para obter as tabelas de compatibilidade completas, consulte o suporte à Ferramenta por região e modelo.

Conteúdo relacionado

  • Last updated on