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 del agente.

Cuando la salida de una herramienta supera los 100,000 caracteres (aproximadamente 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í.

Configuración del 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 se identifica por su name, que toma un valor de la columna Nombre en Herramientas disponibles. Una entrada también acepta un campo opcional type con el mismo valor.

Cada entrada de configuración también puede establecer un permission_policy. La política controla si las llamadas de la herramienta se ejecutan sin confirmación, requieren confirmación o son evaluadas individualmente por el servidor. Consulta Políticas de permisos para ver los tipos de políticas disponibles.

El siguiente ejemplo habilita el conjunto de herramientas y deshabilita web_fetch:

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_fetch
        enabled: false
---

Deshabilitar herramientas específicas

Para deshabilitar una herramienta, establece enabled: false en su entrada de configs:

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

Restringir la búsqueda web y la obtención web

Las entradas web_search y web_fetch también aceptan listas de dominios, un límite para el contenido obtenido y una ubicación de búsqueda. Consulta Restringir los dominios de búsqueda web y obtención web.

Tipos de entradas de configuración en los SDK

Los SDK de Python, TypeScript, Go, Java, C#, Ruby y PHP tipan cada entrada de configs por herramienta. El tipo es una unión con un miembro por cada herramienta integrada, discriminada por type.

En Go, Java, C# y PHP, construyes las entradas a partir de valores tipados en lugar de diccionarios o hashes simples. En esos SDK, el tipo de elemento de configs es la propia unión, así que construye cada entrada a partir de su tipo de miembro por herramienta.

Puedes omitir type al construir una entrada, porque el servidor lo infiere a partir de name. Las respuestas siempre lo incluyen. Este tipado no cambia el JSON al que se serializa una entrada. Una solicitud cuyas entradas establecen solo name, enabled y permission_policy es válida con o sin type.

Herramientas personalizadas

Las herramientas personalizadas son análogas a las herramientas de cliente definidas por el usuario en la Messages API. Tú especificas qué operaciones están disponibles y qué devuelven, y Claude determina cuándo y cómo llamarlas.

Claude no ejecuta una herramienta personalizada por sí mismo. Emite una solicitud estructurada, tu código ejecuta la operación y tú devuelves el resultado a la sesión.

El siguiente ejemplo crea un agente con el conjunto de herramientas integrado y una herramienta personalizada, get_weather:

ant apply agent.md

---
name: Weather Agent
model: claude-opus-5-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
---

El nombre de una herramienta personalizada no puede comenzar con mcp__ ni con ant__, ni coincidir con el nombre de una herramienta integrada del agente. Una solicitud que incumpla esta regla devuelve un error 400. Un agente que ya tiene una herramienta personalizada cuyo nombre comienza con ant__ acepta una actualización solo si la actualización envía tools sin ese nombre, así que cambia el nombre de la herramienta o elimínala en tu próxima actualización. Una nueva sesión se rechaza con un error 400 si dicha herramienta está en su agente (después de cualquier sobrescritura), en un agente de la lista predefined_agents de subagents, o en un agente de la lista predefined_agents de workflows. Las sesiones que ya existen no se ven afectadas.

El agente llama a sus herramientas personalizadas durante una sesión. Para recibir las llamadas y devolver los resultados, consulta Flujo de eventos de la sesión.

Para las sesiones que se ejecutan en un sandbox autoalojado, el worker del entorno puede servir herramientas personalizadas desde el sandbox. Estas pueden incluir herramientas que envuelven un servidor MCP dentro de tu red.

Mejores prácticas para las definiciones de herramientas personalizadas

• Proporciona descripciones extremadamente detalladas. Este es, con diferencia, el factor más importante en el rendimiento de las herramientas. Cuanto más contexto puedas darle a Claude sobre tus herramientas, mejor podrá 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. Tus descripciones deben cubrir:
  • Qué hace la herramienta
  • Cuándo usarla y cuándo no
  • Qué significa cada parámetro y cómo afecta el comportamiento de la herramienta
  • Cualquier advertencia o limitación importante
• Consolida las operaciones relacionadas en menos herramientas. Agrupa acciones como create_pr, review_pr y merge_pr 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 a los nombres el recurso (por ejemplo, db_query o storage_read). Esto hace que la selección de herramientas no sea ambigua a medida que crece tu biblioteca.
• Diseña las respuestas de las herramientas para que devuelvan solo información de alto valor. Devuelve identificadores semánticos y estables (por ejemplo, slugs o UUID) en lugar de referencias internas opacas. Incluye solo los campos que Claude necesita para determinar su siguiente paso. Las respuestas sobrecargadas desperdician contexto y dificultan que Claude extraiga lo importante.

Próximos pasos