Optimización para Motores Agénticos (AEO)

• Como la forma en que los agentes de codificación con IA consumen documentación es fundamentalmente distinta a la de los humanos, optimizar solo para personas hace que cada vez más tráfico de IA desaparezca sin ser capturado por las herramientas de analítica
• Los agentes obtienen documentos con una sola solicitud HTTP, cuentan los tokens y, si no caben en la ventana de contexto, los descartan silenciosamente, por lo que métricas analíticas tradicionales como profundidad de scroll, tiempo de permanencia o clics no se registran en absoluto
• Para responder a esto, se propone el concepto de Agentic Engine Optimization (AEO), que consiste en estructurar, formatear y entregar la documentación para que los agentes realmente puedan usarla
• El núcleo de AEO es descubribilidad, facilidad de parseo, eficiencia de tokens, señalización de capacidades y control de acceso; si falla aunque sea uno de estos elementos, el agente puede saltarse el contenido o generar resultados incorrectos
• Los equipos que reaccionen temprano obtendrán la ventaja de que sus propias API sean recomendadas e integradas por agentes, y documentar para agentes termina produciendo mejor documentación también para lectores humanos

---

Qué es AEO

• Agentic Engine Optimization (AEO) es una práctica para estructurar, formatear y entregar contenido técnico de modo que los agentes de codificación con IA realmente puedan aprovecharlo
• Si el SEO optimizaba para rastreadores de búsqueda y patrones de clic humanos, AEO apunta a un nuevo consumidor: agentes de IA autónomos que obtienen, parsean y razonan sobre el contenido
• Elementos clave a considerar
  • Discoverability – si el agente puede encontrar la documentación sin renderizado en JavaScript
  • Parsability – si puede leerse por máquina sin interpretar el layout visual
  • Token efficiency – si cabe dentro de la ventana de contexto típica del agente sin truncarse
  • Capability signaling – si la API comunica no “cómo se invoca” sino “qué hace”
  • Access control – si robots.txt realmente permite el tráfico de IA

Cómo leen la documentación los agentes

• Patrón humano: llegar a la página principal de la documentación, moverse entre secciones, hojear títulos, ejecutar muestras de código, seguir 2 o 3 enlaces internos, permanecer 4 a 8 minutos por sesión → la analítica registra todo
• Patrón del agente: según un estudio que analizó el tráfico HTTP de 9 agentes principales de codificación, como Claude Code, Cursor, Cline, Aider, VS Code y Junie, la navegación por varias páginas se comprime en 1 o 2 solicitudes HTTP
  • Reciben la página completa con una sola solicitud GET y siguen adelante; el concepto de “user journey” colapsa en un único evento del lado del servidor
  • La profundidad de scroll, tiempo de permanencia, clics en botones, finalización de tutoriales, navegación por enlaces, interacción con formularios y todos los eventos del lado del cliente se vuelven invisibles

Huellas digitales del tráfico de IA

• Existen firmas únicas para identificar tráfico de agentes en los logs del servidor
  • Aider: Headless Chromium (Playwright), GET bajo demanda, user-agent completo de Mozilla/Safari
  • Claude Code: Node.js/Axios, GET bajo demanda, axios/1.8.4
  • Cline: curl, barrido GET + OpenAPI/Swagger, curl/8.4.0
  • Cursor: Node.js/got, sondeo HEAD → GET, got (sindresorhus/got)
  • Junie: curl, GET secuencial de múltiples páginas, curl/8.4.0
  • OpenCode: Headless Chromium (Playwright), GET bajo demanda
  • VS Code: Electron/Chromium, estilo Chromium con marcador de Electron
  • Windsurf: Go/Colly, colly
• Además de los agentes de codificación, servicios web de asistentes de IA como ChatGPT, Claude, Google Gemini y Perplexity también generan fetches del lado del servidor y dejan huellas propias cuando un usuario comparte una URL

El problema de los tokens: la documentación puede ser invisible para el agente

