Scoperta pubblica dell'agente
Usa questi esempi per definire il JSON che un altro client A2A recupera prima di decidere se il tuo agente può completare un'attività.
6 modelli JSON pronti da copiare · A2A v1.0
Esempi di A2A Agent Card
Sfoglia modelli pratici A2A v1.0, comprendi le loro decisioni di design, poi adatta qualsiasi esempio per il tuo agente.
Invio al marketplace
Adatta provider, skill, tag, capabilities, e metadati di sicurezza affinché i revisori capiscano cosa fa l'agente e chi lo gestisce.
Cataloghi interni di agenti
Standardizza le descrizioni di endpoint, autenticazione, e skill tra gli agenti interni prima che i team li integrino nei flussi di lavoro.
Modelli JSON
Agent Card di esempio per agenti di supporto, prenotazione, shopping, codifica, ricerca, e flusso di lavoro.
Filtro
Agente di Supporto Clienti
Gestisce domande sui prodotti, ricerche ordini, resi, ed escalation.
Perché è costruito così
- Le credenziali client OAuth 2.0 proteggono i dati degli ordini: la Agent Card dichiara l'URL del token e lo scope in modo che i client possano autenticarsi senza documentazione fuori banda.
- streaming e pushNotifications sono entrambi true perché le conversazioni di supporto sono di lunga durata e gli aggiornamenti di risoluzione arrivano in modo asincrono.
- L'unica skill è limitata a un singolo confine di attività (classificare, risolvere, escalare) invece di una descrizione vaga "aiutare i clienti", così i router possono farla corrispondere con precisione.
{
"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"
]
}
]
}Agente di Prenotazione
Trova slot di appuntamento disponibili e prepara conferme di prenotazione.
Perché è costruito così
- Una chiave API in un header è sufficiente qui: le prenotazioni sono a livello di tenant ma non comportano il problema del consenso utente delegato che OAuth risolve.
- defaultOutputModes è solo application/json, segnalando che i chiamanti ottengono proposte di prenotazione strutturate invece di prosa.
- pushNotifications è true così l'agente può confermare una prenotazione dopo che il backend che mantiene lo slot si stabilizza, senza che il client debba fare polling.
{
"name": "Agente di Prenotazione",
"description": "Cerca la disponibilità, propone opzioni di prenotazione e prepara le prenotazioni degli appuntamenti per l'approvazione.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "Trova e prepara la prenotazione",
"description": "Controlla la disponibilità delle risorse, confronta le finestre di prenotazione e restituisce una proposta di prenotazione strutturata.",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"Trova un appuntamento di 30 minuti domani pomeriggio."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente di Shopping
Confronta prodotti, disponibilità, prezzi, e vincoli di acquisto.
Perché è costruito così
- Le raccomandazioni classificate arrivano in streaming man mano che vengono calcolate, quindi streaming è true mentre pushNotifications rimane false — non succede nulla dopo che la risposta è completa.
- La descrizione della skill si impegna a restituire compromessi e motivazioni, il che dice agli orchestratori che questo agente spiega le classifiche invece di limitarsi a elencare i prodotti.
- Gli scope OAuth regolano i dati relativi all'acquisto; una demo pubblica di shopping potrebbe eliminare completamente la sicurezza e rimanere comunque una Agent Card valida.
{
"name": "Agente di Shopping",
"description": "Confronta i prodotti con i vincoli dell'utente e restituisce le opzioni di acquisto classificate con i compromessi.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "Confronta le opzioni di acquisto",
"description": "Valuta i prodotti candidati, filtra in base ai vincoli e restituisce consigli classificati con motivazione.",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"Confronta laptop leggeri sotto i $ 1.200."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Agente di Programmazione
Rivede attività di codice, propone patch, e spiega le decisioni di implementazione.
Perché è costruito così
- extendedAgentCard è true: la Agent Card pubblica elenca una skill generica "implementa modifica del codice", mentre le skill specifiche del repository vengono rivelate solo ai client autenticati tramite GetExtendedAgentCard.
- Sono dichiarati sia output text/plain che application/json perché l'agente restituisce spiegazioni leggibili dall'uomo insieme a patch applicabili dalla macchina.
- Lo streaming è importante per lunghi cicli di compilazione e test; i client vedono progressi intermedi invece di una chiamata silenziosa di più minuti.
{
"name": "Agente di Programmazione",
"description": "Assiste nelle attività di ingegneria del software analizzando il codice, proponendo modifiche e restituendo note di implementazione.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "Implementare la modifica del codice",
"description": "Legge una richiesta di codifica, ispeziona i file rilevanti, restituisce una proposta di patch e riepiloga i passaggi di verifica.",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"Aggiungi l'impaginazione all'API degli utenti."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Agente di Ricerca
Raccoglie fonti, estrae prove, e restituisce note di ricerca strutturate.
Perché è costruito così
- Nessun securitySchemes affatto: l'endpoint è intenzionalmente pubblico, e omettere il campo è il modo corretto per dirlo — una mappa di schemi vuota sarebbe ambigua.
- L'input è solo text/plain, perché i brief di ricerca iniziano da domande in linguaggio naturale; l'output strutturato arriva come note application/json.
- Questa è la Agent Card v1.0 minima utile: identità, un'interfaccia, capabilities, modalità, e una skill ben taggata.
{
"name": "Agente di Ricerca",
"description": "Raccoglie materiale originale, estrae prove e produce note di ricerca strutturate con citazioni.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "Preparare un brief di ricerca",
"description": "Cerca fonti approvate, estrae affermazioni e prove e restituisce un breve riepilogo della ricerca.",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"Preparare un brief citato sulla politica delle energie rinnovabili."
]
}
]
}Agente di Flusso di Lavoro Interno
Coordina approvazioni, controlli di stato, e aggiornamenti del flusso di lavoro back-office.
Perché è costruito così
- application/json è l'unica modalità di input e output: questo agente viene chiamato da altri sistemi, mai da persone che digitano prosa.
- OAuth 2.0 più extendedAgentCard si adatta agli audit aziendali — i team di sicurezza possono vedere pubblicamente i requisiti di autenticazione mentre le skill sensibili del flusso di lavoro rimangono dietro l'autenticazione.
- pushNotifications è essenziale perché le catene di approvazione richiedono ore o giorni; i webhook sostituiscono il polling per i cambiamenti di stato.
{
"name": "Agente di Flusso di Lavoro Interno",
"description": "Coordina le approvazioni interne, controlla lo stato del sistema e prepara gli aggiornamenti del flusso di lavoro per i team operativi.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Esempio Inc.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "Coordinare il flusso di lavoro interno",
"description": "Riceve l'intento del flusso di lavoro, controlla i requisiti delle policy, raccoglie le approvazioni e segnala lo stato finale.",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"Richiedere l'approvazione per distribuire l'aggiornamento del libro paga."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Adatta con fiducia
Come adattare un esempio di Agent Card
Ogni esempio di Agent Card è intenzionalmente abbastanza completo da copiare, ma la Agent Card non dovrebbe essere pubblicata invariata. Trattala come una mappa dei campi per il tuo server A2A: sostituisci identità, endpoint, provider, autenticazione, capabilities, modalità, e dettagli delle skill con valori di produzione.
Gli Agent Card più forti spiegano il confine dell'attività dell'agente sia in linguaggio semplice che in metadati leggibili dalla macchina. Un client dovrebbe essere in grado di capire cosa può fare l'agente, cosa non può fare, quale URL chiamare, e se sono richieste credenziali.
Prima di pubblicare
Sostituisci ogni URL example.com con il tuo endpoint A2A distribuito e il sito web del provider.
Riscrivi il nome della skill, la descrizione, i tag (richiesti in v1.0), e gli esempi per il confine di attività effettivo.
Imposta provider.organization e incrementa la version di primo livello ogni volta che il contenuto della Agent Card cambia.
Rimuovi i campi di autenticazione solo quando l'endpoint è intenzionalmente pubblico.
Mantieni defaultInputModes e defaultOutputModes allineati con ciò che il tuo server accetta e restituisce effettivamente.
Convalida il JSON finale e pubblicalo su /.well-known/agent-card.json sul dominio del tuo servizio.
Pronto a costruire
Inizia con un esempio, poi rendilo tuo.
Apri qualsiasi pattern nel Generatore di Agent Card, rivedi il JSON, e convalidalo prima di pubblicare.