ard.json

A Agentic Resource Discovery (ARD) é uma especificação para catalogar recursos agênticos. O manifesto ard.json descreve recursos de agentes em um domínio, como servidores MCP, agentes A2A e habilidades de agentes, para que agentes de IA e registros possam encontrá-los.

Como funciona a auditoria do Lighthouse

Processo de descoberta: a auditoria procura o manifesto com base nos mecanismos de descoberta na especificação ARD (§5.1):

  • Verificando se há uma diretiva Agentmap: dentro de robots.txt.
  • Verificando se há tags <link rel="ard" href="..."> no HTML.
  • Inspecionando uma resposta de cabeçalho HTTP Link: <...>; rel="ard".
  • Buscando no endpoint conhecido /.well-known/ard.json.

Se a descoberta principal falhar, o Lighthouse vai verificar os caminhos legados (como rel="ai-catalog" ou /.well-known/ai-catalog.json). Embora o conteúdo encontrado aqui ainda seja validado, um aviso é gerado porque os clientes ARD padrão não são obrigados a oferecer suporte a rotas descontinuadas.

Regras de validação: a verificação é realizada usando uma porta JavaScript do conjunto de conformidade da ARD v0.91, testando os seguintes critérios:

Erros de conformidade e validação:

  • Sintaxe e esquema: o manifesto é um JSON válido e corresponde ao esquema de manifesto ARD, e cada entrada corresponde ao esquema de entrada ARD. O Lighthouse não busca nem valida o artefato para o qual uma entrada aponta (por exemplo, o card do servidor MCP em url).
  • Campos obrigatórios: o manifesto contém uma matriz entries, e cada entrada contém um identifier, displayName e type.
  • URNs ancorados em domínio: cada identifier segue o formato urn:air:<publisher>:<namespace>:<name>.
  • Definição de local: cada entrada define exatamente um url ou data inline, nunca ambos ou nenhum.
  • Estrutura do manifesto de confiança: quando um trustManifest é incluído, ele é um objeto com uma propriedade identity.

Avisos de práticas recomendadas:

  • Consultas representativas: cada entrada tem uma matriz representativeQueries com 2 a 5 consultas de exemplo. Os registros criam o índice da Pesquisa com base neles, então uma entrada sem eles não vai aparecer nos resultados da pesquisa. Se presente, precisa ser uma matriz de strings. Qualquer outro tipo de dado gera um erro.
  • Tipo de mídia: type precisa ser um tipo de mídia bem formado. O Lighthouse avisa sobre tipos descontinuados (por exemplo, application/mcp-server+json para application/mcp-server-card+json), tipos padrão com parâmetros ausentes ou extras e tipos não reconhecidos fora de application/*. Tipos personalizados de application/* são permitidos.
  • Coleções: sinaliza um campo collections de nível superior. Ele não faz mais parte da ARD e é ignorado. Em vez disso, use hierarquias de modelo dentro de entries.
  • Endpoints legados: sinaliza manifestos encontrados apenas nos locais legados de ai-catalog.
  • Locais anunciados corrompidos: sinaliza qualquer local anunciado (link Agentmap:, rel="ard" ou rel="ai-catalog" ou cabeçalho Link) que não pôde ser carregado quando o manifesto foi encontrado em outro lugar.

Não é necessário:

  • specVersion e outros campos extras de nível superior não afetam a pontuação.
  • capabilities são opcionais e não recebem pontuação. Se o recurso expor ferramentas ou habilidades nomeadas, considere listá-las (por exemplo, ["WeatherTool", "ForecastTool"]) para que os registros possam filtrá-las sem buscar o artefato completo. Se incluído, precisa ser uma matriz de strings.

Como ler a tabela de resultados

A coluna "Elemento" mostra Root para problemas com o manifesto como um todo. Para problemas com uma entrada, ele mostra o displayName da entrada, voltando para o identifier ou Entry #n se nenhum estiver disponível. Um único problema de esquema pode aparecer duas vezes, uma em Root e outra na entrada, correspondendo à saída do teste de conformidade oficial.

Entenda sua pontuação

Os resultados da auditoria são refletidos das seguintes maneiras:

  • Aprovado (1): o manifesto foi encontrado e não tem erros ou avisos.
  • Crédito parcial (0,9): o manifesto é válido, mas tem pelo menos um aviso de prática recomendada.
  • Falha (0): qualquer erro de conformidade, como JSON malformado, uma violação de esquema, um URN inválido ou ambos ou nenhum de url/data. A auditoria também falha se um manifesto foi anunciado (por meio de robots.txt, um link rel="ard" ou rel="ai-catalog" ou um cabeçalho Link), mas não pôde ser carregado.
  • Não relevante: nenhum manifesto foi encontrado por qualquer método. Isso não afeta sua pontuação do Lighthouse.

Como corrigir

Para passar na auditoria, siga estas etapas:

  1. Disponibilize o manifesto em /.well-known/ard.json ou vincule-o a rel=ard. Se você usa ai-catalog.json ou rel=ai-catalog, mude para os novos nomes.
  2. Corrija os erros listados na tabela de auditoria para que o manifesto corresponda ao esquema da ARD.
  3. Dê a cada entrada um identificador urn:air:... e exatamente um entre url ou data.
  4. Use um tipo de mídia ARD padrão em type, quando aplicável.
  5. Adicione de 2 a 5 representativeQueries a cada entrada para conseguir uma pontuação perfeita.