Habilitar a pesquisa de ferramentas em uma caixa de ferramentas

Use o Foundry Toolkit para Visual Studio Code para habilitar a pesquisa de ferramentas ao criar ou editar uma caixa de ferramentas. A caixa de seleção Pesquisa de ferramentas adiciona a entrada de configuração toolbox_search à versão da caixa de ferramentas.

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. Selecione Busca 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. Para ver o fluxo de trabalho completo de criação da caixa de ferramentas, consulte Organizar a caixa de ferramentas baseada em intenções no Foundry.

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

project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

# ToolSearchToolboxTool() enables tool search — other tools in the toolbox are discovered on
# demand through tool_search instead of being listed up front. Add as many MCP servers as you need;
# tool search keeps the agent's initial tool surface small regardless of toolbox size.
inner_mcp_tool = MCPToolboxTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="never",
    project_connection_id="github-mcp-conn",
)

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Large toolbox with tool search enabled",
    tools=[inner_mcp_tool, ToolSearchToolboxTool()],
)
print(f"Created toolbox `{toolbox_version.name}` (version {toolbox_version.version})")

Para fixar ferramentas críticas ou adicionar palavras-chave de pesquisa para ferramentas específicas, use tool_configs na entrada de ferramenta individual. Consulte Descoberta de ferramentas de ajuste fino.

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

{
  "description": "Large toolbox with tool search enabled",
  "tools": [
    {
      "type": "toolbox_search"
    },
    {
      "type": "work_iq_preview",
      "project_connection_id": "{workiq-connection-id}",
      "tool_configs": {
        "calendar_events": {
          "pin": true,
          "additional_search_text": "meetings appointments schedule calendar invites"
        }
      }
    },
    {
      "type": "mcp",
      "server_label": "github",
      "server_url": "https://api.githubcopilot.com/mcp",
      "require_approval": "never",
      "project_connection_id": "github-mcp-conn"
    }
  ]
}

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

// ToolSearchToolboxTool enables tool search — other tools are discovered on demand via tool_search
MCPToolboxTool mcpTool = new(serverLabel: "github")
{
  ServerUri = new Uri("https://api.githubcopilot.com/mcp"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};
ToolSearchToolboxTool searchTool = new()
{
    Name = "ToolBoxSearch",
    Description = "Search for tools by capability"
};

ToolboxVersion toolboxVersion = toolboxClient.CreateVersion(
    name: "my-toolbox",
    tools: [mcpTool, searchTool],
    description: "Large toolbox with tool search enabled");
Console.WriteLine($"Created toolbox `{toolboxVersion.Name}` (version {toolboxVersion.Version})");

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

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

// { type: "toolbox_search" } enables tool search — other tools in the toolbox are
// discovered on demand through tool_search instead of being listed up front. Add as many MCP
// servers as you need; tool search keeps the agent's initial tool surface small regardless of size.
const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "mcp",
      server_label: "github",
      server_url: "https://api.githubcopilot.com/mcp",
      require_approval: "never",
      project_connection_id: "github-mcp-conn",
    },
    { type: "toolbox_search" },
  ],
  { description: "Large toolbox with tool search enabled" },
);
console.log(`Created toolbox \`${toolboxVersion.name}\` (version ${toolboxVersion.version})`);

O Foundry Toolkit cria e publica a caixa de ferramentas. Para verificar a resposta do endpoint MCP de uma versão específica do kit de ferramentas, selecione a guia Python, .NET, JavaScript ou REST API nesta seção.

Instale o SDK do cliente MCP se você ainda não tiver:

pip install mcp

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"
expected_pinned_tools = {"calendar_events"}  # Match the tools configured with pin=True.

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 the two meta-tools and any explicitly pinned 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]}")

            names = {tool.name for tool in tools_result.tools}
            meta_tools = {"tool_search", "call_tool"}
            assert meta_tools <= names, "Tool Search meta-tools are missing -- check toolbox_search config"
            assert expected_pinned_tools <= names, "A configured pinned tool is missing"

            unexpected_tools = names - meta_tools - expected_pinned_tools
            assert not unexpected_tools, f"Unpinned tools are visible: {sorted(unexpected_tools)}"

asyncio.run(verify_toolbox())

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

Em result.tools, confirme que tool_search, call_toole todas as ferramentas configuradas com pin: true estão presentes. Todas as ferramentas comuns não fixadas da barra de ferramentas não devem aparecer na lista inicial.

Use qualquer cliente .NET compatível com MCP. Adquira um token com escopo https://ai.azure.com/.default e chame tools/list contra o ponto de extremidade MCP específico da versão. Consulte a aba API REST para ver o formato da solicitação.

Instale o SDK do cliente MCP se você ainda não tiver:

npm install @modelcontextprotocol/sdk @azure/identity

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

const url =
  "https://<account>.services.ai.azure.com/api/projects/<proj>" +
  "/toolboxes/<name>/versions/<version>/mcp?api-version=v1";
// Match the tools configured with pin: true.
const expectedPinnedTools = new Set(["calendar_events"]);

