# Referencia de ajustes del control de rastreadores IA

> Cada campo del ajuste de borde ai_agents, su valor por defecto y cómo lo cambian un merge patch, una plantilla y los ajustes por nombre.

`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](https://developers.openwaf.dev/es/waf/browser-challenge/). `log`: mantener la exención por User-Agent y registrarla. Independiente de `mode`. |
| `policy.<clave>` | consulta los [valores por defecto](https://developers.openwaf.dev/es/ai-crawl-control/policy/#defaults) | `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](https://developers.openwaf.dev/es/ai-crawl-control/trap-and-tarpit/#trap). |
| `tarpit.enabled` | `false` | Permitir la acción `tarpit`. |
| `robots.enabled` | `false` | Anteponer la sección gestionada a [robots.txt](https://developers.openwaf.dev/es/ai-crawl-control/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](https://developers.openwaf.dev/es/ai-crawl-control/markdown-for-agents/). |
| `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](https://developers.openwaf.dev/es/waf/block-page/) del sitio. |
| `endpoints` | `[]` | Hasta 20 [endpoints de IA](https://developers.openwaf.dev/es/ai-crawl-control/ai-endpoints/#fields). Los endpoints con `kind: "mcp"` son de [MCP Shield](https://developers.openwaf.dev/es/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 `null` vuelve a su valor por defecto; `"ai_agents": null` restaura todos los valores por defecto;
- `template` fija primero la política entera de la plantilla; las claves de `policy` del mismo patch se aplican encima.

```json
{"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. |