ai_agents forma parte de los ajustes de borde de una zona (GET/PATCH /v1/orgs/{org}/zones/{zone}/edge) y de los de cada nombre (hosts.<nombre>.ai_agents). Los ajustes se validan aunque el control de rastreadores IA esté desactivado.
| Campo | Por defecto | Valores |
|---|---|---|
enabled | false | Clasificar las peticiones y aplicar la política. |
mode | log | log (contar lo que pasaría) o enforce. |
spoofed_challenge | log | enforce: solo los rastreadores verificados se saltan el reto de navegador. log: mantener la exención por User-Agent y registrarla. Independiente de mode. |
policy.<clave> | consulta los valores por defecto | allow, log, challenge, block o tarpit para ai_training, ai_search, ai_user_agent, search_engine, unverified_automation, spoofed, unverified_bot, trap_hit, secret_probe, robots_violation, agent_burst. |
template | — | Solo escritura: search_ok_block_training, verified_only o block_unverified_automation. Sustituye la política entera. |
bot_overrides | [] | Hasta 100 {"bot_id", "action"}. |
trap.enabled | false | Insertar el enlace señuelo. |
tarpit.enabled | false | Permitir la acción tarpit. |
robots.enabled | false | Anteponer la sección gestionada a robots.txt. |
robots.content_signals.search | yes | yes, no o "" (sin indicar). |
robots.content_signals.ai_input | yes | yes, no o "". |
robots.content_signals.ai_train | no | yes, no o "". |
markdown.enabled | false | Markdown para agentes. |
block_response.status | 403 | 401, 402, 403, 404, 410, 429, 451 o 503. |
block_response.message | "" | Texto plano de hasta 1024 bytes; "" = la página de bloqueo del sitio. |
endpoints | [] | Hasta 20 endpoints de IA. Los endpoints con kind: "mcp" son de MCP Shield. |
Respuesta de bloqueo
Una petición bloqueada recibe block_response.status. Con message, el cuerpo es ese texto (text/plain); con 429 o 503, la respuesta lleva además Retry-After: 3600. Sin mensaje, se usa la página de bloqueo del sitio con ese estado.
Cómo lo cambia un PATCH
ai_agents en un PATCH …/edge es un JSON merge patch (RFC 7396):
- los objetos se mezclan campo a campo, y la política clave a clave;
- las listas (
bot_overrides,endpoints) se sustituyen enteras; - un campo a
nullvuelve a su valor por defecto;"ai_agents": nullrestaura todos los valores por defecto; templatefija primero la política entera de la plantilla; las claves depolicydel mismo patch se aplican encima.
{"ai_agents": {"enabled": true, "mode": "enforce", "template": "search_ok_block_training"}}Por nombre
hosts.<nombre>.ai_agents sustituye entera la configuración de la zona para ese nombre. El primer cambio en ai_agents de un nombre parte de una copia de la de la zona, así que los campos que no das conservan los valores de la zona. A partir de ahí, los cambios posteriores de la zona ya no llegan al nombre. Para volver a seguir a la zona, quítala: {"hosts": {"shop.example.com": {"ai_agents": null}}} (Volver a usar la del dominio en el panel).
Atajos de la CLI
| Argumento | Efecto |
|---|---|
ai_agents.enabled=true | Cualquier campo por su ruta con puntos. |
ai_agents.template=verified_only | Se comprueba antes de llamar a la API. |
ai_agents.bot_overrides=gptbot:block,ccbot:allow | Pares bot:acción; "" = ninguno. |
ai_agents.endpoints:='[…]' | Valor JSON. |
--host shop.example.com | Los ajustes propios del nombre. |