Herramientas

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

También se admiten herramientas personalizadas definidas por el usuario. Tu aplicación ejecuta estas herramientas por separado y envía los resultados de las herramientas de vuelta a Claude; Claude puede usar los resultados para continuar con la tarea en cuestión.

Herramientas disponibles

El conjunto de herramientas del agente incluye las siguientes herramientas. Todas están habilitadas por defecto cuando incluyes el conjunto de herramientas en la configuración de tu agente.

Configurar el conjunto de herramientas

Habilita el conjunto de herramientas completo con agent_toolset_20260401 al crear un agente. Usa el array configs para deshabilitar herramientas específicas o anular su configuración.

Deshabilitar herramientas específicas

Para deshabilitar una herramienta, establece enabled: false en su entrada de configuración:

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

Habilitar solo herramientas específicas

Para comenzar con todo deshabilitado 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 personalizadas definidas por el usuario en la API de Messages.

Las herramientas personalizadas te permiten ampliar las capacidades de Claude para realizar una variedad más amplia de tareas. Cada herramienta define un contrato: especificas qué operaciones están disponibles y qué devuelven; Claude decide cuándo y cómo llamarlas. El modelo nunca ejecuta nada por su cuenta. Emite una solicitud estructurada, tu código ejecuta la operación, y el resultado fluye de vuelta a la conversación.

Una vez que hayas definido la herramienta a nivel de agente, el agente invocará las herramientas durante el curso de una sesión. Consulta Flujo de eventos de sesión para el flujo completo.

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, cuándo debe usarse (y cuándo no), qué significa cada parámetro y cómo afecta al comportamiento de la herramienta, y cualquier advertencia o limitación importante. Cuanto más contexto puedas dar a Claude sobre tus herramientas, mejor será a la hora de decidir cuándo y cómo usarlas. Apunta a al menos 3-4 oraciones por 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 única herramienta con un parámetro action. Menos herramientas, más capaces, reducen la ambigüedad de 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, prefija los nombres con el recurso (por ejemplo, db_query, 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 alta señal. 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 razonar sobre su próximo paso. Las respuestas infladas desperdician contexto y hacen que sea más difícil para Claude extraer lo que importa.