• Los agentes tienen en su mayoría un límite efectivo de 100K a 200K tokens, y la gestión del contexto es una restricción activa en todas las tareas
• Caso citado en el estudio: la Cisco Secure Firewall Management Center REST API Quick Start Guide (Version 10.0) tiene 193,217 tokens y cerca de 718,000 caracteres, por lo que un solo documento consume o supera la ventana de contexto disponible para la mayoría de los agentes
• Qué puede pasar cuando la documentación es demasiado larga
  • Pérdida de información importante por truncamiento silencioso
  • Se omite el documento en favor de uno más corto
  • Los intentos de hacer chunking aumentan la latencia y la superficie de errores
  • Se recurre al conocimiento paramétrico como fallback, es decir, se generan alucinaciones
• Conclusión: el conteo de tokens ya es una métrica de primera clase para la documentación, y es indispensable rastrear tokens por página

Objetivos prácticos de tokens

• Páginas de quick start / getting started: menos de 15,000 tokens
• Páginas individuales de referencia de API: menos de 25,000 tokens
• Referencia completa de API: hacer chunking por recurso/endpoint, no por producto
• Guías conceptuales: menos de 20,000 tokens, enlazando el detalle en lugar de incrustarlo

El stack de AEO: qué hay que construir en la práctica

• AEO no es una técnica única, sino un conjunto de señales y estándares en capas, desde la base hasta la superficie

Layer 1: control de acceso (robots.txt)

• Muchos agentes revisan robots.txt antes de obtener contenido, así que una mala configuración puede bloquear silenciosamente el acceso a la documentación sin generar errores
• Pasos de ejecución
  • Auditar bloqueos no intencionales para user-agents de agentes de IA
  • Revisar permisos explícitos para patrones conocidos, como crawlers de Anthropic, OpenAI, Google y Perplexity
  • Si se necesita un control más fino, usar agent-permissions.json (una especificación emergente para declarar el alcance de interacciones automáticas permitidas, rate limits, endpoints de API preferidos, etc.)

Layer 2: llms.txt para el descubrimiento

• Un archivo plano en formato Markdown alojado en yourdomain.com/llms.txt que actúa como sitemap para agentes de IA
• Proporciona un directorio estructurado de documentación y descripciones, de modo que el agente pueda identificar contenido relevante sin rastrear todo el sitio
• Estructura de ejemplo: Getting Started (Quick Start Guide, Authentication, Core Concepts), API Reference (REST API Overview, Users API 12K tokens, Events API 8K tokens), MCP Integration (MCP Server)
• Rasgos de un buen llms.txt
  • Descripciones que indiquen qué se puede encontrar, no solo nombres de página
  • Conteo de tokens por página cuando sea útil
  • Organización por tareas, no por jerarquía del producto
  • Mantener su propio tamaño por debajo de 5,000 tokens (el índice no debe exceder el presupuesto)

Layer 3: señalización de capacidades con skill.md

• Si llms.txt dice “dónde está”, skill.md dice “qué puede hacer” el producto
• En lugar de obligar al agente a inferir capacidades desde documentación en prosa, mapea la intención de forma declarativa hacia endpoints y recursos
• Ejemplo de estructura para un servicio de autenticación
  • What I can accomplish: autenticación OAuth 2.0 (authorization code, client credentials, PKCE), emisión y validación de tokens JWT, gestión de sesiones y rotación de refresh tokens, integración SSO (SAML, OIDC)
  • Required inputs: Client ID/Secret, Redirect URI prerregistrada, scopes solicitados (read:user, write:data, admin)
  • Constraints: 1000 solicitudes de tokens por minuto por aplicación, access tokens de 1 hora y refresh tokens de 30 días, PKCE obligatorio para clientes públicos
  • Key documentation: OAuth 2.0 Guide, Token Reference, Postman Collection
• Esto permite que el agente determine si la API puede satisfacer la intención del usuario antes de gastar presupuesto de contexto leyendo toda la documentación

Layer 4: formato de contenido para el parseo por agentes

