SpyBara
Go Premium

agent-sdk/tool-search.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

This page contains 10 additions and 10 deletions.

2026
Sat 3 23:57 Wed 14 22:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59

Escala a muchas herramientas con búsqueda de herramientas

Escala tu agente a miles de herramientas descubriendo y cargando solo lo que se necesita, bajo demanda.

La búsqueda de herramientas permite que tu agente trabaje con cientos o miles de herramientas descubriendo y cargándolas dinámicamente bajo demanda. En lugar de cargar todas las definiciones de herramientas en la ventana de contexto de antemano, el agente busca en tu catálogo de herramientas y carga solo las herramientas que necesita.

Este enfoque resuelve dos desafíos a medida que las bibliotecas de herramientas se escalan:

  • Eficiencia de contexto: Las definiciones de herramientas pueden consumir grandes porciones de la ventana de contexto (50 herramientas pueden usar 10-20K tokens), dejando menos espacio para el trabajo real.
  • Precisión de selección de herramientas: La precisión de selección de herramientas se degrada con más de 30-50 herramientas cargadas a la vez.

Cómo funciona la búsqueda de herramientas

La búsqueda de herramientas está activada de forma predeterminada, con las excepciones enumeradas en Configurar la búsqueda de herramientas.

Cuando está activa, las definiciones de herramientas se retienen de la ventana de contexto. El agente recibe un resumen de las herramientas disponibles y busca las relevantes cuando la tarea requiere una capacidad que no está ya cargada. Hasta cinco de las herramientas más relevantes se cargan en contexto de forma predeterminada, donde permanecen disponibles para turnos posteriores hasta que el SDK compacta los mensajes donde el agente las descubrió. Después de esa compactación, el agente busca esas herramientas nuevamente cuando las necesita.

La búsqueda de herramientas añade un viaje de ida y vuelta extra cada vez que Claude busca herramientas, pero para grandes conjuntos de herramientas esto se compensa con un contexto más pequeño en cada turno. Con menos de ~10 herramientas cuyas definiciones caben cómodamente en la ventana de contexto, cargar todo de antemano es típicamente más rápido.

Para detalles sobre el mecanismo API subyacente, consulta Búsqueda de herramientas en la API.

[!NOTE]

La búsqueda de herramientas no es compatible con implementaciones de Microsoft Foundry alojadas en Azure, que la rechazan del lado del servidor: el SDK detecta el rechazo y carga las definiciones de herramientas de antemano para esa implementación en su lugar. ENABLE_TOOL_SEARCH no puede anular esto, ya que el rechazo proviene de la implementación misma.

Configurar la búsqueda de herramientas

La búsqueda de herramientas está activada por defecto. Para los modelos en la lista de modelos no compatibles del SDK, el SDK carga las definiciones de herramientas de antemano en su lugar, y ningún valor ENABLE_TOOL_SEARCH sobrescribe eso. En Google Cloud's Agent Platform, el SDK decide por generación de modelo:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 y posterior: la búsqueda de herramientas está activada por defecto.
  • Modelos anteriores de Agent Platform: el SDK carga las definiciones de herramientas de antemano, porque sus pilas de servicio rechazan el encabezado beta requerido. ENABLE_TOOL_SEARCH no puede sobrescribir esto.

Antes de Claude Code v2.1.221, el SDK deshabilitaba la búsqueda de herramientas para todos los modelos en Google Cloud's Agent Platform a menos que establecieras ENABLE_TOOL_SEARCH.

[!NOTE]

La búsqueda de herramientas está activada por defecto detrás de un gateway ANTHROPIC_BASE_URL, sin nada que configurar. Si el gateway la rechaza, consulta Búsqueda de herramientas a través de un gateway de LLM. Antes de Claude Code v2.1.304, el SDK deshabilitaba la búsqueda de herramientas detrás de un gateway de este tipo a menos que ENABLE_TOOL_SEARCH fuera true, auto o auto:N.

Controlas si las definiciones de herramientas se difieren y cuándo con la variable de entorno ENABLE_TOOL_SEARCH, que acepta estos valores:

Valor Comportamiento
(sin establecer) La búsqueda de herramientas está activada, con las definiciones de herramientas diferidas y descubiertas bajo demanda. Recurre a la carga de antemano en los modelos anteriores a Opus 4 y Sonnet 4, en los modelos anteriores de Agent Platform y en los despliegues de Microsoft Foundry alojados en Azure.
true La búsqueda de herramientas está activada, con las mismas alternativas de respaldo que (sin establecer).
auto La búsqueda de herramientas está desactivada y las definiciones de herramientas se cargan de antemano hasta que las definiciones que puede diferir alcanzan el 10% de la ventana de contexto del modelo. Entonces la búsqueda de herramientas se activa y puede permanecer activada en la misma conversación aunque esas definiciones bajen después por debajo del 10%.
auto:N Igual que auto con un porcentaje personalizado. auto:5 se activa cuando esas definiciones alcanzan el 5% de la ventana de contexto. Los valores más bajos se activan antes.
false La búsqueda de herramientas está desactivada. Todas las definiciones de herramientas se cargan en contexto en cada turno.

