Herramientas

Claude Managed Agents proporciona un conjunto de herramientas integradas que Claude puede usar de forma autónoma dentro de una sesión. Tú controlas qué herramientas están disponibles especificándolas en la configuración del agente.

Claude Managed Agents también admite herramientas personalizadas definidas por el usuario. Tu aplicación ejecuta estas herramientas por separado y devuelve los resultados a Claude, que los usa para continuar la tarea. Para darle al agente herramientas de un servidor MCP, usa el conector MCP en su lugar.



Herramientas disponibles

El conjunto de herramientas del agente incluye las siguientes herramientas. Todas están habilitadas de forma predeterminada cuando incluyes el conjunto de herramientas en la configuración de tu agente. Usa los valores de la columna Nombre para referenciar las herramientas en el arreglo configs.

Cuando la salida de una herramienta supera los 100,000 caracteres (alrededor de 25,000 tokens), se escribe automáticamente en un archivo en el sandbox. El modelo recibe una vista previa truncada con la ruta del archivo y puede leer el contenido completo desde allí.



Configurar el conjunto de herramientas

Habilita el conjunto completo de herramientas con agent_toolset_20260401 al crear un agente. Usa el arreglo configs para deshabilitar herramientas específicas o sobrescribir su configuración. Cada entrada de configuración también puede establecer una permission_policy que controla si las llamadas de la herramienta se aprueban automáticamente o requieren confirmación. Consulta Políticas de permisos para conocer los tipos de políticas disponibles.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
YAML



Deshabilitar herramientas específicas

Para deshabilitar una herramienta, establece enabled: false en su entrada de configuración en el objeto del conjunto de herramientas del arreglo tools de tu agente:

{
  "type": "agent_toolset_20260401",
  "configs": [
    { "name": "web_fetch", "enabled": false },
    { "name": "web_search", "enabled": false }
  ]
}



Habilitar solo herramientas específicas

El objeto default_config establece la línea base para cada herramienta del conjunto, y las entradas configs por herramienta la sobrescriben. Para comenzar con todo desactivado y habilitar solo lo que necesitas, establece default_config.enabled en false:

{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash", "enabled": true },
    { "name": "read", "enabled": true },
    { "name": "write", "enabled": true }
  ]
}



Herramientas personalizadas

Además de las herramientas integradas, puedes definir herramientas personalizadas. Las herramientas personalizadas son análogas a las herramientas de cliente definidas por el usuario en la Messages API.

Cada herramienta personalizada define un contrato: tú especificas qué operaciones están disponibles y qué devuelven, y Claude determina cuándo y cómo llamarlas. El modelo nunca ejecuta nada por sí mismo. Emite una solicitud estructurada, tu código ejecuta la operación y el resultado fluye de vuelta a la conversación. Consulta Flujo de eventos de sesión para saber cómo recibir llamadas a herramientas personalizadas y devolver resultados durante una sesión.

Si tus sesiones se ejecutan en un sandbox autoalojado, el worker del entorno puede servir herramientas personalizadas desde tu sandbox, incluidas herramientas que envuelven un servidor MCP dentro de tu red.

ant beta:agents create <<'YAML'
name: Weather Agent
model: claude-opus-5
tools:
  - type: agent_toolset_20260401
  - type: custom
    name: get_weather
    description: Get current weather for a location
    input_schema:
      type: object
      properties:
        location:
          type: string
          description: City name
      required:
        - location
YAML

Una vez que hayas definido herramientas personalizadas en el agente, el agente las invoca durante una sesión.



Mejores prácticas para definiciones de herramientas personalizadas

• Proporciona descripciones extremadamente detalladas. Este es, con diferencia, el factor más importante en el rendimiento de las herramientas. Tus descripciones deben explicar qué hace la herramienta y cuándo usarla (y cuándo no). Explica qué significa cada parámetro y cómo afecta el comportamiento de la herramienta. Señala cualquier advertencia o limitación importante. Cuanto más contexto puedas darle a Claude sobre tus herramientas, mejor será para determinar cuándo y cómo usarlas. Apunta a tres o cuatro oraciones por cada descripción de herramienta, más si la herramienta es compleja.
• Consolida operaciones relacionadas en menos herramientas. En lugar de crear una herramienta separada para cada acción (create_pr, review_pr, merge_pr), agrúpalas en una sola herramienta con un parámetro action. Menos herramientas, pero más capaces, reducen la ambigüedad en la selección y hacen que tu superficie de herramientas sea más fácil de navegar para Claude.
• Usa espacios de nombres significativos en los nombres de las herramientas. Cuando tus herramientas abarcan múltiples servicios o recursos, antepón el recurso al nombre (por ejemplo, db_query o storage_read). Esto hace que la selección de herramientas sea inequívoca a medida que tu biblioteca crece.
• Diseña las respuestas de las herramientas para devolver solo información de alto valor. Devuelve identificadores semánticos y estables (por ejemplo, slugs o UUIDs) en lugar de referencias internas opacas, e incluye solo los campos que Claude necesita para determinar su siguiente paso. Las respuestas infladas desperdician contexto y dificultan que Claude extraiga lo que importa.



Próximos pasos