Otimização para Motores Agênticos (AEO)

• Como a forma como agentes de programação com IA consomem documentação é fundamentalmente diferente da de humanos, otimizar só para pessoas faz com que uma parcela cada vez maior do tráfego de IA desapareça sem ser capturada pelas ferramentas de análise
• Os agentes buscam documentos com uma única requisição HTTP, contam os tokens e, se o conteúdo não couber na janela de contexto, o descartam silenciosamente; por isso, métricas analíticas tradicionais como profundidade de rolagem, tempo na página e cliques simplesmente não são registradas
• Para responder a isso, propõe-se o conceito de Agentic Engine Optimization (AEO), que consiste em estruturar, formatar e disponibilizar documentos para que agentes realmente consigam usá-los
• O núcleo do AEO é descoberta, facilidade de parsing, eficiência de tokens, sinalização de capacidades e controle de acesso; se qualquer um desses pontos falhar, o agente pode ignorar o conteúdo ou gerar saídas incorretas
• Equipes que agirem cedo garantem a vantagem de ter suas APIs recomendadas e integradas por agentes, e documentar para agentes acaba produzindo documentação melhor também para leitores humanos

---

O que é AEO

• Agentic Engine Optimization (AEO) é a prática de estruturar, formatar e disponibilizar conteúdo técnico para que agentes de programação com IA realmente consigam utilizá-lo
• Se SEO era otimização voltada para crawlers de busca e padrões de clique humanos, AEO tem como alvo um novo consumidor: agentes de IA autônomos que buscam, fazem parsing e raciocinam sobre conteúdo
• Fatores centrais a considerar
  • Discoverability – o agente consegue encontrar a documentação sem renderização em JavaScript?
  • Parsability – o conteúdo é legível por máquina sem depender da interpretação de layout visual?
  • Token efficiency – cabe na janela de contexto típica do agente sem ser truncado?
  • Capability signaling – a API comunica o que faz, e não apenas como chamar?
  • Access control – o robots.txt realmente permite tráfego de IA?

Como agentes leem documentação

• Padrão humano: a pessoa chega à home da documentação, navega entre seções, passa os olhos pelos títulos, executa exemplos de código, segue 2 ou 3 links internos, permanece de 4 a 8 minutos por sessão → as ferramentas analíticas registram tudo
• Padrão do agente: segundo um artigo que analisou o tráfego HTTP de 9 agentes de programação importantes, incluindo Claude Code, Cursor, Cline, Aider, VS Code e Junie, a navegação por várias páginas é comprimida em 1 ou 2 requisições HTTP
  • Recebe a página inteira com uma única requisição GET e segue adiante; o conceito de “jornada do usuário” colapsa em um único evento no lado do servidor
  • Profundidade de rolagem, tempo na página, cliques em botões, conclusão de tutoriais, navegação por links, interações com formulários e todos os eventos client-side ficam invisíveis

Fingerprints do tráfego de IA

• Existem assinaturas específicas que permitem identificar tráfego de agentes nos logs do servidor
  • Aider: Headless Chromium (Playwright), GET sob demanda, user-agent completo Mozilla/Safari
  • Claude Code: Node.js/Axios, GET sob demanda, axios/1.8.4
  • Cline: curl, varredura GET + OpenAPI/Swagger, curl/8.4.0
  • Cursor: Node.js/got, sondagem HEAD → GET, got (sindresorhus/got)
  • Junie: curl, GET sequencial de múltiplas páginas, curl/8.4.0
  • OpenCode: Headless Chromium (Playwright), GET sob demanda
  • VS Code: Electron/Chromium, estilo Chromium com marcador Electron
  • Windsurf: Go/Colly, colly
• Além dos agentes de programação, serviços web de assistentes de IA como ChatGPT, Claude, Google Gemini e Perplexity também fazem fetch server-side quando o usuário compartilha uma URL, gerando fingerprints próprios

O problema dos tokens: a documentação pode ficar invisível para o agente

• Os agentes têm, em sua maioria, um limite prático de 100K a 200K tokens, e o gerenciamento de contexto é uma restrição ativa em qualquer tarefa
• Caso citado no artigo: o Cisco Secure Firewall Management Center REST API Quick Start Guide (Version 10.0) tem 193.217 tokens, cerca de 718.000 caracteres, o que por si só já consome ou ultrapassa a janela de contexto disponível da maioria dos agentes
• Quando a documentação é longa demais, pode acontecer o seguinte
  • Perda silenciosa de informações importantes por truncamento
  • O agente pular o documento e preferir outro mais curto
  • Tentativas de chunking aumentarem latência e superfície de erro
  • Fallback para conhecimento paramétrico — ou seja, alucinação
• Conclusão: contagem de tokens agora é uma métrica de primeira classe da documentação, e rastrear tokens por página passa a ser essencial

Metas práticas de tokens

• Páginas de quick start / getting started: menos de 15.000 tokens
• Páginas individuais de referência de API: menos de 25.000 tokens
• Referência completa da API: fazer chunking por recurso/endpoint, não por produto
• Guias conceituais: menos de 20.000 tokens, com detalhes ligados por link em vez de embutidos

