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. Cada entrada en el array configs se identifica por su name, usando los valores de la columna Nombre, y acepta un campo type opcional con el mismo valor. Las entradas web_search y web_fetch aceptan configuraciones adicionales; consulta Restringir dominios de búsqueda web y obtención web.

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 toolset completo con agent_toolset_20260401 al crear un agente. Usa el array 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 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.

Las entradas de configuración para web_search y web_fetch también aceptan filtros de dominio y otras configuraciones web; consulta Restringir dominios de búsqueda web y obtención web.

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 configuración en el objeto del conjunto de herramientas del array 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 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 dominios de búsqueda web y obtención web

Para controlar a qué sitios pueden acceder las herramientas web del agente, establece allowed_domains (la herramienta solo puede acceder a estos hosts) o blocked_domains (la herramienta nunca puede acceder a estos hosts) en las entradas web_search y web_fetch del array configs del conjunto de herramientas. Cada herramienta lleva su propia lista, por lo que web_search y web_fetch pueden tener restricciones diferentes. Un dominio listado cubre ese host y todos sus subdominios. En tiempo de ejecución, una llamada a web_fetch para una URL que sus listas no permiten devuelve un resultado de error al agente (is_error: true en el evento agent.tool_result, con contenido que nombra el código de error url_not_allowed), y web_search omite los resultados que sus listas no permiten.

El siguiente conjunto de herramientas limita web_search a dos sitios y localiza sus resultados, y bloquea un host para web_fetch mientras limita cuánto contenido obtenido entra en el contexto:

