Agent Card vs robots.txt: dois arquivos, duas eras do acesso por máquina

Última atualização: 19 Mai 2026

A diferença em uma frase

robots.txt define permissão de acesso. agent-card.json declara capabilities de negócio.

Essas seis palavras resumem por que os dois arquivos coexistem sem conflito — e por que confundi-los indica que a infraestrutura do seu site ainda está calibrada para um visitante que não domina mais o tráfego de AI.

Quando o bot do Google chega ao seu servidor em 1994, a única pergunta relevante é: posso rastrear essa URL? robots.txt existe para responder isso. Ele é uma política de controle de acesso — sem sintaxe para descrever o que a empresa faz, quais ações estão disponíveis, ou como um agente deve interagir com o sistema.

Quando um agente AI chega ao seu servidor em 2026, ele tem perguntas completamente diferentes: O que esse site faz? Quais serviços estão disponíveis? Posso solicitar uma cotação diretamente? Qual endpoint aceita ações automatizadas? Quais autenticações são suportadas? robots.txt não tem como responder nenhuma dessas perguntas. agent-card.json foi projetado exatamente para isso.

Por que robots.txt não basta em 2026

Para entender a limitação, é útil olhar o que robots.txt foi projetado para fazer — e o que está fora do seu escopo por design.

O padrão foi proposto por Martijn Koster em 1994 como o "Robots Exclusion Protocol": um mecanismo simples para que donos de sites comunicassem a rastreadores automatizados quais caminhos eram off-limits. A RFC 9309, publicada em 2022, modernizou a spec sem alterar a premissa fundamental. Dois tipos de diretivas: Allow e Disallow. Uma diretiva opcional de Crawl-delay. Um apontador para Sitemap.

Isso é tudo. E é suficiente para o problema que robots.txt resolve.

O problema é que agentes de AI modernos — sistemas que executam tarefas de forma autônoma, consultam APIs, preenchem formulários, solicitam orçamentos e fecham contratos — não estão simplesmente rastreando conteúdo. Eles precisam de uma interface de capabilities: o que este site pode fazer por mim? Quais ações estão disponíveis? Em quais endpoints? Com qual autenticação?

Nenhum desses dados existe no robots.txt. A consequência prática: um agente que chega ao seu site sem um agent-card.json tem três opções. Tentar inferir capabilities a partir do HTML (caro, impreciso, ~3.000 tokens para uma homepage comum). Consultar sua memória de treinamento sobre o domínio (potencialmente desatualizada). Ou simplesmente não tentar — e seguir para um concorrente que declarou suas capabilities de forma legível por máquina.

O terceiro cenário é o mais comum. E é silencioso — nenhum analytics tradicional registra quando um agente desistiu de você.

O que é agent-card.json

agent-card.json é um arquivo JSON publicado em /.well-known/agent-card.json que declara as capabilities de um sistema para agentes AI que seguem o Google A2A Protocol.

O A2A Protocol (Agent-to-Agent) foi lançado pelo Google em abril de 2025 com mais de 150 organizações fundadoras — incluindo Anthropic, Microsoft, Salesforce e SAP. A spec oficial está em google.github.io/A2A/. O objetivo declarado: estabelecer um padrão aberto para que agentes AI descobrissem e se comunicassem com outros sistemas — sem depender de integrações point-to-point ou documentação de API em linguagem natural.

O caminho /.well-known/ não é uma escolha arbitrária. É o diretório padronizado pela RFC 5785 para metadados de serviço que precisam ser descobertos de forma consistente por clientes automatizados — o mesmo mecanismo usado para /.well-known/openid-configuration em OAuth e /.well-known/security.txt em disclosure de vulnerabilidades.

A estrutura de um agent-card.json contém:

• name e description — identidade legível por humanos e máquinas
• skills[] — array de capabilities disponíveis, cada uma com id, description, inputs tipados, outputs esperados e endpoint para execução
• capabilities — features de protocolo suportadas (streaming, push notifications)
• defaultInputModes / defaultOutputModes — tipos de mídia aceitos e retornados
• Extensions opcionais — o A2A Protocol permite campos prefixados com x_ para extensões proprietárias não-destrutivas