A stack de AEO: o que realmente precisa ser construído

• AEO não é uma técnica única, mas um conjunto de sinais e padrões em camadas, da base até a superfície

Layer 1: controle de acesso (robots.txt)

• Muitos agentes verificam primeiro o robots.txt antes de buscar conteúdo; uma configuração errada pode bloquear silenciosamente o acesso à documentação sem gerar erro
• Etapas de execução
  • Auditar bloqueios não intencionais para user-agents de agentes de IA
  • Revisar permissões explícitas para padrões conhecidos, como crawlers da Anthropic, OpenAI, Google e Perplexity
  • Se precisar de controle mais granular, usar agent-permissions.json (uma especificação emergente para declarar faixa de interações automáticas permitidas, rate limits, endpoints de API preferidos etc.)

Layer 2: llms.txt para descoberta

• Um arquivo de texto simples em Markdown hospedado em yourdomain.com/llms.txt, que funciona como sitemap para agentes de IA
• Fornece um diretório estruturado de documentos e descrições, permitindo que o agente encontre conteúdo relevante sem rastrear o site inteiro
• Estrutura de exemplo: 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)
• Características de um bom llms.txt
  • Descrições que informam o que pode ser encontrado, não só o nome da página
  • Inclusão da contagem de tokens por página quando útil
  • Organização por tarefas, não por hierarquia de produto
  • Tamanho próprio abaixo de 5.000 tokens (o índice não pode estourar o orçamento)

Layer 3: sinalização de capacidades com skill.md

• Se o llms.txt informa “onde está”, o skill.md informa “o que o produto consegue fazer”
• Em vez de forçar o agente a inferir capacidades a partir de documentação em prosa, ele mapeia declarativamente intenções a endpoints e recursos
• Exemplo de estrutura para um serviço de autenticação
  • What I can accomplish: autenticação OAuth 2.0 (authorization code, client credentials, PKCE), emissão e validação de tokens JWT, gerenciamento de sessão e rotação de refresh tokens, integração SSO (SAML, OIDC)
  • Required inputs: Client ID/Secret, Redirect URI previamente registrada, escopos solicitados (read:user, write:data, admin)
  • Constraints: 1000 requisições de token por minuto por aplicação, access token de 1 hora e refresh token de 30 dias, PKCE obrigatório para clientes públicos
  • Key documentation: OAuth 2.0 Guide, Token Reference, Postman Collection
• Antes de gastar orçamento de contexto lendo toda a documentação, o agente consegue avaliar se a API atende à intenção do usuário

Layer 4: formato do conteúdo para parsing por agentes

• Ofereça Markdown além de HTML — permitir acesso ao Markdown original com .md na URL ou por query parameter reduz drasticamente o overhead de tokens, sem ruído de tags, navegação ou rodapé
• Estruture para escaneamento, não só para leitura
  • Hierarquia consistente de títulos (H1 → H2 → H3, sem saltos)
  • Cada seção começa com o resultado esperado, e não com contexto de fundo
  • Exemplos de código vêm logo após a explicação
  • Referências de parâmetros usam tabelas, que comprimem melhor que listas em prosa
• Remova ruído de navegação como sidebar, breadcrumb e links de rodapé
• Nos primeiros 500 tokens de cada página, responda “o que é isto, o que posso fazer com isto e do que preciso para começar”

Layer 5: exposição de tokens

• Exponha a contagem de tokens tanto no índice llms.txt quanto na própria página (via metadados ou header da página)
• Exemplos de decisões que isso permite ao agente
  • “Esta página tem 8K tokens — posso incluí-la inteira no contexto”
  • “Esta página tem 150K tokens — preciso buscar só as seções relevantes”
  • “Ultrapassa a janela de contexto — usar o resumo em llms.txt”
• A implementação pode contar caracteres no lado do servidor e estimar tokens dividindo aproximadamente por 4, expondo o valor em meta tag ou header HTTP

Layer 6: “Copy for AI”

• Quando o desenvolvedor tenta incluir documentação como contexto em um assistente de IA dentro do IDE, copiar o HTML renderizado também leva junto ruído de navegação e rodapé
• Um botão “Copy for AI” que copia Markdown limpo para a área de transferência melhora de forma significativa a qualidade do contexto recebido pelo agente
• Anthropic e Cloudflare já lançaram variações disso; é barato e tem alto sinal

AGENTS.md: o padrão básico emergente

• Assim como README.md era o ponto de entrada para desenvolvedores humanos em um repositório, AGENTS.md está emergindo como o ponto de entrada para agentes de IA
• Agentes de programação procuram AGENTS.md no diretório raiz ao abrir um projeto e usam esse arquivo como instrução para todo o trabalho posterior
• O que um bom AGENTS.md deve incluir
  • Estrutura do projeto e localização dos arquivos principais
  • Links diretos para documentação relevante de APIs/serviços
  • Sandboxes de desenvolvimento e ambientes de teste disponíveis
  • Rate limits e restrições que o agente precisa conhecer
  • Padrões e convenções preferidos do codebase
  • Link para servidor MCP, quando houver
