Ferramenta de descoberta · A2A v1.0

Verifique as URLs de descoberta do A2A Agent Card

Clientes A2A descobrem um agente buscando seu Agent Card JSON em uma URL well-known. Teste as duas convenções de nomenclatura em um domínio real e veja exatamente o que os clientes recebem.

Constrói ambas as URLs de descoberta candidatas a partir do mesmo domínio base.

Busca o JSON retornado e relata o código de status e o tipo de conteúdo.

Analisa a resposta como JSON de Agent Card quando possível.

Executa verificações de prontidão para interfaces, skills, provedor, modos, capacidades e metadados de segurança.

Verificar um domínio de agente público

Digite um domínio base. O verificador busca ambos os caminhos de descoberta, analisa o JSON retornado e executa verificações de prontidão do Agent Card.

Como funciona a descoberta

Uma única URL well-known inicia cada integração A2A.

Antes que outro agente possa chamar o seu, ele busca o Agent Card em um URI well-known (RFC 8615) no seu domínio, avalia as skills e os requisitos de segurança, e então chama a interface preferida. Se o Agent Card estiver ausente, desatualizado ou escondido atrás de um redirecionamento, a integração falha antes mesmo de começar.

Este site pratica o que verifica: a AgentCard.net publica seu próprio Agent Card em ambos os caminhos, e o exemplo à direita é o documento real.

Ver nosso Agent Card ao vivo
agentcard.net discovery
GET /.well-known/agent-card.json HTTP/1.1
Host: www.agentcard.net

HTTP/1.1 200 OK
Content-Type: application/a2a+json

{
  "name": "AgentCard.net Toolkit",
  "version": "1.0.0",
  "supportedInterfaces": [
    { "url": "https://www.agentcard.net/api/agent-card",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0" }
  ],
  "skills": [
    { "id": "generate-agent-card", ... },
    { "id": "validate-agent-card", ... },
    { "id": "check-well-known-discovery", ... }
  ]
}

Caminhos de descoberta

Duas convenções, um só Agent Card.

Abrir validador completo
Padrão A2A v1.0

/.well-known/agent-card.json

O URI well-known registrado pela especificação A2A v1.0. Clientes novos buscam primeiro este caminho; sirva-o com o tipo de conteúdo application/a2a+json.

Legado (pré-v1.0)

/.well-known/agent.json

Usado por implementações A2A antigas e exemplos de codelabs. Muitos clientes implantados ainda verificam apenas este caminho, então servir o mesmo Agent Card aqui é uma estratégia de transição segura.

Padrão de publicação

Torne a descoberta do Agent Card resiliente.

Falhas de descoberta raramente são exóticas: um redirecionamento, uma página de erro em cache, ou um caminho implantado e o outro esquecido. Esta rotina de publicação mantém ambas as convenções servindo o mesmo Agent Card atualizado.

  1. 1

    Publicar no caminho padrão

    Sirva o Agent Card revisado em /.well-known/agent-card.json via HTTPS no mesmo domínio do serviço A2A, com o tipo de conteúdo application/a2a+json.

  2. 2

    Espelhar o caminho legado

    Retorne o documento idêntico em /.well-known/agent.json enquanto clientes mais antigos ainda estiverem em circulação — Agent Cards divergentes nos dois caminhos confundem o roteamento.

  3. 3

    Manter o Agent Card sincronizado

    Sempre que endpoints, skills, capacidades ou autenticação mudarem, atualize o Agent Card, incremente seu campo version e reimplante ambos os caminhos juntos.

  4. 4

    Reverificar após cada mudança

    Execute este verificador após implantações, mudanças de DNS, migrações de gateway ou edições de marketplace. As falhas geralmente vêm de redirecionamentos, páginas de erro HTML, ou um caminho esquecido.

Perguntas frequentes

Perguntas frequentes sobre Well-known Agent JSON

O que publicar, onde publicar e como manter clientes de ambas as convenções funcionando.

Qual caminho de Agent Card well-known devo usar?

A2A v1.0 registra /.well-known/agent-card.json como o caminho de descoberta padrão. O antigo /.well-known/agent.json é anterior à v1.0, mas ainda é verificado por muitos clientes implantados, então publicar o mesmo Agent Card em ambos os caminhos é a escolha pragmática durante a transição.

Ambos os caminhos devem retornar JSON idêntico?

Sim. Retornar o mesmo Agent Card público de ambos os caminhos mantém consistentes os clientes que suportam apenas uma convenção. Documentos divergentes fazem o agente parecer diferente dependendo de qual caminho o cliente busca.

Com qual tipo de conteúdo o Agent Card deve ser servido?

A especificação registra application/a2a+json para Agent Cards. O application/json simples é amplamente aceito na prática, mas um tipo de conteúdo HTML é um sinal confiável de que o caminho está retornando uma página de erro em vez do Agent Card.

O Agent Card público pode esconder capacidades privadas?

Sim. Publique apenas metadados seguros para descoberta no Agent Card público, defina capabilities.extendedAgentCard como true, e exponha skills sensíveis através da operação autenticada GetExtendedAgentCard.

Por que as verificações de descoberta falham após uma implantação?

As causas comuns são redirecionamentos para uma página de login ou marketing, páginas HTML 404 retornadas com status 200, JSON desatualizado em cache de um CDN, ou apenas um dos dois caminhos well-known implantado. O verificador relata o código de status e o tipo de conteúdo de cada caminho, tornando a falha visível imediatamente.

Antes de publicar

Valide o Agent Card, depois verifique as URLs.

Passe primeiro o JSON pelo validador completo, publique-o em ambos os caminhos well-known e confirme a descoberta com este verificador.

Abrir o validadorGerar um Agent Card