Como dar aos agentes de IA um caminho estruturado pelo seu app

Por que agentes de IA precisam de um caminho diferente pelo seu app?

Uma parcela crescente das solicitações para sua aplicação vem de agentes de IA: assistentes que buscam documentação para um usuário, ferramentas de pesquisa que leem páginas de produto, fluxos autônomos que chamam sua API. A maioria deles opera por interfaces criadas para pessoas. Eles baixam páginas HTML completas, analisam layouts, seguem navegação pensada para um mouse e tentam novamente quando uma página com muito script não renderiza como esperam.

Isso é ineficiente para todos. Os agentes recebem conteúdo ruidoso e cometem erros. Seus servidores gastam recursos renderizando páginas que ninguém olha. E o tráfego fica difícil de interpretar, porque parece um navegador com comportamento estranho. Se você ainda não tem certeza de quanto do seu tráfego é assim, comece com como saber se o tráfego do site vem de agentes de IA.

Uma abordagem melhor é dar aos agentes um caminho estruturado: conteúdo e ações em formatos feitos para programas, descobertos em pontos padrão, com limites que recompensam clientes que se identificam corretamente. Este guia mostra como fazer isso sem construir uma segunda aplicação.

Etapa 1: Decida o que os agentes devem ser capazes de fazer

Comece pela intenção, não pela tecnologia. Observe as rotas em que você já vê tráfego de agentes e agrupe-as:

• Ler conteúdo: documentação, informações do produto, páginas de preços, artigos de ajuda, perfis públicos.
• Consultar dados: busca, consultas de catálogo, disponibilidade, status.
• Executar ações: criar, atualizar ou excluir algo em nome de um usuário.

Ler e consultar são boas candidatas a um caminho estruturado aberto a qualquer cliente que se comporte bem. As ações exigem autenticação e autorização, independentemente de como o cliente se identifica, e são cobertas no guia sobre proteção de ações sensíveis.

Etapa 2: Ofereça formatos amigáveis para máquinas

Para rotas de conteúdo, ofereça as mesmas informações sem a interface visual da página. Dois formatos cobrem a maior parte das necessidades:

• Markdown para conteúdo em texto, como documentação e artigos, servido com o tipo de mídia text/markdown registrado em RFC 7763. Ele preserva títulos, listas, links e blocos de código, e é compacto.
• JSON para registros estruturados, como produtos, planos ou status.

Use negociação de conteúdo para que a URL continue a mesma e o cliente solicite o formato que deseja:

import express from "express";

const app = express();

app.get("/docs/:slug", async (req, res) => {
  const doc = await loadDoc(req.params.slug);
  if (!doc) return res.status(404).end();

  res.vary("Accept");
  const preferred = req.accepts(["text/html", "text/markdown", "application/json"]);

  if (preferred === "text/markdown") {
    return res.type("text/markdown; charset=utf-8").send(doc.markdown);
  }
  if (preferred === "application/json") {
    return res.json({ title: doc.title, updatedAt: doc.updatedAt, body: doc.markdown });
  }
  return res.render("doc", { doc });
});

Envie um cabeçalho Vary: Accept (RFC 9110 sobre Vary) para que caches armazenem cada representação separadamente. Muitas equipes também expõem uma URL alternativa explícita, como acrescentar .md a um caminho de documentação, porque alguns clientes acham isso mais fácil do que a negociação. Vincule isso à página HTML com <link rel="alternate" type="text/markdown" href="..."> para que possa ser descoberto. Links tipados como este seguem o modelo de Web Linking.

Etapa 3: Como os agentes descobrem seu caminho estruturado?

Os agentes não podem usar o que não conseguem encontrar. Publique pontos de entrada em locais que clientes automatizados já verificam:

1. /llms.txt na raiz do site: um resumo curto em Markdown do que seu site oferece, com links para as páginas mais úteis e suas versões estruturadas, seguindo a proposta llms.txt.
2. Uma descrição da API, como um documento OpenAPI, vinculado da sua documentação para desenvolvedores e de /llms.txt.
3. Links alternativos em páginas HTML apontando para versões em Markdown ou JSON.
4. Um sitemap listando suas URLs canônicas de conteúdo, no formato definido pelo protocolo Sitemaps.