• A Cisco DevNet adotou isso como arquivo padrão em templates de GitHub para projetos open source; ao criar um novo projeto, já vem um AGENTS.md específico com links para documentação OpenAPI, sandboxes da DevNet e ambientes de teste

Monitoramento de tráfego de referência por IA

• Algo que dá para fazer imediatamente: começar a rastrear tráfego de referência de IA nas ferramentas de analytics
• Fontes de referência 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
• O tráfego direto de agentes que chega sem referrer pode ser capturado pelos fingerprints HTTP citados antes (axios/1.8.4, curl/8.4.0, got (sindresorhus/got), colly)
• Construir segmentos adequados de tráfego de IA fornece um indicador antecedente para avaliar o efeito do trabalho de AEO

Implicações mais amplas para a experiência do desenvolvedor

• Até aqui, portais para desenvolvedores foram desenhados com foco em padrões cognitivos humanos: progressive disclosure, hierarquia visual, exemplos interativos e tutoriais guiados
• Premissas que quebram em um mundo centrado em agentes
  • Hierarquia visual perde relevância — o agente lê texto, não layout
  • Progressive disclosure vira obstáculo — o agente quer tudo de uma vez
  • Exemplos interativos perdem valor — sem equivalente estático/API, tornam-se inúteis
  • A jornada do usuário colapsa — um tutorial de várias páginas vira um único carregamento de contexto
• Isso não significa o fim do design centrado em humanos, mas os humanos também passarão cada vez mais a ler documentação dentro do contexto de assistentes de IA
• A melhor documentação do futuro deve ser escaneável e bem estruturada para humanos, legível por máquina e eficiente em tokens para agentes

Checklist de auditoria de AEO

Discovery

• Existe um llms.txt na raiz com índice estruturado da documentação
• O robots.txt não bloqueia acidentalmente user-agents conhecidos de agentes de IA
• As regras de acesso de clientes automáticos são definidas com agent-permissions.json
• Existe um AGENTS.md no repositório conectando a documentação relevante

Content structure

• As páginas de documentação são oferecidas em Markdown limpo, não apenas em HTML renderizado
• Cada página começa com uma declaração clara de resultado nas primeiras 200 palavras
• Os títulos são consistentes e hierarquicamente corretos
• Os exemplos de código aparecem logo após a explicação em prosa
• A referência de parâmetros usa tabelas, não prosa aninhada

Token economics

• A contagem de tokens é acompanhada por página
• Não existe página única acima de 30.000 tokens sem estratégia de chunking
• A contagem de tokens das páginas principais é exposta no llms.txt
• A contagem de tokens é fornecida nos metadados da página (meta tag ou HTTP header)

Capability signaling

• Arquivos skill.md descrevem as funções de cada serviço/API, não o modo de chamada
• Cada skill inclui capabilities, required inputs, constraints e key doc links
• Quando aplicável, há servidor MCP para integração direta por agentes

Analytics

• As fontes de referência de IA são segmentadas na web analytics
• Os logs do servidor são monitorados para fingerprints HTTP conhecidos de agentes de IA
• Existe uma linha de base para a proporção entre tráfego de IA e tráfego humano

UX bridge

• As páginas de documentação oferecem botão “Copy for AI”
• O Markdown original pode ser acessado por convenção de URL (por exemplo, adicionando .md)

Tooling

• Foi lançado o agentic-seo, uma ferramenta leve de auditoria que verifica llms.txt, bloqueios de agentes em robots.txt, contagem de tokens, disponibilidade de Markdown etc. — uma espécie de Lighthouse para prontidão a agentes

Por onde começar

• Ordem recomendada
  1. Auditar o robots.txt — 10 minutos de trabalho, previne bloqueios silenciosos de agentes
  2. Adicionar llms.txt — algumas horas de trabalho, melhora imediata na descoberta
  3. Medir e expor a contagem de tokens — projeto de fim de semana, alta alavancagem
  4. Escrever skill.md para as 3 principais APIs — começando pelas mais acessadas por agentes
  5. Adicionar botão “Copy for AI” — baixo custo, alto sinal
  6. Configurar monitoramento de tráfego de IA — para obter dados que justifiquem o restante do trabalho

Encerramento

• Assim como SEO ensinou que “ter ótimo conteúdo não basta; ele precisa ser descobrível de acordo com os padrões reais de tráfego da época”, AEO traz a mesma lição para um novo tipo de consumidor
• Agentes de programação com IA já representam uma parcela significativa e crescente do tráfego para documentação, e operam de forma fundamentalmente diferente de leitores humanos
• Equipes que se moverem primeiro garantem a vantagem de ver suas APIs recomendadas, integradas com sucesso e reutilizadas por agentes
• Equipes que não reagirem enfrentarão um modo silencioso de falha difícil de depurar, no qual cresce a distância entre a qualidade da documentação e a taxa real de sucesso das tarefas executadas por agentes
• Construir para agentes acaba produzindo documentação melhor também para humanos, e as duas áreas se sobrepõem muito mais do que divergem