A lógica é análoga à de uma OpenAPI spec, mas otimizada para descoberta por agentes — não para documentação de desenvolvedor. O agent-card informa o que o sistema faz; o agente decide se e como interagir com base nessa declaração.

Exemplo real — agent-card.json da EPIC

A EPIC publica seu próprio agent-card.json como parte da implementação dogfood do AEO Framework™. O arquivo está em produção em epic.digital/.well-known/agent-card.json. O trecho abaixo é o arquivo real, sem modificações editoriais:

{
  "name": "EPIC Digital",
  "description": "Consultoria de Arquitetura de Receita B2B. Implementa Revenue Operations,
    AEO Framework v2.2 (7 layers, 66 checks), Commerce Layer (A2A Protocol + MCP),
    e operações HubSpot para mais de 25 clientes ativos em B2B SaaS, fintech,
    consulting e enterprise software.",
  "url": "https://www.epic.digital",
  "version": "1.0.0",
  "protocolVersion": "0.3",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "request_audit",
      "name": "Request AEO Audit",
      "description": "Solicita audit AEO gratuito do domínio informado. EPIC roda
        `aeo audit` em 48 horas e retorna relatório HTML com Combined Score por
        layer, gaps críticos e potencial de melhoria.",
      "tags": ["audit", "diagnostic", "free", "lead-capture"],
      "inputs": {
        "type": "application/json",
        "schema": {
          "firstname": "string (required)",
          "email": "email (required)",
          "company": "string (required)",
          "website": "url (required)"
        }
      },
      "outputs": {
        "type": "application/json",
        "schema": {
          "status": "string (received|error)",
          "ticket_id": "string",
          "eta_hours": "number (48)",
          "next_steps": "string"
        }
      },
      "endpoint": "https://www.epic.digital/api/aeo/audit-request",
      "method": "POST"
    }
  ],
  "x_aeo": {
    "version": "2.2",
    "framework": "AEO Framework v2.2 — 7 layers, 66 checks",
    "landing_page": "https://www.epic.digital/aeo/diagnostico",
    "landing_page_clients": "https://www.epic.digital/aeo/produto"
  }
}

Três aspectos merecem atenção:

O campo skills[] é o coração do arquivo. Cada skill é uma capability executável, com schema de inputs e outputs tipados — não uma descrição de marketing. Um agente que lê este arquivo sabe exatamente o que enviar e o que esperar em resposta, sem consultar documentação adicional.

O campo x_aeo é uma extension proprietária. O prefixo x_ sinaliza ao protocolo que é metadata não-padrão — o agente pode ignorar se não souber interpretá-la. A EPIC usa esse campo para fornecer contexto adicional sobre versão do framework, links de landing page e métricas de referência. Outros sistemas podem criar suas próprias extensions sem quebrar compatibilidade.

O campo protocolVersion indica a versão do A2A Protocol suportada. Agentes que implementam versões mais recentes do protocolo podem identificar limitações antes de tentar interagir, evitando falhas silenciosas.

A2A vs MCP — complementares, não competidores

É comum a confusão entre o Google A2A Protocol e o MCP (Model Context Protocol) da Anthropic. São padrões diferentes, com escopos diferentes, projetados para estágios diferentes da interação agente-sistema.

O MCP, lançado em novembro de 2024 e adotado first-class por Claude Desktop, ChatGPT e Gemini em 2026, resolve um problema específico: como um modelo de linguagem acessa ferramentas externas durante a execução de uma tarefa. Pense no MCP como o protocolo de runtime — ele define como o agente invoca uma função, recebe o resultado e decide o próximo passo. A spec oficial está em modelcontextprotocol.io.

O A2A Protocol, por sua vez, resolve o problema de descoberta e declaração de capabilities. Antes de invocar qualquer função, o agente precisa saber: este sistema existe, suporta ações automatizadas, e aqui estão os parâmetros para interagir. agent-card.json é essa declaração.

A distinção prática: A2A declara o que um sistema pode fazer (nível de descoberta). MCP define como o agente executa isso (nível de runtime). Um bom sistema agent-ready implementa ambos — usa agent-card.json para se tornar descobrível e declarar capabilities, e implementa endpoints compatíveis com MCP para que a execução seja confiável e padronizada.

