Habilitación de la búsqueda de herramientas en un cuadro de herramientas

Use Foundry Toolkit para Visual Studio Code para habilitar la búsqueda de herramientas al crear o editar un cuadro de herramientas. La casilla Búsqueda de herramientas agrega la entrada de configuración toolbox_search a la versión de la caja de herramientas.

1. Seleccione Foundry Toolkit en la barra de actividades.
2. En Mis recursos, expanda El nombre> del proyectoHerramientas.
3. Seleccione el icono + Agregar cuadro de herramientas .
4. En la pestaña Crear un cuadro de herramientas personalizado , escriba el nombre y la descripción del cuadro de herramientas y agregue las herramientas que desee.
5. Seleccione Búsqueda de herramientas.
6. Seleccione Publicar.

Al publicar un nuevo cuadro de herramientas, se genera automáticamente su primera versión. Esa versión se convierte automáticamente en la versión predeterminada. Para consultar el flujo de trabajo completo de creación de la caja de herramientas, consulte Organizar una caja de herramientas basada en intenciones en 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 anclar herramientas críticas o agregar palabras clave de búsqueda para herramientas específicas, use tool_configs en la entrada de herramienta individual. Consulte Detección de herramientas 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})`);

Foundry Toolkit crea y publica el cuadro de herramientas. Para comprobar la respuesta del punto de conexión de MCP para una versión específica del cuadro de herramientas, seleccione la pestaña Python, .NET, JavaScript o API REST de esta sección.

Instale el SDK de cliente MCP si aún no lo ha hecho:

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

Utilice el punto de conexión específico de la versión (/versions/{version}/mcp) para validar antes de promoverla.

1. Inicialice la sesión de 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 la notificación 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. Enumerar las herramientas disponibles:

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

En result.tools, confirme que tool_search, call_tooly todas las herramientas configuradas con pin: true están presentes. Todas las herramientas normales de la caja de herramientas que no estén ancladas deben estar ausentes de la lista inicial.

Use cualquier cliente de .NET compatible con MCP. Obtenga un token con el ámbito https://ai.azure.com/.default y realice la llamada tools/list al punto de conexión MCP específico de la versión. Vea la pestaña REST API para consultar el formato de la solicitud.

Instale el SDK de cliente MCP si aún no lo ha hecho:

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

Foundry Toolkit admite la habilitación de la búsqueda de herramientas. Para configurar herramientas ancladas o palabras clave de búsqueda adicionales, seleccione la pestaña Python, .NET, JavaScript o API REST de esta sección.

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

En el SDK de .NET, adjunte tool_configs a la entrada de la herramienta MCP al crear la versión del cuadro de herramientas. La forma de configuración es idéntica al JSON que se muestra en la pestaña API REST .

En JavaScript, incluya tool_configs en el objeto de herramienta MCP pasado a 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 la misma clave comodín "*" dentro de tool_configs en la entrada de la herramienta MCP de .NET para anclar todas las herramientas de un servidor MCP. Consulte la pestaña API de REST para la forma JSON.

Usa la misma "*" clave comodín dentro de tool_configs en el objeto de herramienta MCP de JavaScript para anclar todas las herramientas de un 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"
    }
  }
}

En el SDK de .NET, establezca additional_search_text (y, opcionalmente, pin) dentro de tool_configs en la entrada de la herramienta MCP. La forma coincide con el JSON que se muestra en la pestaña API rest .

En JavaScript, establezca additional_search_text (y opcionalmente pin) dentro tool_configs del objeto de herramienta MCP pasado a 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",
    },
  },
}