Il Validatore di Agent Card controlla JSON incollato, file di Agent Card caricati, e URL pubblici di agenti rispetto ai requisiti di discovery A2A v1.0.
Incolla JSON, l'URL di un agente pubblico o trascina un file JSON nell'editor.
Copertura del Validatore di Agent Card
Il Validatore di Agent Card è progettato per sviluppatori che pubblicano agenti A2A, team di piattaforma interni che revisionano i metadati degli agenti, e operatori di marketplace che verificano se una Agent Card inviata contiene informazioni sufficienti per un'invocazione affidabile.
Incolla un documento JSON locale durante lo sviluppo, carica una Agent Card dal tuo repository, o usa la validazione URL live contro un dominio distribuito per verificare i percorsi di scoperta pubblici.
Controlla i campi richiesti rispetto alla specifica v1.0: name, description, version, supportedInterfaces con protocolBinding e protocolVersion per interfaccia, capabilities, modalità di contenuto, e almeno una skill con i tag richiesti.
Rileva strutture precedenti a v1.0 — url di primo livello, preferredTransport, protocolVersion, provider.name, stateTransitionHistory — e ti dice esattamente dove ogni campo si è spostato in v1.0.
Verifica che securitySchemes e i requisiti di sicurezza siano dichiarati per gli endpoint non pubblici, segnala gli URL non-HTTPS, e cerca valori che sembrano chiavi API, JWT, o token bearer incorporati.
Recupera /.well-known/agent-card.json e il vecchio /.well-known/agent.json da un dominio live e conferma che entrambi restituiscono JSON di Agent Card analizzabile.
Dove si inserisce la validazione
Una Agent Card che ha superato la revisione il mese scorso può ancora rompere la scoperta oggi — un endpoint si sposta, una skill cambia, un redeploy elimina la rotta well-known. I team di piattaforma e i revisori di marketplace trattano la validazione come un gate ripetibile, non un controllo una tantum.
La protezione CI più semplice non ha bisogno di altro che curl: conferma che il percorso well-known risponda con JSON analizzabile prima che il traffico passi a un nuovo deployment.
# deploy pipeline: fail if the published card breaks
curl -fsS https://your-domain/.well-known/agent-card.json \
| python3 -c '
import json, sys
card = json.load(sys.stdin)
assert card.get("name"), "name is required"
assert card.get("supportedInterfaces"), "supportedInterfaces missing"
assert card.get("skills"), "skills missing"
print("agent card OK:", card["name"])'Guida alle correzioni
Usa il report del Validatore di Agent Card per affrontare prima i campi richiesti, poi migliora i dettagli di scoperta, fiducia, e migrazione.
Sostituisci gli URL endpoint segnaposto con l'URL del servizio A2A HTTPS distribuito.
Sposta url e preferredTransport di primo livello in un array supportedInterfaces ordinato — la prima voce è l'interfaccia preferita.
Aggiungi il campo version di primo livello richiesto che descrive l'agente stesso, e aggiungi tag a ogni skill.
Rinomina provider.name in provider.organization ed espandi le descrizioni brevi in modo che i client sappiano quando invocare l'agente.
Dichiara metadati di sicurezza ogni volta che l'endpoint dell'agente non è completamente pubblico — e non incorporare mai la credenziale stessa.
Pubblica lo stesso Agent Card valido su /.well-known/agent-card.json (e sul vecchio percorso agent.json finché i client controllano ancora entrambi).
FAQ
Sistema gli elementi essenziali prima che il tuo agente raggiunga un client A2A.
Confronta esempi validiI controlli seguono la struttura Agent Card A2A v1.0 — supportedInterfaces, versioni di protocollo per interfaccia, tag delle skill richiesti, provider.organization. Le Agent Card precedenti a v1.0 non vengono rifiutate direttamente: i campi legacy compaiono come avvisi con l'esatta sostituzione v1.0.
La specifica v1.0 registra /.well-known/agent-card.json, ma le implementazioni A2A precedenti usavano /.well-known/agent.json. Controllare entrambi rileva le lacune di scoperta prima che i client falliscano.
Gli avvisi non bloccano come errori JSON, ma di solito indicano metadati che rendono l'agente più facile da scoprire, di cui fidarsi, e da chiamare — o campi precedenti a v1.0 che i client più recenti smetteranno di leggere.
Tre momenti: durante la modifica di una Agent Card in sviluppo, come gate CI prima del deployment, e dopo la pubblicazione — incolla l'URL del servizio live per confermare cosa i client ricevono effettivamente da entrambi i percorsi di scoperta.
Pronto a validare
Incolla JSON, rilascia un file di Agent Card, o controlla un URL pubblico dallo spazio di lavoro unificato del validatore.