Strumento di discovery · A2A v1.0

Controlla gli URL di discovery di A2A Agent Card

I client A2A scoprono un agente recuperando il suo Agent Card JSON da un URL well-known. Testa entrambe le convenzioni di denominazione su un dominio reale e osserva esattamente cosa ricevono i client.

Costruisce entrambi gli URL di discovery candidati dallo stesso dominio di base.

Recupera il JSON restituito e segnala codice di stato e content type.

Analizza la risposta come JSON di Agent Card quando possibile.

Esegue controlli di prontezza su interfacce, skill, provider, modalità, capacità e metadati di sicurezza.

Controlla un dominio agente pubblico

Inserisci un dominio di base. Il controllo recupera entrambi i percorsi di discovery, analizza il JSON restituito ed esegue controlli di prontezza dell'Agent Card.

Come funziona la discovery

Un solo URL well-known avvia ogni integrazione A2A.

Prima che un altro agente possa chiamare il tuo, recupera l'Agent Card da un URI well-known (RFC 8615) sul tuo dominio, valuta skill e requisiti di sicurezza, quindi chiama l'interfaccia preferita. Se la Agent Card manca, è obsoleta o nascosta dietro un redirect, l'integrazione fallisce prima ancora di iniziare.

Questo sito applica ciò che controlla: AgentCard.net pubblica la propria Agent Card su entrambi i percorsi, e l'esempio a destra è il documento reale.

Guarda il nostro Agent Card in tempo reale

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", ... }
  ]
}

Percorsi di discovery

Due convenzioni, una sola Agent Card.

Apri il validatore completo

Standard A2A v1.0

/.well-known/agent-card.json

L'URI well-known registrato dalla specifica A2A v1.0. I nuovi client recuperano prima questo percorso; servilo con content type application/a2a+json.

Legacy (pre-v1.0)

/.well-known/agent.json

Usato dalle prime implementazioni A2A ed esempi di codelab. Molti client distribuiti controllano ancora solo questo percorso, quindi servire la stessa Agent Card qui è una strategia di transizione sicura.

Modello di pubblicazione

Rendi resiliente la discovery di Agent Card.

I fallimenti di discovery raramente sono esotici: un redirect, una pagina di errore in cache, o un percorso distribuito e l'altro dimenticato. Questa routine di pubblicazione mantiene entrambe le convenzioni che servono la stessa Agent Card aggiornata.

1
Pubblica sul percorso standard
Servi l'Agent Card revisionata su /.well-known/agent-card.json via HTTPS sullo stesso dominio del servizio A2A, con content type application/a2a+json.
2
Rifletti il percorso legacy
Restituisci lo stesso documento identico da /.well-known/agent.json finché i client più vecchi sono ancora in circolazione — Agent Card divergenti sui due percorsi confondono il routing.
3
Mantieni la Agent Card sincronizzata
Ogni volta che endpoint, skill, capacità o autenticazione cambiano, aggiorna la Agent Card, incrementa il suo campo version e ridistribuisci entrambi i percorsi insieme.
4
Ricontrolla dopo ogni modifica
Esegui questo controllo dopo distribuzioni, cambi DNS, migrazioni di gateway o modifiche al marketplace. I fallimenti derivano solitamente da redirect, pagine di errore HTML, o un percorso dimenticato.

FAQ

Domande frequenti su Well-known Agent JSON

Cosa pubblicare, dove pubblicarlo e come mantenere funzionanti i client di entrambe le convenzioni.

Quale percorso well-known di Agent Card dovrei usare?

A2A v1.0 registra /.well-known/agent-card.json come percorso di discovery standard. Il vecchio /.well-known/agent.json precede la v1.0 ma è ancora controllato da molti client distribuiti, quindi pubblicare la stessa Agent Card su entrambi i percorsi è la scelta pragmatica durante la transizione.

Entrambi i percorsi dovrebbero restituire JSON identico?

Sì. Restituire lo stesso Agent Card pubblico da entrambi i percorsi mantiene coerenti i client che supportano una sola convenzione. Documenti divergenti fanno apparire l'agente diverso a seconda del percorso che il client recupera.

Con quale content type dovrebbe essere servito l'Agent Card?

La specifica registra application/a2a+json per gli Agent Card. Il semplice application/json è ampiamente accettato in pratica, ma un content type HTML è un segno affidabile che il percorso sta restituendo una pagina di errore anziché la Agent Card.

L'Agent Card pubblico può nascondere capacità private?

Sì. Pubblica nella Agent Card pubblica solo metadati sicuri per la discovery, imposta capabilities.extendedAgentCard su true, ed esponi le skill sensibili tramite l'operazione autenticata GetExtendedAgentCard.

Perché i controlli di discovery falliscono dopo una distribuzione?

Le cause comuni sono redirect verso una pagina di login o marketing, pagine HTML 404 restituite con stato 200, JSON obsoleto in cache su una CDN, o solo uno dei due percorsi well-known distribuito. Il controllo segnala codice di stato e content type per ogni percorso, così il fallimento è visibile immediatamente.

Prima di pubblicare

Convalida la Agent Card, poi controlla gli URL.

Fai passare prima il JSON nel validatore completo, pubblicalo su entrambi i percorsi well-known e conferma la discovery con questo controllo.

Apri il validatore Genera una Agent Card