Habilitación de la búsqueda de herramientas en un cuadro de herramientas (versión preliminar)

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_preview 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 MCPTool, ToolboxSearchPreviewTool

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

# ToolboxSearchPreviewTool() 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 = MCPTool(
    server_label="github",
    server_url="https://api.githubcopilot.com/mcp",
    require_approval="never",
    project_connection_id="github-mcp-conn",
)

toolbox_version = client.beta.toolboxes.create_version(
    name="my-toolbox",
    description="Large toolbox with tool search enabled",
    tools=[inner_mcp_tool, ToolboxSearchPreviewTool()],
)
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_preview"
    },
    {
      "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();

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

ToolboxVersion toolboxVersion = toolboxClient.CreateToolboxVersion(
    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_preview" } 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.beta.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_preview" },
  ],
  { 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"

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

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 -- only tool_search should appear initially
            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]}")

            # Confirm tool_search is present
            names = [t.name for t in tools_result.tools]
            assert "tool_search" in names, "tool_search not found -- check toolbox_search_preview config"

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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

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

En result.tools, tool_search debe estar presente y todas las demás herramientas del cuadro de herramientas deben estar ausentes en la lista inicial.

Use cualquier cliente de .NET compatible con MCP. Adquiera un token con ámbito https://ai.azure.com/.default, incluya el encabezado Foundry-Features: Toolboxes=V1Preview y llame a tools/list en el punto de conexión de MCP específico de la versión. Vea la pestaña REST API para consultar el formato de la solicitud.

Use cualquier cliente de JavaScript compatible con MCP (por ejemplo, el @modelcontextprotocol/sdk paquete). Adquiera un token con ámbito https://ai.azure.com/.default, incluya el encabezado Foundry-Features: Toolboxes=V1Preview y llame a tools/list en el punto de conexión de MCP específico de la versión. Consulte la pestaña API REST para ver la estructura de la solicitud.

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_preview"},
    {
        "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_preview" },
    {
      "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.beta.toolboxes.createVersion. La forma de configuración es idéntica al JSON que se muestra en la pestaña API REST .

{
    "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.

Use la misma clave comodín "*" dentro de tool_configs en el objeto de la herramienta MCP de JavaScript para anclar todas las herramientas de un servidor MCP. Consulte la pestaña API de REST para la forma JSON.

{
    "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.beta.toolboxes.createVersion. La forma coincide con el JSON que se muestra en la pestaña API rest .