A analogia com infraestrutura web é útil: agent-card.json é para agentes o que um OpenAPI spec é para desenvolvedores — a documentação de contrato. MCP é o HTTP/HTTPS sobre o qual a transação acontece.

Como criar o seu agent-card.json

A barreira técnica para publicar um agent-card.json é baixa. O arquivo é JSON estático que pode ser servido por qualquer servidor web. O desafio real é de design: o que declarar, com qual granularidade, e com quais salvaguardas.

Quatro decisões que determinam a qualidade do seu agent-card:

1. Quais skills declarar. Comece pelas ações que um agente externo precisaria executar para obter valor do seu sistema. Para um site B2B, o conjunto típico inclui: solicitar diagnóstico, obter cotação, agendar demonstração, consultar disponibilidade. Não liste capabilities internas ou administrativas — o agent-card é uma interface pública de capabilities de negócio, não um inventário de endpoints.

2. Inputs e outputs com schema preciso. Campos vagos ("dados do cliente: object") são equivalentes a documentação de API sem tipos — funcionais para um humano que vai ler e inferir, problemáticos para um agente que precisa de validação prévia. Use tipos primitivos explícitos: string, email, url, number. Marque campos obrigatórios como required.

3. Human-in-the-loop para ações consequentes. Nem toda skill precisa ser executável automaticamente. Para ações de alto impacto (contratos, pagamentos, acessos privilegiados), o campo implementationStatus pode ser spec_only — declarando a capability sem expor execução automática. O agente reconhece a capability, mas entende que requer intervenção humana para completar. O agent-card.json da EPIC usa exatamente esse padrão para o endpoint de audit: a skill está declarada, o agente pode ler e planejar, mas a execução roteia para um formulário com review humano.

4. Escopo de acesso e autenticação. O campo authentication (opcional no protocolVersion 0.3) permite declarar quais skills requerem credenciais. Skills públicas (cotação anônima, disponibilidade de calendário) não precisam de autenticação declarada. Skills que operam sobre dados de cliente (status de contrato, histórico) devem ser protegidas. Declarar a política de acesso no agent-card evita que agentes tentem executar ações para as quais não têm permissão — e recebam erros que degradam a experiência.

Após criar o arquivo, o passo de validação mais simples é verificar se ele é JSON válido e se está acessível no caminho correto:

curl -s https://seu-dominio.com/.well-known/agent-card.json | python3 -m json.tool

Uma resposta limpa com a estrutura JSON formatada confirma que o arquivo está publicado e bem formado. Validação de conformidade com o A2A Protocol requer comparação contra o schema oficial em google.github.io/A2A/ — ou, no caso de sites que implementam o AEO Framework™ completo, a pontuação de Layer 4 no relatório do CLI proprietário EPIC (ferramenta interna, não distribuída publicamente).

O que isso desbloqueia — Commerce Layer™

agent-card.json é o ponto de entrada. O que ele desbloqueia é o Commerce Layer™ — o sistema completo que transforma um site de repositório de informações em um canal de negócios acessível por agentes.

No AEO Framework™ da EPIC, o Commerce Layer é o Layer 4 de um sistema de 7 camadas. Os primeiros três layers (Discovery, Structured Data, Semantic HTML) garantem que agentes encontrem e entendam o site. O Layer 3 (Narrative Blocks) garante que o conteúdo seja citável e extraível. O Layer 4 é onde a capacidade de agir entra — não apenas ser lido.

O Commerce Layer completo tem cinco componentes:

• Agent Card (/.well-known/agent-card.json) — ponto de descoberta e declaração de capabilities, que você acaba de ler sobre
• AEO Sitemap (/sitemap-aeo.json) — índice machine-readable de todas as páginas do site com ações disponíveis por URL
• JSON Endpoints (/api/aeo/{página}.json) — versão estruturada de cada página, otimizada para tokens (~400 tokens vs ~3.000 tokens para HTML)
• Transactional Endpoints — APIs POST que executam ações reais: solicitar cotação, agendar audit, receber recomendação personalizada
• Alternate Link Declaration — tag <link rel="alternate"> no HTML que sinaliza ao crawler que existe uma versão JSON da mesma página

