Um arquivo de descoberta para agentes não pode ser lido
Um arquivo que os agentes procuram em /.well-known/ responde, mas não pode ser lido: agent-card.json (um agent card A2A), mcp.json (um descritor de servidor MCP), api-catalog (RFC 9727) ou, em lojas, ucp. Ele não é um JSON válido ou não tem um campo obrigatório, como o name do agent card ou o linkset do catálogo de API.
O que significa
Um arquivo em /.well-known/ que os agentes procuram (o agent card, o descritor MCP, o catálogo de API ou o perfil UCP) responde, mas não com JSON válido ou sem os campos necessários. Os agentes que o encontram param ali. Corrija o arquivo ou remova-o.
Por que isso importa para a busca com IA
Esses arquivos dizem aos agentes o que um site oferece: um agente com quem conversar, um servidor MCP, uma API, uma forma de comprar. Um agente que encontra um deles e não consegue interpretá-lo desiste em vez de tentar adivinhar.
A maioria dos sites não precisa de nenhum deles, então um arquivo ausente nunca é apontado. Um arquivo que existe mas está quebrado costuma vir de um teste, de um template ou de um plugin que foi configurado e esquecido.
Como corrigir
- Abra cada arquivo das evidências e passe-o por um validador de JSON.
- Corrija a sintaxe e adicione os campos obrigatórios, seguindo a especificação do próprio arquivo.
- Sirva-o com
Content-Type: application/json(application/linkset+jsonpara o catálogo de API). - Se o site não oferece o que o arquivo descreve, apague o arquivo. Execute “Verificar de novo” no relatório da página para confirmar o resultado.
Exemplo
{
"name": "Example support agent",
"description": "Answers questions about orders",
"url": "https://example.com/a2a",
"version": "1.0.0",
"skills": []
} Como confirmar a correção
Depois da mudança, clique em “Verificar de novo” no relatório: ele mostra o que foi corrigido e como a nota mudou.