Restringir los dominios de búsqueda web y obtención web

Para controlar qué sitios pueden alcanzar las herramientas web del agente, establece una lista de dominios en las entradas web_search y web_fetch del conjunto de herramientas del agente. Cada una de estas entradas de configs acepta una de dos listas:

• allowed_domains: La herramienta solo puede alcanzar estos hosts.
• blocked_domains: La herramienta nunca puede alcanzar estos hosts.

Cada herramienta tiene su propia lista, por lo que web_search y web_fetch pueden tener restricciones diferentes.

Establecer listas de dominios en un agente

El siguiente ejemplo crea un agente que limita web_search a dos sitios y bloquea un host para web_fetch. También establece user_location y max_content_tokens, que se describen en Configuración. Luego, el ejemplo imprime el arreglo 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 un entorno en la nube con redes limited, los allowed_hosts del entorno también se aplican a web_search y web_fetch. La creación de una sesión falla con un error 400 cuando los allowed_domains de una herramienta web habilitada tienen una entrada que no está dentro de allowed_hosts. Lo mismo ocurre con una actualización de sesión que agrega una entrada así. Para solucionarlo, agrega el host a allowed_hosts o elimina la entrada de allowed_domains. En tiempo de ejecución, una llamada a web_fetch para una URL en un host que no coincide con allowed_hosts devuelve un resultado de error url_not_allowed. web_search omite los resultados de esos hosts. Las dos listas coinciden de forma diferente: la entrada de una herramienta cubre sus subdominios, pero una entrada de allowed_hosts coincide con un único host exacto a menos que comience con *.. Por ejemplo, la entrada de herramienta docs.example.com no está dentro de unos allowed_hosts con el valor ["example.com"], pero sí está dentro de ["docs.example.com"] o ["*.example.com"].

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.

Configuración

Además de enabled y permission_policy, las entradas de herramientas web aceptan la siguiente configuración:

Para saber cómo los SDK tipan estas entradas, consulta Tipos de entradas de configuración en los SDK.

Cuando un dominio no está permitido

web_search omite los resultados que su lista de dominios no permite. Una llamada a web_fetch para una URL que su lista de dominios no permite devuelve un resultado de error al agente. El evento agent.tool_result tiene is_error: true, y su contenido indica el código de error url_not_allowed.

Reglas de las listas de dominios

Estas reglas se aplican por igual a allowed_domains y blocked_domains. Una solicitud que incumple alguna se rechaza, como se describe en Errores de validación.

• Una lista por entrada: Establece allowed_domains o blocked_domains en una entrada, no ambas.
• Tamaño de la lista: Cada lista contiene de 1 a 64 dominios, cada uno de 1 a 255 caracteres.
• Sin listas vacías: Para no aplicar ninguna restricción, omite el campo o envía null.
• Sin duplicados: Un dominio solo puede aparecer una vez en una lista. www.example.com y example.com cuentan como dominios diferentes.

Con qué coincide un dominio listado

Un dominio listado coincide con ese host y con todos 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.

Los nombres de host se comparan sin distinguir entre mayúsculas y minúsculas.

Formato de dominio

Cada dominio es un nombre de dominio registrable, o un subdominio de uno, escrito como un nombre de host simple. Puede contener letras ASCII, dígitos, guiones, guiones bajos y puntos. Se ignora una única / final.

Un dominio también se rechaza si contiene credenciales o espacios en blanco, o si una de sus etiquetas comienza o termina con un guion. localhost y los hosts que terminan en .localhost, .local, .internal, .localdomain o .invalid también se rechazan.

Sufijos de ruta en dominios de búsqueda web

Un dominio de web_search puede llevar un sufijo de ruta, como example.com/blog. La ruta no puede contener espacios, ?, # ni ninguno de los caracteres $ , | ^ !.

Prefiere nombres de host simples también para web_search. El proveedor de búsqueda compara los sufijos de ruta como patrones de URL en lugar de como reglas estrictas de host.

Errores de validación

La API valida esta configuración cuando creas un agente o actualizas un agente. También la valida cuando creas o actualizas una sesión que proporciona tools.

Las infracciones de formato y de límites se rechazan con un error 400 invalid_request_error:

En las mismas solicitudes, la API también rechaza 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.
• Un user_location.timezone que no es un nombre IANA válido.

En un entorno en la nube con redes limited, la creación y actualización de sesiones también comprueban allowed_domains frente a los allowed_hosts del entorno. Consulta la regla en Establecer listas de dominios en un agente.

Cuando una configuración aceptada deja de ser válida

La sesión vuelve a comprobar la configuración cuando inicializa la herramienta por primera vez. Si una configuración que se aceptó antes ya no es válida en ese momento, la sesión emite un evento session.error. Luego vuelve a idle sin reintentar.

Para continuar la sesión:

1. Corrige la configuración actualizando las herramientas de la sesión.
2. Actualiza también el agente, para que las nuevas sesiones comiencen con la configuración corregida.
3. Envía un nuevo user.message.

Sesiones multiagente y orientadas a resultados

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 tres conjuntos de listas:

• Sus propios allowed_domains y blocked_domains
• Los de cualquier agente que lo haya llamado
• Las listas actuales del coordinador

La configuración se combina de la siguiente manera:

Por lo tanto, un agente de la lista puede restringir lo que alcanza una herramienta, pero nunca ampliarlo:

• Un agente de la lista que establece blocked_domains conserva los allowed_domains del coordinador y bloquea esos hosts dentro de ellos.
• Un agente de la lista que establece sus propios allowed_domains solo puede alcanzar los hosts que cubren tanto su lista como la del coordinador.

Una entrada de lista {"type": "self"} no tiene configuración web propia y sigue la configuración actual del coordinador.

Si las listas allowed_domains combinadas no tienen ningún dominio en común, la herramienta sigue disponible para ese agente, pero todas las llamadas fallan. Cada llamada devuelve un error url_not_allowed que indica que no se permite ningún dominio. La descripción de la herramienta le indica lo mismo al modelo. Para evitarlo, mantén los allowed_domains de cada agente de la lista dentro de los del coordinador.

El evaluador en las sesiones orientadas a resultados se ejecuta sin web_search ni web_fetch, independientemente de esta configuración.

Cambiar las listas a mitad de sesión

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 aplica las nuevas listas a partir de su siguiente turno. La actualización no cambia las listas propias de un agente de la lista. Esas se mantienen tal como las estableció la definición del agente cuando se creó la sesión.

Diferencias con las herramientas de la Messages API

Esta configuración usa los mismos campos allowed_domains y blocked_domains que el filtrado de dominios en las herramientas de servidor de la Messages API. Managed Agents difiere en cuatro aspectos:

• Cada lista está limitada a 64 dominios.
• Los dominios listados para web_fetch no pueden incluir una ruta.
• Los dominios deben ser ASCII. 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.

Próximos pasos