A implicação estratégica é direta: enquanto sites sem Commerce Layer precisam que um agente faça inferências sobre o que é possível fazer ali, sites com Commerce Layer tornam essa informação explícita, estruturada e executável. Para B2B global — energia, infraestrutura, SaaS enterprise, fintech — esse não é um diferencial opcional. É a diferença entre aparecer ou não no conjunto de opções que um agente considera quando executa uma tarefa de compra, avaliação ou integração.

A EPIC implementou o Commerce Layer completo no próprio site como dogfood do framework. O agent-card.json que você viu acima é o Layer 4 em produção — não um exemplo hipotético.

Para entender a arquitetura completa do Commerce Layer™ e como ele se integra aos outros layers do AEO Framework™, o spoke dedicado está em /aeo/commerce-layer.

Perguntas frequentes

agent-card.json substitui robots.txt?

Não. Os dois arquivos resolvem problemas diferentes em camadas diferentes do acesso por máquina. robots.txt controla quais caminhos rastreadores podem indexar — é uma política de permissão de acesso que qualquer crawler web respeita. agent-card.json declara capabilities de negócio para agentes AI que seguem o A2A Protocol — é um contrato de interface, não uma política de acesso. Manter robots.txt correto é pré-condição (Layer 0 no AEO Framework™). Publicar agent-card.json é o que habilita transações (Layer 4). São complementares e ambos são necessários.

Onde exatamente o agent-card.json deve ser publicado?

O caminho canônico definido pelo A2A Protocol é /.well-known/agent-card.json — na raiz do domínio principal. O diretório /.well-known/ é um padrão RFC 5785 para metadados de serviço de descoberta automática. Alguns sistemas que hospedam múltiplos agentes publicam variações por subdomínio (agent.empresa.com/.well-known/agent-card.json), mas para a grande maioria dos casos corporativos, um único arquivo na raiz é suficiente e correto.

Qual a diferença entre o A2A Protocol e o MCP da Anthropic?

O A2A Protocol (Google, abril de 2025) define como agentes descobrem sistemas e declaram capabilities — é a camada de descoberta e contrato. O MCP — Model Context Protocol (Anthropic, novembro de 2024) — define como um modelo de linguagem acessa ferramentas externas durante a execução de uma tarefa — é a camada de runtime. A2A declara o que um sistema pode fazer. MCP é o mecanismo pelo qual o agente invoca isso. Uma infraestrutura agent-ready robusta implementa ambos: agent-card.json para descoberta, endpoints compatíveis com MCP para execução confiável.

Qualquer stack consegue publicar agent-card.json?

Sim. agent-card.json é um arquivo JSON estático. Qualquer servidor web que sirva arquivos estáticos consegue publicá-lo — Apache, Nginx, HubSpot CMS, Vercel, Netlify, S3 com static hosting. O requisito é que o arquivo esteja acessível em /.well-known/agent-card.json com content-type application/json. Stacks com restrições de roteamento (como o HubSpot CMS Pro) podem exigir configurações específicas para servir o diretório /.well-known/ corretamente — isso é coberto nas camadas de implementação do AEO Framework™.

Como validar se meu agent-card.json está correto?

O teste mais básico é verificar se o arquivo é JSON válido e está acessível no caminho correto via curl -s https://seu-dominio.com/.well-known/agent-card.json | python3 -m json.tool. Para validação de conformidade com o A2A Protocol, a spec de referência está em google.github.io/A2A/. Para análise completa das 11 verificações de Layer 4 — incluindo agent-card, sitemap-aeo.json, JSON endpoints e transactional endpoints — o CLI proprietário EPIC (ferramenta interna, não distribuída publicamente) produz um relatório com Combined Score por layer e gaps acionáveis.

Quais empresas já implementaram agent-card.json?

O A2A Protocol foi lançado em abril de 2025 com mais de 150 organizações fundadoras, incluindo Google, Anthropic, Microsoft, Salesforce e SAP. A adoção comercial está em estágio early mover em maio de 2026 — o que significa que empresas que implementam agora ganham vantagem de descoberta antes que o padrão se torne commoditizado. A EPIC publica seu próprio agent-card.json em produção como implementação de referência do AEO Framework™.