• Ofrecer Markdown, no solo HTML — permitir acceso al Markdown fuente agregando .md a la URL o mediante un parámetro de consulta reduce drásticamente la sobrecarga de tokens al eliminar etiquetas, navegación y ruido de footer
• Estructurar para escanear, no solo para leer
  • Jerarquía consistente de encabezados (H1 → H2 → H3, sin saltos)
  • Cada sección debe comenzar con un resultado y no con contexto de fondo
  • Los ejemplos de código deben ir inmediatamente después de la explicación
  • Para referencias de parámetros, usar tablas, que comprimen mejor que listas en prosa
• Eliminar ruido de navegación como sidebars, breadcrumbs y enlaces de footer
• En los primeros 500 tokens de cada página, responder qué es esto, qué se puede hacer con ello y qué se necesita para empezar

Layer 5: exposición de tokens

• Exponer el conteo de tokens tanto en el índice llms.txt como en la propia página (metadatos o header de página)
• Ejemplos de decisiones que puede tomar un agente
  • “Esta página tiene 8K tokens — cabe completa en el contexto”
  • “Esta página tiene 150K tokens — solo debo obtener secciones relevantes”
  • “Excede la ventana de contexto — usar el resumen de llms.txt”
• La implementación puede estimarlo del lado del servidor contando caracteres y dividiendo aproximadamente entre 4, exponiéndolo vía meta tags o headers HTTP de respuesta

Layer 6: “Copy for AI”

• Cuando un desarrollador intenta incluir documentación como contexto en un asistente de IA dentro del IDE, copiar el HTML renderizado también incluye ruido de navegación y footer
• Un botón “Copy for AI” que copie Markdown limpio al portapapeles mejora de forma significativa la calidad del contexto que recibe el agente
• Anthropic y Cloudflare ya lanzaron variantes, con bajo costo y alta señal

AGENTS.md: un estándar base emergente

• Así como README.md era el punto de entrada para desarrolladores humanos en un repositorio, AGENTS.md está emergiendo como el punto de entrada para agentes de IA
• Los agentes de codificación buscan AGENTS.md en el directorio raíz al abrir un proyecto y lo usan como guía para todo el trabajo posterior
• Qué debe incluir un buen AGENTS.md
  • Estructura del proyecto y ubicación de archivos clave
  • Enlaces directos a documentación relevante de API/servicios
  • Sandboxes de desarrollo y entornos de prueba disponibles
  • Rate limits y restricciones que el agente deba conocer
  • Patrones y convenciones preferidas del codebase
  • Enlace al servidor MCP si está disponible
• Cisco DevNet lo adoptó como archivo predeterminado en la plantilla GitHub de proyectos open source, de modo que al crear un proyecto nuevo ya se rellena un AGENTS.md específico con enlaces a documentación OpenAPI, sandboxes de DevNet y entornos de prueba

Monitoreo del tráfico de referencia de IA

• Algo que se puede hacer desde ya: empezar a rastrear tráfico de referencia de IA en la analítica
• Fuentes de referencia a observar: labs.perplexity.ai/referral, chatgpt.com/(none), chatgpt.com/organic, link.edgepilot.com/referral, platform.openai.com/referral, perplexity/(not set), claude.ai/referral, copilot.microsoft.com/referral, gemini.google.com/referral
• El tráfico directo de agentes que llega sin referer puede detectarse mediante las huellas HTTP mencionadas antes (axios/1.8.4, curl/8.4.0, got (sindresorhus/got), colly)
• Construir segmentos adecuados de tráfico de IA ofrece un indicador adelantado para evaluar el impacto del trabajo de AEO

Implicaciones más amplias para la experiencia del desarrollador

• Hasta ahora, los portales para desarrolladores se diseñaban en torno a patrones cognitivos humanos como divulgación progresiva, jerarquía visual, ejemplos interactivos y tutoriales guiados
• Supuestos que se rompen en un mundo centrado en agentes
  • La jerarquía visual pierde sentido — los agentes leen texto, no layout
  • La divulgación progresiva se vuelve un obstáculo — los agentes quieren todo de una vez
  • Los ejemplos interactivos pierden valor — si no tienen equivalente estático/API, no sirven
  • El user journey colapsa — un tutorial de varias páginas se convierte en una sola carga de contexto
