Riferimento schema · 14 fieldsA2A v1.0
Un Agent Card è il documento JSON standardizzato che indica ai client A2A chi è un agente, dove raggiungerlo, cosa può fare, e come è protetto l'accesso. Questo riferimento copre ogni campo v1.0 con tipi, requisiti, esempi, e gli errori che i validatori rilevano più spesso.
Come funziona la discovery
Un client A2A recupera la Agent Card dall'URI well-known, valuta skill, capacità, e requisiti di sicurezza rispetto al suo compito, quindi chiama l'interfaccia preferita — la prima voce in supportedInterfaces. Se capabilities.extendedAgentCard è true, i client autenticati possono richiedere una Agent Card più ricca tramite l'operazione GetExtendedAgentCard.
La specifica registra /.well-known/agent-card.json come posizione standard. I deployment v0.x più vecchi usavano /.well-known/agent.json, motivo per cui il nostro validatore controlla entrambi.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Riferimento campi
I flag obbligatori seguono le definizioni protobuf v1.0 nella specifica ufficiale. I link di ancoraggio rendono ogni campo citabile da issue, revisioni, e output CI.
Nome leggibile dall'uomo dell'agente.
Mostrato negli elenchi del marketplace e nelle interfacce client. Mantienilo breve e specifico — i client lo usano come etichetta principale quando confrontano agenti candidati.
Errore comune: Usare un nome generico come "AI Assistant" che non dà ai sistemi di routing nulla su cui differenziare.
"name": "Agente di pianificazione del percorso geospaziale"
Cosa fa l'agente e quando un altro agente dovrebbe chiamarlo.
Questo è il principale segnale in testo libero sia per gli integratori umani che per i router basati su LLM che decidono se il tuo agente è adatto a un compito. Indica il dominio del compito, le capacità chiave, e i limiti.
Errore comune: Descrizioni di una riga sotto i 20 caratteri. I router non possono abbinare ciò che non descrivi.
"description": "Fornisce servizi avanzati di pianificazione del percorso, analisi del traffico e generazione di mappe personalizzate."
Elenco ordinato di endpoint e binding di protocollo. La prima voce è preferita.
Nuovo in v1.0: sostituisce i vecchi campi di primo livello url, preferredTransport, e additionalInterfaces. Ogni voce dichiara il proprio url, protocolBinding (JSONRPC, GRPC, HTTP+JSON, o un URI di binding personalizzato), protocolVersion, e una chiave di routing tenant facoltativa — così un agente può servire più versioni di protocollo e trasporti simultaneamente.
Errore comune: Dichiarare un binding che il server non serve effettivamente a quell'URL — la specifica richiede che ogni voce sia accurata.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Chi gestisce l'agente: organizzazione e sito web.
Segnale di fiducia per marketplace e audit aziendali. v1.0 ha rinominato il campo name in organization; url è obbligatorio all'interno dell'oggetto quando presente.
Errore comune: Usare ancora provider.name (pre-1.0). I validatori che leggono Agent Card v1.0 non lo riconosceranno.
"provider": {
"organization": "Esempio Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}La versione dell'agente stesso, non del protocollo.
Permette ai client di rilevare quando una Agent Card è cambiata materialmente e rivalutare la compatibilità. Segui il tuo schema di rilascio, tipicamente semver.
Errore comune: Confonderlo con la versione del protocollo A2A — che ora risiede su ogni voce di supportedInterfaces.
"version": "1.2.0"
Link alla documentazione leggibile dall'uomo per l'agente.
Dà agli integratori un posto dove leggere il contratto API completo, i limiti di frequenza, e i termini che non appartengono a un documento di discovery.
Errore comune: Puntare a una homepage di marketing invece che alla documentazione tecnica.
"documentationUrl": "https://docs.example.com/agent"
Flag delle funzionalità del protocollo: streaming, pushNotifications, extensions, extendedAgentCard.
I client NON DEVONO chiamare funzionalità che non hai dichiarato — le chiamate di streaming non dichiarate restituiscono errori. extendedAgentCard: true annuncia una Agent Card autenticata più ricca tramite l'operazione GetExtendedAgentCard. v1.0 ha rimosso stateTransitionHistory.
Errore comune: Dichiarare streaming: true quando il server non ha un endpoint di streaming. I client lo chiameranno e falliranno.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Schemi di autenticazione nominati: chiave API, autenticazione HTTP, OAuth 2.0, OpenID Connect, o TLS reciproco.
Ogni schema nominato racchiude un oggetto schema concreto (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme). I client scoprono da qui come autenticarsi — le credenziali stesse vengono sempre ottenute fuori banda.
Errore comune: Incorporare una chiave API o un token reale nella Agent Card. Un Agent Card è un documento pubblico.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Quali schemi dichiarati (e scope) sono richiesti per chiamare l'agente.
Ogni voce mappa un nome di schema da securitySchemes agli scope di cui ha bisogno, rispecchiando il modello di requisito di sicurezza OpenAPI. Ometti entrambi i campi completamente per gli agenti intenzionalmente pubblici.
Errore comune: Dichiarare securitySchemes ma senza requisiti di security, lasciando che i client indovinino se l'autenticazione è imposta.
"security": [{ "google": ["openid", "profile", "email"] }]Tipi di media che l'agente accetta in tutte le skill.
Tipi MIME standard come text/plain, application/json, o image/png. Le singole skill possono sovrascrivere con i propri inputModes.
Errore comune: Omettere il campo. È obbligatorio in v1.0 — i client ne hanno bisogno per formare le richieste.
"defaultInputModes": ["application/json", "text/plain"]
Tipi di media che l'agente restituisce in tutte le skill.
Dice ai chiamanti se aspettarsi prosa, JSON strutturato, immagini, o file. Le skill possono sovrascrivere per skill con outputModes.
Errore comune: Elencare solo text/plain quando l'agente in realtà restituisce artefatti strutturati.
"defaultOutputModes": ["application/json", "image/png"]
Le capacità concrete in cui l'agente ha probabilità di successo.
Ogni skill richiede id, name, description, e tags; examples, modalità per skill, e sicurezza per skill sono facoltativi. Le skill sono l'unità di discovery — i router abbinano i compiti ad esse, quindi limita ciascuna a un unico confine di compito.
Errore comune: Skill senza tag. I tag sono diventati obbligatori in v1.0 e guidano il matching a livello di skill.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Ottimizzatore di percorso sensibile al traffico",
"description": "Calcola i percorsi di guida ottimali utilizzando il traffico in tempo reale...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Pianifica un percorso da A a B evitando i pedaggi."]
}]Firme JSON Web che dimostrano che la Agent Card è stata emessa dal provider.
Ogni firma porta un header JWS protetto base64url e un valore di firma, calcolato sulla Agent Card canonicalizzata RFC 8785 (JCS). I client DOVREBBERO verificare almeno una firma prima di fidarsi di una Agent Card recuperata dal web aperto.
Errore comune: Firmare la card e poi modificare qualsiasi campo — anche modifiche di valore insignificanti negli spazi bianchi invalidano il JWS.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]URL a un'icona che rappresenta l'agente.
Usata da cataloghi e interfacce client. Servila via HTTPS da una posizione stabile.
Errore comune: Collegare un'icona su un dominio diverso e non affidabile che può cambiare senza preavviso sotto il tuo annuncio.
"iconUrl": "https://agent.example.com/icon.png"
Migrazione di versione
Se la tua Agent Card ha ancora un url o preferredTransport di primo livello, è precedente a v1.0. Il validatore segnala automaticamente ciascuno di questi.
| Campo v0.x | Sostituzione v1.0 | Perché è cambiato |
|---|---|---|
| url | supportedInterfaces[0].url | L'endpoint preferito è ora semplicemente la prima voce di interfaccia. |
| preferredTransport | supportedInterfaces[] ordering | La preferenza è espressa dall'ordine dell'array invece che da un campo separato. |
| additionalInterfaces | supportedInterfaces[] | Tutte le interfacce vivono in un unico array ordinato. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Ogni interfaccia dichiara la propria versione del protocollo, abilitando il supporto multi-versione. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | Spostato nell'oggetto capabilities; l'RPC è stato rinominato in GetExtendedAgentCard. |
| provider.name | provider.organization | Rinominato per chiarezza. |
| capabilities.stateTransitionHistory | — removed | Non fa parte di v1.0; modella un comportamento equivalente come estensione se necessario. |
Boilerplate
Inserisci queste interfacce in un client, server, o controllo CI per analizzare e produrre Agent Card con sicurezza dei tipi. Rispecchiano le definizioni protobuf nel repository ufficiale della specifica, nella forma JSON camelCase in cui le Agent Card vengono pubblicate.
Stai costruendo una Agent Card a mano invece? Il generatore produce esattamente questa forma.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Integrità
Poiché gli Agent Card vengono recuperati dal web aperto, v1.0 formalizza la firma: la Agent Card (meno il campo signatures e i valori predefiniti) viene canonicalizzata con RFC 8785 JSON Canonicalization, poi firmata come JWS. I client dovrebbero verificare almeno una firma — tramite l'header kid/jku o un archivio chiavi affidabile — prima di agire su una Agent Card. Firme multiple supportano la rotazione delle chiavi.
Servi la Agent Card su /.well-known/agent-card.json via HTTPS.
Ogni voce di supportedInterfaces è raggiungibile e parla il binding dichiarato.
Le skill hanno i tag obbligatori più descrizioni con confini di compito chiari.
Le capabilities dichiarate corrispondono al server — le funzionalità non dichiarate devono restituire errori, quelle dichiarate devono funzionare.
securitySchemes descrive come autenticarsi; nessuna credenziale appare da nessuna parte nella Agent Card.
version viene incrementato ogni volta che il contenuto della Agent Card cambia.
Un agente di supporto clienti con OAuth 2.0, streaming, e notifiche push — tutti i campi richiesti presenti. Altri pattern si trovano nella libreria di esempi.
{
"name": "Agente di Supporto Clienti",
"description": "Risponde alle domande dell'assistenza clienti, recupera il contesto dell'ordine e inoltra i problemi irrisolti a un team umano.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Risolvere la richiesta di assistenza clienti",
"description": "Classifica una richiesta di assistenza clienti, raccoglie il contesto necessario, propone una soluzione e interviene quando la fiducia è bassa.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Aiutami a restituire il mio ordine."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}FAQ
I cambiamenti di versione, i campi di discovery, e i dettagli di pubblicazione che decidono se una Agent Card supera la revisione.
v1.0 ha consolidato url, preferredTransport, e additionalInterfaces in un unico array ordinato supportedInterfaces dove ogni voce dichiara il proprio url, protocolBinding, e protocolVersion. supportsAuthenticatedExtendedCard è passato a capabilities.extendedAgentCard, provider.name è diventato provider.organization, i tag delle skill sono diventati obbligatori, e le firme Agent Card JWS sono state formalizzate con la canonicalizzazione RFC 8785.
No. Un Agent Card è un documento di discovery per un agente. Riassume identità, interfacce, capacità, skill, modalità, provider, e metadati di sicurezza, mentre uno schema API completo descrive forme dettagliate di richiesta e risposta. Svolge il ruolo che un README o una panoramica OpenAPI svolgono per un servizio: sufficiente per decidere se e come chiamarlo.
name, description, supportedInterfaces, skills (con tag), defaultInputModes, defaultOutputModes, capabilities, provider, e metadati di sicurezza. I sistemi di routing abbinano i compiti alla tua description e ai tag delle skill, poi usano interfacce e capabilities per pianificare la chiamata effettiva.
Pubblica solo skill sicure per la discovery non autenticata. Se serve una Agent Card privata più ricca, imposta capabilities.extendedAgentCard su true ed esponi le skill sensibili tramite l'operazione autenticata GetExtendedAgentCard.
All'URI well-known https://{tuo-dominio}/.well-known/agent-card.json, servito con il content type application/a2a+json (application/json funziona anche in pratica). Le implementazioni precedenti usavano /.well-known/agent.json, quindi pubblicare entrambi durante la transizione è una scelta pragmatica.
Metti lo schema al lavoro
Genera una Agent Card con forma v1.0 dai dettagli del tuo servizio, o incollane una Agent Card esistente nel validatore per vedere esattamente quali campi necessitano attenzione.