async function verifyToolbox() {
  const credential = new DefaultAzureCredential();
  const tokenResponse = await credential.getToken(
    "https://ai.azure.com/.default",
  );
  if (!tokenResponse) {
    throw new Error("Failed to acquire an access token.");
  }

  // Build the bearer header from the acquired token. Using tokenResponse.token
  // here reveals no secret in source -- it's a variable reference resolved at
  // runtime, not a hardcoded value.
  const authorizationHeader = "Bearer " + tokenResponse.token;
  const transport = new StreamableHTTPClientTransport(new URL(url), {
    requestInit: {
      headers: { Authorization: authorizationHeader },
    },
  });

  const client = new Client({ name: "tool-search-verifier", version: "1.0.0" });
  await client.connect(transport);

  try {
    // List the two meta-tools and any explicitly pinned 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)}`);
    }

    const names = new Set(toolsResult.tools.map((tool) => tool.name));
    const metaTools = ["tool_search", "call_tool"];
    for (const metaTool of metaTools) {
      if (!names.has(metaTool)) {
        throw new Error(
          `Tool Search meta-tool "${metaTool}" is missing -- check toolbox_search config`,
        );
      }
    }
    for (const pinnedTool of expectedPinnedTools) {
      if (!names.has(pinnedTool)) {
        throw new Error(`A configured pinned tool is missing: ${pinnedTool}`);
      }
    }

    const unexpectedTools = [...names].filter(
      (name) => !metaTools.includes(name) && !expectedPinnedTools.has(name),
    );
    if (unexpectedTools.length > 0) {
      throw new Error(`Unpinned tools are visible: ${unexpectedTools.join(", ")}`);
    }
  } finally {
    await client.close();
  }
}

verifyToolbox().catch((err) => {
  console.error("The verifier encountered an error:", err);
});

O Foundry Toolkit dá suporte à habilitação da pesquisa de ferramentas. Para configurar ferramentas fixas ou palavras-chave de pesquisa extras, selecione a guia Python, .NET, JavaScript ou API REST nesta seção.

tools=[
    {"type": "toolbox_search"},
    {
        "type": "mcp",
        "server_label": "analytics",
        "server_url": "https://db-mcp.internal/sse",
        "tool_configs": {
            "execute_query": {"pin": True},  # always visible — no search needed
        },
    },
]

{
  "tools": [
    { "type": "toolbox_search" },
    {
      "type": "mcp",
      "server_label": "analytics",
      "server_url": "https://db-mcp.internal/sse",
      "tool_configs": {
        "execute_query": { "pin": true }
      }
    }
  ]
}

No SDK do .NET, anexe tool_configs à entrada da ferramenta MCP ao construir a versão da caixa de ferramentas. A forma de configuração é idêntica ao JSON mostrado na guia API REST .

No JavaScript, inclua tool_configs no objeto de ferramenta MCP passado para project.toolboxes.createVersion:

const tools = [
  { type: "toolbox_search" },
  {
    type: "mcp",
    server_label: "analytics",
    server_url: "https://db-mcp.internal/sse",
    tool_configs: {
      execute_query: { pin: true }, // always visible — no search needed
    },
  },
];

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "*": {"pin": True},  # every tool in this server is always visible
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "*": { "pin": true }
  }
}

Use a mesma chave curinga "*" dentro de tool_configs na entrada da ferramenta MCP .NET para fixar todas as ferramentas de um servidor MCP. Consulte a aba REST API para ver a estrutura JSON.

Use a mesma chave curinga "*" dentro de tool_configs no objeto da ferramenta MCP para JavaScript para fixar todas as ferramentas de um servidor MCP:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    "*": { pin: true }, // every tool in this server is always visible
  },
}

{
    "type": "mcp",
    "server_label": "analytics",
    "server_url": "https://db-mcp.internal/sse",
    "tool_configs": {
        "execute_query": {
            "pin": True,
            "additional_search_text": "SQL database analytics reporting dashboard queries",
        },
        "list_tables": {
            "additional_search_text": "schema columns metadata table structure discover",
        },
    },
}

{
  "type": "mcp",
  "server_label": "analytics",
  "server_url": "https://db-mcp.internal/sse",
  "tool_configs": {
    "execute_query": {
      "pin": true,
      "additional_search_text": "SQL database analytics reporting dashboard queries"
    },
    "list_tables": {
      "additional_search_text": "schema columns metadata table structure discover"
    }
  }
}

No SDK do .NET, defina additional_search_text (e, opcionalmente, pin) dentro tool_configs na entrada da ferramenta MCP. A forma corresponde ao JSON mostrado na guia API REST .

No JavaScript, defina additional_search_text (e opcionalmente pin) dentro tool_configs do objeto de ferramenta MCP passado para project.toolboxes.createVersion:

{
  type: "mcp",
  server_label: "analytics",
  server_url: "https://db-mcp.internal/sse",
  tool_configs: {
    execute_query: {
      pin: true,
      additional_search_text: "SQL database analytics reporting dashboard queries",
    },
    list_tables: {
      additional_search_text: "schema columns metadata table structure discover",
    },
  },
}