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 con 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 arreglo configs se identifica por su name, usando los valores de la columna Nombre, y acepta un campo opcional type 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í.



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 anular sus configuraciones. 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.

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 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 dentro del 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 individuales de configs la anulan. 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 arreglo configs del conjunto de herramientas. Cada herramienta tiene 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 arreglo configs de la respuesta:

ant beta:agents create --transform tools.0.configs <<'YAML'
name: Research Agent
model: claude-opus-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
YAML

En 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 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 es rechazada.
• Cada lista contiene de 1 a 64 dominios, cada uno de 1 a 255 caracteres. Una lista vacía es rechazada: 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 etiquetas que comiencen o terminen con un guion, y sin ruta salvo el 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.
• No se aceptan direcciones IP en ninguna forma, ya sea IPv4, IPv6, entre corchetes o en notación numérica abreviada como 127.1. Lista el nombre de dominio del sitio en su lugar.
• Un dominio de nivel superior simple o sufijo de registro como com, co.uk o gov.uk es rechazado, 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 son rechazados.
• Usa la forma xn-- (Punycode) para nombres de dominio internacionalizados; un dominio que contiene caracteres no ASCII es rechazado.
• 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 son rechazados. 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 violaciones de formato y 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 incumple 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 nuevamente 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 durante la sesión

En una sesión multiagente, cada lista de dominios que aplica a un hilo se aplica al mismo tiempo: un agente en el roster 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 del roster puede reducir lo que una herramienta alcanza pero nunca ampliarlo. Por ejemplo, un agente del roster que establece blocked_domains conserva los allowed_domains del coordinador y bloquea esos hosts dentro de ellos, y un agente del roster que establece sus propios allowed_domains solo puede acceder a los hosts que cubren tanto su lista como la del coordinador.
• Si las listas de permitidos combinadas no tienen ningún dominio en común, la herramienta permanece 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 del roster 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 herramienta 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 roster {"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 del roster permanecen como las estableció su definición de agente cuando se creó la sesión.



Diferencias con las herramientas de la API de Messages

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

• Cada lista tiene un límite de 64 dominios.
• Los dominios listados para web_fetch no pueden incluir una ruta.
• 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 API de Messages.

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 < agent.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

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 para 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, añade un prefijo a los nombres con el recurso (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 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 dificultan que Claude extraiga lo que importa.



Próximos pasos