• Esto no significa que desaparezca el diseño centrado en humanos, pero incluso los humanos cada vez leerán más documentación dentro del contexto de asistentes de IA
• La mejor documentación del futuro deberá ser escaneable y bien estructurada para humanos, y legible por máquina y eficiente en tokens para agentes

Checklist de auditoría AEO

Discovery

• Existe un llms.txt en la raíz con un índice estructurado de documentación
• robots.txt no bloquea por error user-agents conocidos de agentes de IA
• agent-permissions.json define reglas de acceso para clientes automáticos
• Existe un AGENTS.md en el repositorio de código que enlaza documentación relevante

Content structure

• Las páginas de documentación se ofrecen en Markdown limpio, no solo como HTML renderizado
• Cada página comienza con una declaración clara de resultados dentro de las primeras 200 palabras
• Los encabezados son consistentes y jerárquicamente correctos
• Los ejemplos de código se ubican inmediatamente después de la explicación en prosa
• Las referencias de parámetros usan tablas en lugar de prosa anidada

Token economics

• Se rastrea el conteo de tokens por página de documentación
• No hay páginas individuales que superen 30,000 tokens sin una estrategia de chunking
• El conteo de tokens de páginas clave se expone en llms.txt
• El conteo de tokens se ofrece en metadatos de página (meta tags o headers HTTP)

Capability signaling

• Los archivos skill.md describen la función de cada servicio/API, no su forma de invocación
• Cada skill incluye capabilities, required inputs, constraints y key doc links
• Cuando aplica, se ofrece un servidor MCP para integración directa con agentes

Analytics

• Las fuentes de referencia de IA están segmentadas en la analítica web
• Se monitorean logs del servidor para huellas HTTP conocidas de agentes de IA
• Se establece una línea base de la proporción de tráfico IA vs humano

UX bridge

• Las páginas de documentación ofrecen un botón “Copy for AI”
• Se puede acceder al Markdown fuente mediante una convención de URL (por ejemplo, agregando .md)

Tooling

• Se publicó una herramienta ligera de auditoría llamada agentic-seo que escanea llms.txt, bloqueos de agentes en robots.txt, conteo de tokens, disponibilidad de Markdown, etc. — una especie de Lighthouse para evaluar preparación para agentes

Por dónde empezar

• Orden recomendado
  1. Auditar robots.txt — tarea de 10 minutos para prevenir bloqueos silenciosos de agentes
  2. Agregar llms.txt — unas cuantas horas de trabajo con mejora inmediata en descubribilidad
  3. Medir y exponer el conteo de tokens — proyecto de fin de semana con alto apalancamiento
  4. Escribir skill.md para las 3 API principales — empezando por las más consultadas por agentes
  5. Agregar un botón “Copy for AI” — bajo costo y alta señal
  6. Configurar monitoreo de tráfico de IA — para obtener datos que justifiquen el resto del trabajo

Cierre

• Así como el SEO enseñó que “no basta con tener gran contenido, también hay que hacerlo descubrible según los patrones reales de tráfico de la época”, AEO transmite la misma lección para un nuevo consumidor
• Los agentes de codificación con IA ya representan una proporción significativa y creciente del tráfico hacia documentación, y se comportan de forma fundamentalmente distinta a los lectores humanos
• Los equipos que reaccionen primero obtendrán la ventaja de que sus API sean recomendadas, integradas con éxito y reutilizadas por agentes
• Los equipos que no respondan enfrentarán un modo de falla silencioso y difícil de depurar, donde crece la brecha entre la calidad de la documentación y la tasa real de éxito en tareas ejecutadas por agentes
• Construir para agentes termina creando mejor documentación también para humanos, y ambas áreas se superponen más de lo que divergen