Como tornar um site Agent-Ready — e o que 100 no IsItAgentReady realmente prova

O que mede

Existe um robots.txt válido e ele não impede o acesso ao conteúdo.

Como implementar

Um arquivo em texto na raiz, com pelo menos um grupo User-agent e a diretiva Sitemap apontando para o índice absoluto.

Neste projeto

/robots.txt — versionado em public/robots.txt, servido como está.

Como validar

curl -s https://seu-site/robots.txt

O que mede

Existe um sitemap.xml alcançável, com URLs absolutas.

O princípio

O sitemap é o inventário do que você quer que seja consumido. A lista de exclusões é tão importante quanto a de inclusões: área administrativa, páginas de teste e utilitários internos não são convite.

Neste projeto

Gerado no build por vite-plugin-sitemap, com lista explícita de exclusões em vite.config.js. Nunca escrito à mão — um sitemap mantido manualmente diverge do site na primeira página nova.

Como validar

curl -sI https://seu-site/sitemap.xml deve responder 200 e application/xml.

O que mede

O site anuncia recursos relacionados no header HTTP, não apenas no corpo do documento.

O princípio

Esta é a camada mais barata para o agente e a mais ignorada por quem implementa. Um HEAD em qualquer URL já entrega o mapa: nenhum download de página, nenhum parser de HTML, nenhuma convenção a adivinhar. É também a única camada que funciona para recursos que não são HTML.

Neste projeto

Sete relações em toda resposta, aplicadas por uma política de headers no CDN — ou seja, fora do repositório. Se o seu site roda em Vercel, Netlify, nginx ou Cloudflare, a receita é a do seu stack; o conteúdo é o mesmo.

link: </.well-known/api-catalog>; rel="api-catalog",
      </.well-known/ai-catalog.json>; rel="service-desc"; type="application/json",
      </llms.txt>; rel="service-doc"; type="text/plain",
      </llms-full.txt>; rel="describedby"; type="text/plain",
      </cv-for-ai.md>; rel="service-doc"; type="text/markdown",
      </cv.json>; rel="describedby"; type="application/json",
      </.well-known/oauth-protected-resource>; rel="oauth-protected-resource"
vary: Accept

Como validar

Exemplo genérico shell

curl -sI https://seu-site/ | grep -i '^link\|^vary'

O que mede

O domínio publica registros DNS que apontam para os pontos de entrada agênticos — e a resposta é validada por DNSSEC.

O princípio

Descoberta antes do primeiro pacote HTTP. Um agente que resolve _index._agents. do domínio já sabe onde procurar sem ter carregado nada. E aqui há uma regra que a documentação deixa implícita: sem DNSSEC a validação não passa. O registro publicado sem cadeia de confiança é, para o avaliador, um registro que qualquer resolvedor no caminho poderia ter inventado.

Neste projeto

Três nomes (_index, _mcp, _a2a) sob _agents., com a zona assinada. O script de publicação vive em scripts/setup-dns-aid-route53.sh e a operação em docs/DNS_AID_SETUP.md.

curl -s -H 'accept: application/dns-json' \
  'https://cloudflare-dns.com/dns-query?name=_index._agents.seu-site&type=HTTPS&do=1'

AD: true é a resposta autenticada. Se vier false, a cadeia DNSSEC não fecha — e nenhum ajuste no registro resolve isso.

O que mede

Uma requisição com Accept: text/markdown recebe Markdown; um navegador recebe HTML. Mesma URL, formatos diferentes.

O princípio

Negociação de conteúdo é um mecanismo de 1996 que quase ninguém usou, e é exatamente o que o agente precisa. A alternativa comum — publicar /pagina.md como URL separada — funciona, mas obriga o agente a adivinhar a convenção e fragmenta a identidade do recurso: duas URLs para o mesmo conteúdo, dois canônicos, dois lugares para desatualizar.

Como implementar