Establecer CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la búsqueda de herramientas desactivada. No puedes sobrescribirlo estableciendo ENABLE_TOOL_SEARCH tú mismo. En Claude Code v2.1.227 o posterior, tu organización puede mantener la búsqueda de herramientas activada con esta variable a través de configuración administrada. En una sesión que recibe la configuración HIPAA, la búsqueda de herramientas está desactivada, y ni ENABLE_TOOL_SEARCH ni la configuración administrada la vuelven a activar. Deshabilitar capacidades de pre-lanzamiento cubre dónde se aplica la sobrescritura y qué elimina la variable.

La búsqueda de herramientas se aplica a todas las herramientas registradas, ya sea que provengan de servidores MCP remotos o servidores MCP personalizados del SDK. Cuando utilizas auto, el SDK cuenta todas las definiciones que la búsqueda de herramientas puede diferir hacia un umbral combinado: cada herramienta MCP que no esté marcada como alwaysLoad, de cualquier servidor, más las herramientas integradas que se cargan bajo demanda. El SDK carga las herramientas integradas principales como Bash, Read y Edit de antemano y no las cuenta hacia el umbral. Un mod en uno de tus plugins también puede diferir una herramienta o cargarla de antemano, lo que cambia ese conteo.

Establece el valor en la opción env en query(). En TypeScript, env reemplaza el entorno del subproceso, por lo que debes expandir ...process.env para mantener las variables heredadas. En Python, env se fusiona sobre el entorno heredado. Este ejemplo se conecta a un servidor MCP remoto que expone muchas herramientas, pre-aprueba todas ellas con un comodín, y utiliza auto:5 para que la búsqueda de herramientas se active cuando las definiciones que puede diferir alcanzan el 5% de la ventana de contexto:

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  for await (const message of query({
    prompt: "Find and run the appropriate database query",
    options: {
      mcpServers: {
        "enterprise-tools": {
          // Connect to a remote MCP server
          type: "http",
          url: "https://tools.example.com/mcp"
        }
      },
      allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
      env: {
        ...process.env, // env replaces the subprocess environment, so keep inherited variables
        ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      console.log(message.result);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result
  console.log(`Session ended with an error: ${error}`);
}

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when deferrable definitions reach 5% of context
        },
    )

    try:
        async for message in query(
            prompt="Find and run the appropriate database query",
            options=options,
        ):
            if isinstance(message, ResultMessage) and message.subtype == "success":
                print(message.result)
    except Exception as error:
        # A single-shot query() raises after yielding an error result
        print(f"Session ended with an error: {error}")


asyncio.run(main())

Para ejecutar este ejemplo, reemplaza https://tools.example.com/mcp con la URL de tu propio servidor MCP. Si tiene éxito, el texto del resultado se imprime en la consola.

Debido a que se trata de una llamada query() de un solo disparo, el SDK genera una excepción después de producir un resultado de error, por lo que el ejemplo envuelve el bucle en un bloque try. Para ver por qué falló una ejecución, verifica el subtype del mensaje de resultado, como error_during_execution, dentro del bucle. Para obtener más información sobre los mensajes de resultado, consulta Manejar el resultado.

Optimizar el descubrimiento de herramientas

El mecanismo de búsqueda coincide consultas contra nombres y descripciones de herramientas. Nombres como search_slack_messages aparecen para un rango más amplio de solicitudes que query_slack. Las descripciones con palabras clave específicas ("Buscar mensajes de Slack por palabra clave, canal o rango de fechas") coinciden con más consultas que las genéricas ("Consultar Slack").

También puede añadir una sección de indicación del sistema listando categorías de herramientas disponibles. Esto le da al agente contexto sobre qué tipos de herramientas están disponibles para buscar. Pase el texto a través de la opción systemPrompt en TypeScript o system_prompt en Python, utilizando el preset claude_code con append, que añade su texto al prompt del preset en lugar de reemplazarlo:

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "You can search for tools to interact with Slack, GitHub, and Jira."
  }
}

options = ClaudeAgentOptions(
    system_prompt={
        "type": "preset",
        "preset": "claude_code",
        "append": "You can search for tools to interact with Slack, GitHub, and Jira.",
    }
)

Para el conjunto completo de opciones de indicación del sistema, consulte Modificación de indicaciones del sistema.

Límites

  • Herramientas máximas: 10,000 herramientas en tu catálogo
  • Resultados de búsqueda: devuelve hasta cinco herramientas más relevantes por búsqueda de forma predeterminada
  • Soporte de modelo: Opus 4, Sonnet 4, Haiku 4.5 y modelos posteriores, u Opus 4.5, Sonnet 4.5, Haiku 4.5 y modelos posteriores en Agent Platform de Google Cloud. En modelos anteriores, el SDK carga las definiciones de herramientas por adelantado, como se describe en Configurar la búsqueda de herramientas.

Documentación relacionada