Restringir los dominios de búsqueda web y obtención web
Controla qué sitios pueden alcanzar las herramientas de búsqueda web y obtención web de un agente, limita el contenido obtenido y localiza los resultados de búsqueda.
El uso varía según el producto
allowed_domains o blocked_domains en la herramienta web_search o web_fetch de la solicitud.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.
La configuración de búsqueda web de tu organización en la página Capacidades de la Claude Console también se aplica a web_search en una sesión. Si un administrador deshabilita la búsqueda web, las llamadas a web_search devuelven un resultado de error al agente y la sesión continúa. Si la organización restringe los dominios de búsqueda web, el agente recibe solo los resultados de búsqueda que permiten tanto las restricciones de dominio de la organización como las listas por herramienta del agente.
La configuración de obtención web de tu organización en la misma página también se aplica a web_fetch en una sesión. Si un administrador desactiva la obtención web, las llamadas a web_fetch devuelven un resultado de error al agente y la sesión continúa. Si la organización establece dominios permitidos o bloqueados para la obtención web, una URL debe superar la lista de la organización y las listas por herramienta del agente, y lo mismo debe hacer cualquier URL a la que conduzca una redirección. Una llamada a web_fetch para una URL que cualquiera de ellas excluya también devuelve un resultado de error al agente.
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. Configuración describe ambos.
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
---ant apply crea el agente e imprime su ID.
En un entorno en la nube con redes limited, el allowed_hosts del entorno también se aplica a web_search y web_fetch. La creación de una sesión falla con un error 400 cuando el allowed_domains de una herramienta web habilitada tiene 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 corregirlo, 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 con el que allowed_hosts no coincide 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 un allowed_hosts de ["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 Herramientas integradas en el formulario del agente. Establece max_content_tokens y user_location en la vista Sin procesar 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:
| Configuración | Se aplica a | Descripción |
|---|---|---|
allowed_domains | web_search, web_fetch | Los únicos hosts que la herramienta puede alcanzar. Consulta Reglas de las listas de dominios. |
blocked_domains | web_search, web_fetch | Hosts que la herramienta no puede alcanzar. Consulta Reglas de las listas de dominios. |
max_content_tokens | web_fetch | Limita la cantidad de contenido de página obtenido que se incluye en el contexto. Debe ser un entero positivo. Consulta límites de contenido. |
user_location | web_search | Localiza los resultados de búsqueda. Un objeto con los mismos campos que el parámetro user_location de la Messages API. |
Para conocer los tipos que usa el SDK para 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. La API rechaza una solicitud que incumple alguna de estas reglas, como se describe en Errores de validación.
- Como máximo una lista por entrada: Establece
allowed_domainsoblocked_domainsen 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.comyexample.comcuentan 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 de web_search también puede incluir una ruta, como se describe en Sufijos de ruta en dominios de búsqueda web.
| No aceptado | Ejemplo | Usa en su lugar |
|---|---|---|
| Un esquema | https://example.com | example.com |
| Un puerto | example.com:443 | example.com |
| Un comodín | *.example.com | example.com |
Una ruta en un dominio de web_fetch | example.com/* | example.com |
| Una dirección IP en cualquier forma, ya sea IPv4, IPv6, entre corchetes o abreviatura numérica | 127.1 | El nombre de dominio del sitio |
| Un dominio de nivel superior por sí solo o un sufijo de registro | com, co.uk, gov.uk | Un dominio completo como example.co.uk |
| Un nombre de una sola etiqueta | intranet | Un dominio completo como example.co.uk |
| Caracteres no ASCII, como en un nombre de dominio internacionalizado | La forma xn-- (Punycode) |
La API también rechaza un dominio que contiene credenciales o espacios en blanco, o que tiene una etiqueta que comienza o termina con un guion. También rechaza localhost y los hosts que terminan en .localhost, .local, .internal, .localdomain o .invalid.
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.
La API rechaza las infracciones de formato y de límites con un error 400 invalid_request_error:
| Infracción | Mensaje de error |
|---|---|
| Una entrada establece ambas listas. | Incluye Only one of allowed_domains or blocked_domains may be set. |
| Una lista está vacía. | Incluye allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null. |
| Un dominio incumple una regla de formato. | Indica la lista del dominio y su posición basada en cero, como en allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com" |
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_domainsal que el rastreador de Anthropic no tiene permitido acceder. - Un
user_location.countryque el proveedor de búsqueda no admite. El mensaje termina enuser_location.country: not a country the search provider supports. - Un
user_location.timezoneque no es un nombre de zona horaria 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 al 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:
- 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.
- 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 enumerado en la lista predefined_agents de subagents está sujeto a tres conjuntos de listas por herramienta:
- Sus propios
allowed_domainsyblocked_domains - Los de cualquier agente que lo haya llamado
- Las listas actuales del agente que la sesión ejecuta
La configuración se combina de la siguiente manera:
| Configuración | Cómo se combina |
|---|---|
allowed_domains | La herramienta puede alcanzar un host solo si todas las listas lo cubren. |
blocked_domains | Las listas se suman. |
max_content_tokens, user_location | No se combinan. Un hilo usa el valor de su propia configuración de herramientas si está establecido. De lo contrario, usa el valor del agente que lo llamó y, si no, la configuración actual del agente de la sesión. |
Por lo tanto, un agente enumerado puede restringir lo que alcanza una herramienta, pero nunca ampliarlo:
- Un agente enumerado que establece
blocked_domainsconserva losallowed_domainsdel agente de la sesión y bloquea esos hosts dentro de ellos. - Un agente enumerado que establece sus propios
allowed_domainssolo puede alcanzar los hosts que cubren tanto su lista como la lista del agente de la sesión.
Una entrada {"type": "self"} en la lista predefined_agents de subagents no tiene configuración web propia y sigue la configuración actual del agente de la sesión.
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 cuyo texto incluye no domain is permitted. La descripción de la herramienta le indica lo mismo al modelo. Para evitarlo, mantén los allowed_domains de cada agente enumerado dentro de los allowed_domains del agente de la sesión.
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. Para un agente enumerado en la lista predefined_agents de subagents, la actualización no cambia las listas propias del agente. Estas 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_fetchno pueden incluir una ruta. - Los dominios deben ser ASCII. La Messages API acepta entradas Unicode, aunque recomienda no usarlas.
max_uses,citationsycache_controlno están disponibles en el conjunto de herramientas.
Próximos pasos
Consulta las herramientas integradas, habilítalas o deshabilítalas y define herramientas personalizadas.
Controla cuándo se ejecutan las herramientas del agente y de MCP.
Controla el acceso de red saliente propio del sandbox.
Coordina varios agentes dentro de una sola sesión.
Disponibilidad
Claude API
- API
- Messages API
- Managed Agents Beta requiere
- Modelos
- Todos los modelos
Claude Platform on AWS
- Estado
- Beta
- API
- Managed Agents
- Encabezado beta
- Requiere
- Modelos
- Todos los modelos
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents Beta requiere
- Modelos
- Todos los modelos
¿Te resultó útil esta página?