Uma função na borda do CDN inspeciona o header Accept e reescreve o caminho. Duas armadilhas: comparar os valores de qualidade q (um navegador manda text/html,…,*/*;q=0.8 e não pode receber Markdown), e emitir Vary: Accept — sem ele o CDN entrega a versão em cache errada para o cliente errado.

Neste projeto

infra/cloudfront-functions/viewer-request.js, com os companions .md gerados em public/ pelo mesmo pipeline que gera os metadados.

function prefersMarkdown(acceptHeader) {
  if (!acceptHeader) return false;

  var markdownQ = -1;
  var htmlQ     = -1;

  acceptHeader.split(',').forEach(function (part) {
    var tokens = part.trim().split(';');
    var type   = tokens[0].trim().toLowerCase();
    var q      = 1.0;

    for (var i = 1; i < tokens.length; i++) {
      var param = tokens[i].trim();
      if (param.indexOf('q=') === 0) {
        var parsed = parseFloat(param.slice(2));
        q = isNaN(parsed) ? 0 : parsed;
        break;
      }
    }

    if (type === 'text/markdown') {
      markdownQ = q;
    } else if (type === 'text/html') {
      if (q > htmlQ) htmlQ = q;
    }
  });

  return markdownQ > 0 && markdownQ >= htmlQ;
}

Como validar

Exemplo genérico os dois lados da negociação precisam ser testados

# o agente pede Markdown → deve receber text/markdown
curl -s -H 'Accept: text/markdown' -o /dev/null \
  -w '%{content_type}\n' https://seu-site/pagina

# o navegador NÃO pode receber Markdown → deve receber text/html
curl -s -H 'Accept: text/html,application/xhtml+xml,*/*;q=0.8' -o /dev/null \
  -w '%{content_type}\n' https://seu-site/pagina

Este documento responde à mesma negociação: /agent-ready.md é o mesmo conteúdo sem layout.

O que mede

Se o robots.txt trata bots de IA — por regra específica ou por um curinga que os alcança.

A leitura honesta

Aqui o check passa com a mensagem "No AI-specific bot rules; wildcard rules apply to all crawlers including AI bots". Ou seja: ele passa por ausência de bloqueio, não por presença de regra. Entender essa diferença vale mais do que comemorar o verde — se a sua política for diferente por agente, é você que precisa escrevê-la; o curinga não decide nada por você.

Neste projeto

User-agent: * com Allow: /, e as exclusões restritas a diretórios internos.

O que mede

Presença da diretiva Content-Signal no robots.txt, declarando os usos permitidos do conteúdo.

O princípio

robots.txt responde se o bot pode buscar. Content Signals responde o que ele pode fazer depois de ter buscado — três decisões independentes: aparecer em busca, ser usado como fonte de resposta, ser usado para treinar modelo. São perguntas distintas e merecem respostas distintas.

Neste projeto

Indexar sim, servir de insumo para resposta sim, treinar não.

User-agent: *
Allow: /
Content-Signal: ai-train=no, search=yes, ai-input=yes

Sitemap: https://mauricio.issei.com.br/sitemap.xml
Agentmap: https://mauricio.issei.com.br/.well-known/ai-catalog.json
LLMs: https://mauricio.issei.com.br/llms.txt
LLMs-full: https://mauricio.issei.com.br/llms-full.txt

O que mede

Se o site publica um diretório de chaves que permite verificar criptograficamente a identidade de um bot, por assinatura de mensagem HTTP.

O princípio

O User-Agent é uma string que qualquer cliente escreve. Web Bot Auth substitui declaração por prova: o bot assina a requisição, e o site valida contra a chave publicada. É a diferença entre dizer que é um agente conhecido e demonstrar que é.

Estado aqui

Neutro — não implementado. Faz sentido para quem precisa distinguir bot legítimo de imitador e aplicar política diferente a cada um. Para um site de conteúdo público, cujo Content Signal já é o mesmo para todos, não muda nenhuma decisão. Um check neutro não penaliza a nota — e é justamente por isso que ele não atesta nada. Ver os limites do score.

O princípio

Um linkset: para cada recurso (anchor), quais links tipados existem. Uma especificação legível por máquina (service-desc), a documentação em prosa (service-doc), o estado (status). O agente descobre a API e como entendê-la em uma única requisição.

{
  "linkset": [
    {
      "anchor": "https://seu-site/dados.json",
      "service-desc": [
        { "href": "https://seu-site/openapi.json",
          "type": "application/openapi+json;version=3.0" }
      ],
      "service-doc": [
        { "href": "https://seu-site/dados.md", "type": "text/markdown" }
      ]
    }
  ]
}

O princípio

Autenticação para agentes tem duas faces. A máquina precisa dos metadados: qual servidor de autorização, quais escopos, onde está a política de privacidade. O agente precisa de instruções em prosa — auth.md é literalmente isso: um documento Markdown que descreve o fluxo, para ser lido por quem raciocina em linguagem natural.

Vale para acesso anônimo também. "Nenhuma credencial é necessária, e estes são os escopos disponíveis" é uma declaração útil — evita que o agente tente um fluxo que não existe.

{
  "resource": "https://mauricio.issei.com.br",
  "authorization_servers": ["https://mauricio.issei.com.br"],
  "scopes_supported": ["cv:read", "projects:read", "profile"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://mauricio.issei.com.br/cv-for-ai.md",
  "resource_policy_uri": "https://mauricio.issei.com.br/privacidade"
}

O documento de autorização deste site declara identidade anônima explicitamente. O formato exato — e por que ele custou três iterações de deploy — está em o caso do agent_auth.

O princípio

Uma skill é procedimento, não dado: "como fazer X neste domínio", escrito para ser carregado no contexto de um agente. O índice aponta para cada SKILL.md e traz o digest SHA-256 do arquivo — o agente verifica que carregou o que o índice prometeu, e não algo trocado no caminho. Instrução que entra no contexto de um modelo é superfície de ataque; o digest é o que a torna verificável.

Neste projeto

Duas skills — convenções deste repositório e acesso aos dados estruturados do currículo —, cada uma com digest.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "cv-data-access",
      "type": "skill-md",
      "description": "How to retrieve and parse structured CV data…",
      "url": "https://mauricio.issei.com.br/.well-known/agent-skills/cv-data-access/SKILL.md",
      "digest": "sha256:95a3d61a86da45cae9037e0f4f7d41a64a37cc4f2a61567791b95c2f5a2178ec"
    }
  ]
}

O princípio

As outras oito camadas são estáticas: documentos publicados que o agente lê de fora. WebMCP é a única em tempo de execução — a página registra ferramentas no navegador, e um agente que esteja rodando ali dentro pode invocá-las com a sessão do usuário, sem servidor intermediário.

É proposta em evolução, então o registro vai atrás de um teste de existência. Sem navigator.modelContext, nada acontece e a página segue idêntica.

if (typeof navigator.modelContext !== 'undefined') {
    const controller = new AbortController();
    const signal = controller.signal;

    navigator.modelContext.registerTool({
        name: 'get_cv_data',
        description: 'Retrieve the full structured curriculum vitae in JSON format.',
        inputSchema: { type: 'object', properties: {} },
        execute: async () => {
            const response = await fetch('/cv.json');
            return await response.json();
        }
    }, { signal });
}