{
  "type": "agent_toolset_20260401",
  "configs": [
    {
      "type": "web_search",
      "name": "web_search",
      "allowed_domains": ["docs.example.com", "arxiv.org"],
      "user_location": {
        "type": "approximate",
        "country": "US",
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "type": "web_fetch",
      "name": "web_fetch",
      "blocked_domains": ["ads.example.com"],
      "max_content_tokens": 50000
    }
  ]
}

La siguiente solicitud crea un agente con este conjunto de herramientas e imprime el array configs de la respuesta:

ant apply agent.md

---
name: Research Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - type: web_search
        name: web_search
        allowed_domains: [docs.example.com, arxiv.org]
        user_location:
          type: approximate
          country: US
          timezone: America/Los_Angeles
      - type: web_fetch
        name: web_fetch
        blocked_domains: [ads.example.com]
        max_content_tokens: 50000
---

En la Claude Console, establece los dominios permitidos o bloqueados desde las filas web_search y web_fetch de la tarjeta Built-in tools en el formulario del agente; establece max_content_tokens y user_location en la vista Raw de la configuración del agente.

Además de enabled y permission_policy, las entradas de las herramientas web aceptan las siguientes configuraciones:

Reglas de las listas de dominios

• Establece allowed_domains o blocked_domains en una entrada, no ambos. Una entrada que establece ambos se rechaza.
• Cada lista contiene de 1 a 64 dominios, cada uno de 1 a 255 caracteres. Una lista vacía se rechaza: para no aplicar ninguna restricción, omite el campo o envía null.
• Cada dominio es un nombre de dominio registrable, o un subdominio de uno, escrito como un nombre de host simple: letras ASCII, dígitos, guiones, guiones bajos y puntos, sin esquema, puerto, credenciales, comodín ni espacios en blanco, sin ninguna etiqueta que comience o termine con un guion, y sin ninguna ruta aparte del sufijo de ruta opcional de web_search descrito más adelante en esta lista. Usa example.com, no https://example.com, example.com:443 ni *.example.com. Los nombres de host se comparan sin distinguir mayúsculas de minúsculas, y se ignora una única / final.
• Un dominio listado coincide con ese host y sus subdominios: example.com cubre docs.example.com, pero docs.example.com no cubre example.com ni api.example.com. Un www. inicial es un subdominio como cualquier otro, por lo que www.example.com no cubre example.com; lista el dominio sin prefijo para cubrir ambos.
• Las direcciones IP no se aceptan en ninguna forma, ya sea IPv4, IPv6, entre corchetes o abreviaturas numéricas como 127.1. Lista el nombre de dominio del sitio en su lugar.
• Un dominio de nivel superior sin más o un sufijo de registro como com, co.uk o gov.uk se rechaza, al igual que un nombre de una sola etiqueta como intranet. Lista un dominio completo como example.co.uk.
• localhost y los hosts que terminan en .localhost, .local, .internal, .localdomain o .invalid se rechazan.
• Usa la forma xn-- (Punycode) para los nombres de dominio internacionalizados; un dominio que contiene caracteres no ASCII se rechaza.
• Un dominio de web_fetch no puede incluir una ruta: usa example.com, no example.com/*. Un dominio de web_search puede llevar un sufijo de ruta como example.com/blog, en el cual la ruta no puede contener espacios, ?, # ni ninguno de los caracteres $ , | ^ !. Prefiere nombres de host simples también para web_search, porque el proveedor de búsqueda compara los sufijos de ruta como patrones de URL en lugar de como reglas estrictas de host.
• Los dominios duplicados dentro de una lista se rechazan. www.example.com y example.com cuentan como dominios diferentes; consulta la regla de coincidencia anterior para saber qué cubre cada uno.

Cuándo se validan las configuraciones

Las infracciones de formato y de límites se rechazan con un error 400 invalid_request_error cuando creas un agente o actualizas un agente, y cuando creas o actualizas una sesión que proporciona tools. Por ejemplo, el mensaje para una entrada que establece ambas listas incluye Only one of allowed_domains or blocked_domains may be set., y el mensaje para una lista vacía incluye allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. El mensaje para un dominio que infringe una regla de formato nombra su lista y su posición basada en cero, por ejemplo allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com".

Las mismas solicitudes también rechazan tres configuraciones que dependen de los proveedores de búsqueda y obtención: un dominio en allowed_domains al que el rastreador de Anthropic no tiene permitido acceder, un user_location.country que el proveedor de búsqueda no admite (el mensaje termina en user_location.country: not a country the search provider supports), y un user_location.timezone que no es un nombre IANA válido. La sesión verifica la configuración de nuevo cuando inicializa la herramienta por primera vez; si una configuración que se aceptó anteriormente ya no es válida en ese momento, la sesión emite un evento session.error y vuelve a idle sin reintentar. Corrige la configuración actualizando las herramientas de la sesión, actualiza también el agente para que las nuevas sesiones comiencen con la configuración corregida, y luego envía un nuevo user.message para continuar.

Sesiones multiagente, resultados y actualizaciones a mitad de sesión

En una sesión multiagente, todas las listas de dominios que se aplican a un hilo se hacen cumplir al mismo tiempo: un agente en la lista del coordinador está sujeto a sus propios allowed_domains y blocked_domains, a los de cualquier agente que lo haya llamado y a las listas actuales del coordinador.

• Las listas de permitidos se combinan en los dominios que todas ellas cubren, y las listas de bloqueados se suman, por lo que un agente de la lista puede reducir a qué accede una herramienta pero nunca ampliarlo. Por ejemplo, un agente de la lista que establece blocked_domains mantiene los allowed_domains del coordinador y bloquea esos hosts dentro de ellos, y un agente de la lista que establece sus propios allowed_domains solo puede acceder a los hosts que cubren tanto su lista como la lista del coordinador.
• Si las listas de permitidos combinadas no tienen ningún dominio en común, la herramienta sigue disponible para ese agente, pero cada llamada falla con un error url_not_allowed que indica que no se permite ningún dominio, y la descripción de la herramienta se lo indica al modelo. Mantén la lista de permitidos de cada agente de la lista dentro de la del coordinador para evitar esto.
• max_content_tokens y user_location no se combinan: un hilo usa el valor de su propia configuración de herramientas si está establecido; de lo contrario, el del agente que lo llamó; de lo contrario, el de la configuración actual del coordinador.
• Una entrada de lista {"type": "self"} no tiene configuraciones web propias y sigue las configuraciones actuales del coordinador.
• El evaluador en las sesiones orientadas a resultados se ejecuta sin web_search ni web_fetch, independientemente de estas configuraciones.
• Puedes cambiar las listas en una sesión inactiva actualizando sus herramientas. Las nuevas listas se aplican al resto de la sesión; en una sesión multiagente, cada hilo las aplica a partir de su siguiente turno, mientras que las listas propias de un agente de la lista permanecen como las estableció su definición de agente cuando se creó la sesión.

Diferencias con las herramientas de la Messages API

Estas configuraciones usan el mismo vocabulario allowed_domains y blocked_domains que el filtrado de dominios en las herramientas de servidor de la Messages API, con las siguientes diferencias en Managed Agents:

• Cada lista está limitada a 64 dominios.
• Los dominios listados para web_fetch no pueden incluir una ruta.
• Los dominios deben ser ASCII: usa la forma xn-- (Punycode) para los nombres de dominio internacionalizados. La Messages API acepta entradas Unicode, aunque recomienda no usarlas.
• max_uses, citations y cache_control no están disponibles en el conjunto de herramientas.

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 la 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 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
---

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

Mejores prácticas para las definiciones de herramientas personalizadas

• Proporciona descripciones extremadamente detalladas. Este es, por mucho, 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 para cada descripción de herramienta, más si la herramienta es compleja.
• Consolida las 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 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, 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 alta señal. Devuelve identificadores semánticos y estables (por ejemplo, slugs o UUID) 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 hacen más difícil que Claude extraiga lo que importa.

Próximos pasos