Um llms.txt mínimo:

# Example App

> Example App helps teams plan projects. This file lists the best entry points for automated clients.

## Docs
- [Getting started](https://example.com/docs/getting-started.md): setup in five steps
- [API reference](https://example.com/openapi.json): OpenAPI description of the public API

## Policies
- [Automated access](https://example.com/docs/automated-access.md): limits and how to sign requests

Mantenha uma página que explique suas regras para clientes automatizados: quais rotas estão abertas, quais limites se aplicam e como um cliente pode se identificar com solicitações assinadas para receber tratamento melhor. Regras claras transformam suposição em cooperação.

Etapa 4: Faça o roteamento por classe de ator, não por string de user agent

Depois de ter respostas estruturadas, decida quem as recebe por padrão. Use a classe de ator e sua base, em vez de analisar strings de user agent caso a caso. Operadores de IA publicam seus user agents, como OpenAI e Anthropic fazem para seus crawlers e fetchers, mas uma correspondência de string ainda é apenas uma declaração.

type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";

function preferStructured(actor: ActorClass, basis: Basis, accept: string): boolean {
  if (accept.includes("text/markdown") || accept.includes("application/json")) return true;
  return actor === "agent" && (basis === "verified" || basis === "declared");
}

Dois princípios mantêm isso seguro:

• Solicitações explícitas sempre prevalecem. Se um cliente pedir Markdown ou JSON, sirva isso, independentemente da classe.
• Padrões nunca retiram nada. Um visitante Humano ou Unknown sempre recebe a página completa. Escolher um padrão estruturado para agentes muda o formato, não o que eles têm permissão de ver.

Etapa 5: Quais limites de taxa os agentes de IA devem ter?

Os limites de taxa são onde o contexto de ator traz mais retorno de forma visível. Em vez de um limite único para todos, dê a cada combinação de classe e base um orçamento sensato:

Baseie o limite no identificador mais estável disponível. Para agentes verificados, isso é a origem do operador e o identificador da chave. Para os demais, use a credencial ou uma chave no nível de rede.

function limitKey(actor: { actor: ActorClass; basis: Basis; operator?: string }, ip: string, apiKey?: string) {
  if (actor.actor === "agent" && actor.basis === "verified" && actor.operator) return `op:${actor.operator}`;
  if (apiKey) return `key:${apiKey}`;
  return `ip:${ip}`;
}

function limitFor(actor: { actor: ActorClass; basis: Basis }): number {
  if (actor.actor === "agent" && actor.basis === "verified") return 600;
  return 120;
}

Os números são marcadores de posição. Defina os seus a partir da linha de base que você observou. Quando um cliente exceder um limite, retorne 429 Too Many Requests com um cabeçalho Retry-After e um link para sua página de acesso automatizado. Agentes bem construídos recuam e leem isso.

Etapa 6: Mantenha as ações atrás da autorização

Um caminho estruturado para leitura não é um caminho ao redor do seu modelo de segurança. Qualquer ação que altere dados ainda exige:

1. autenticação com uma credencial emitida pela sua aplicação,
2. autorização para aquela ação específica, e
3. quaisquer verificações adicionais que o nível de risco da rota exigir.

Uma assinatura verificada informa qual cliente está chamando. Ela não informa que o cliente pode agir em nome de um determinado usuário. Mantenha essas perguntas separadas. Nosso post sobre o que solicitações assinadas de agentes de IA comprovam explica a diferença.

Etapa 7: Meça o efeito

Execute o caminho estruturado primeiro em modo de observação e depois compare:

• a proporção de solicitações de agentes que usam formatos estruturados,
• o custo do servidor e a latência do tráfego de agentes antes e depois,
• as taxas de erro e de repetição para clientes agentes,
• quantos clientes automatizados passam de Declared para Verified depois que você publica suas orientações de assinatura.

Esses números mostram se o caminho estruturado está cumprindo seu papel e onde estendê-lo em seguida.

Etapa 8: Versione e documente o caminho estruturado

Trate o caminho estruturado como uma interface pública, porque os agentes vão construir em cima dele. Alguns hábitos o mantêm confiável:

1. Mantenha URLs estáveis. Se um agente aprendeu que /docs/getting-started.md existe, ele deve continuar funcionando. Quando o conteúdo mudar de lugar, retorne um 301 para o novo local em vez de um 404.
2. Inclua horários de atualização. Coloque um campo updatedAt nas respostas JSON e um cabeçalho Last-Modified no Markdown, para que os agentes possam fazer cache de forma sensata e atualizar apenas quando algo mudar.
3. Suporte a solicitações condicionais. Responda a If-None-Match e If-Modified-Since com 304 Not Modified. Agentes que consultam seu conteúdo custam muito menos quando podem revalidar em vez de baixar tudo de novo.
4. Versão para mudanças incompatíveis. Se uma estrutura JSON precisar mudar, adicione um novo caminho de versão ou um novo tipo de mídia e mantenha o antigo por um período publicado.
5. Publique um changelog para a página de acesso automatizado. Operadores de agentes que se comportam bem leem isso, e isso lhe dá um lugar para anunciar novas rotas estruturadas.

app.get("/api/plans", async (req, res) => {
  const plans = await loadPlans();
  const etag = `"${plans.version}"`;
  res.set("ETag", etag);
  res.set("Cache-Control", "public, max-age=300");
  if (req.get("if-none-match") === etag) return res.status(304).end();
  return res.json({ updatedAt: plans.updatedAt, plans: plans.items });
});

Essas práticas também beneficiam seu próprio frontend e as integrações com parceiros. Um caminho estruturado que seja estável, armazenável em cache e documentado rapidamente se torna a forma mais fácil para qualquer programa trabalhar com sua aplicação.

Armadilhas comuns

• Entregar fatos diferentes para agentes e pessoas. A versão estruturada deve conter as mesmas informações da página. Conteúdo divergente confunde usuários que perguntam a um assistente sobre seu produto.
• Ocultar o caminho estruturado. Se ele não estiver vinculado de /llms.txt, na sua documentação de API ou nas próprias páginas, os agentes continuarão raspando HTML.
• Premiar alegações. Limites maiores pertencem a clientes verificados. Uma string de user agent copiada não deve ganhar um orçamento maior.
• Esquecer caches. Sem Vary: Accept, um cache pode servir Markdown para um navegador.

Onde Proof of Actor se encaixa

Proof of Actor fornece a classe de ator e a base de que você precisa para rotear agentes para conteúdo estruturado e definir limites justos. Ele detecta agentes assinados, declarados e inferidos, ajuda você a entender como eles usam suas rotas e deixa a decisão de roteamento no seu código.

Para projetar um caminho estruturado para sua própria aplicação com a nossa equipe, inscreva-se para acesso antecipado. Para cenários de API e MCP especificamente, veja APIs e MCP Servers, e leia quem está chamando seu MCP server? para entender como o contexto de ator se aplica a chamadas de ferramenta do Model Context Protocol.

Fontes

• RFC 9110: HTTP Semantics: negociação de conteúdo (Seção 12), Vary (Seção 12.5.5), solicitações condicionais (Seção 13) e Retry-After (Seção 10.2.3)
• RFC 7763: The text/markdown Media Type: servir representações em Markdown
• RFC 8288: Web Linking: links tipados alternate
• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests
• proposta llms.txt: o formato de arquivo /llms.txt
• OpenAPI Specification: descrições de API legíveis por máquina
• protocolo Sitemaps: formato de arquivo de sitemap
• OpenAI: Overview of OpenAI Crawlers: user agents e intervalos de IP publicados pela OpenAI
• Anthropic: crawler and fetcher documentation: ClaudeBot, Claude-User e Claude-SearchBot
• Model Context Protocol specification (2026-07-28): a revisão atual de MCP em novembro de 2026