Por que agentes de IA não devem raspar sites e o que fazer em vez disso

Todo agente de IA que navega em um site hoje recebe a mesma coisa que um humano: HTML.

Barras de navegação. Modais de consentimento de cookies. Banners de anúncios. Menus suspensos. O agente tem que analisar todo esse ruído, descobrir quais elementos do DOM representam ações reais e torcer para que a estrutura não mude na próxima semana.

Essa é a abstração errada. Os dados e operações que o agente precisa já estão no servidor — eles estão apenas envolvidos em uma lógica de apresentação destinada aos olhos humanos.

O problema, concretamente

Diga que um agente precisa pedir comida de um aplicativo de entrega. Aqui está o que ele recebe hoje:

<div class="restaurant-card" data-id="r-182">
  <h2 class="name">Pizza Palace</h2>
  <button class="cta" onclick="addToCart(182)">Peça agora</button>
</div>

O agente precisa:

1. Encontrar todos os cartões de restaurante no DOM
2. Analisar o texto para extrair nomes e IDs
3. Identificar o botão certo para clicar
4. Manipular eventos JavaScript
5. Repetir para cada página que navega

E isso quebra no momento em que o site redesenha seu frontend.

A solução: servir dados estruturados para agentes, não HTML

Os sites já servem respostas diferentes para diferentes clientes — móvel vs desktop, logado vs anônimo, API vs navegador. Eles apenas não sabem como servir agentes ainda.

agentgate é uma biblioteca Python que adiciona uma camada nativa para agentes a qualquer backend FastAPI. Quando um agente envia X-Agent-Request: true, em vez de HTML, ele recebe um manifesto legível por máquina de /.well-known/agent-manifest.json — descrevendo exatamente o que o site pode fazer, com um esquema JSON completo para entradas e saídas.

O manifesto

{
  "agent_api_version": "1.0",
  "name": "FoodPanda",
  "intents": [
    {
      "name": "search_restaurants",
      "endpoint": "/agent/intents/search_restaurants",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "location": { "type": "string" }
        },
        "required": ["query", "location"]
      },
      "output_schema": { ... }
    }
  ],
  "flows": [
    {
      "name": "order_food",
      "orchestration": "server",
      "steps": [
        { "name": "search", "entry": true, "next_steps": ["select"] },
        { "name": "select", "next_steps": ["checkout"] },
        { "name": "checkout", "next_steps": [] }
      ]
    }
  ]
}