Introduzione

Tra una cosa e l’altra, in queste incandescenti giornate di agosto, ne ho approfittato per leggere bene la specifica del protocollo A2A di Google e provare a capire come utilizzarne i concetti per disegnare una un’architettura enterprise di Agenti, possibilmente slegata da vincoli di piattaforma tecnologica.

Che cos’è A2A?

Il Protocollo Agent2Agent (A2A) è uno standard aperto progettato e condiviso pubblicamente da Google per facilitare la comunicazione e la collaborazione degli agenti AI. La standardizzazione del modello di interoperabilità dell’AI è un tema di cui si parla già dai primissimi momenti in cui si è iniziato a parlare di Agenti ed i motivi sono diversi:

• estrema eterogeneità, sia in termini di implementazione, di funzionalità e di modello d’ingaggio ed esecuzione dei task
• la tendenza verso la specializzazione fa sì che l’esecuzione di task complessi necessiterà di collaborazione tra Agenti in maniera sempre più pressante
• molte aziende hanno già sviluppato le prime soluzioni agentiche, ma per poterle scalare ed estenderle a nuovi contesti, è fondamentale avere un modello di interoperabilità future-proof e aperto. In assenza di uno standard condiviso e stabile, esiste un concreto rischio di lock-in.

A2A identifica 5 elementi fondamentali per risolvere questi problemi:

Il protocollo di trasporto

A2A prevede 3 protocolli di trasporto alternativi, tutti basati su HTTPS e stabilisce che un agente A2A-compliant debba necessariamente implementarne almeno uno di essi

1. JSON-RPC 2.0
2. gRPC
3. HTTP+JSON/REST

Le Agent Card

Si tratta dello strumento principale per condividere le caratteristiche tecniche e funzionali degli agenti secondo uno schema standard definito in linguaggio JSON. Le “Agent Card” sono come una sorta di interface agreement esposto dall’agente che, oltre a definire i puntamenti e i tecnicismi per l’autenticazione e l’interoperabilità, definisce anche in maniera descrittiva lo scopo dell’agente e le sue capabilities (es: supporto allo streaming o push notifications). A2A impone che ogni agente debba sempre esporre la propria Agent Card in modo che possa essere facilmente scoperta e utilizzata da altri agenti e client.

In un contesto multi-agente, una determinata organizzazione deve dunque fare 2 cose:

1. definire un modo per esporre queste “Agent Card” (come vedremo, A2A suggerisce l’utilizzo di un Well-known URI secondo lo standard RFC 8615)
2. conoscere in ogni momento quali sono le AgentCard a disposizione dell’organizzazione, sapere dove trovarle e magari anche lo stato di salute (healthy/inactive)

Questi 2 punti possono essere sintetizzati tramite il concetto di Discovery che a mio avviso non è affrontato in maniera esaustiva nelle specifiche ufficiali. Queste riflessioni mi hanno portato a considerare l’implementazione di un Agent Registry home-made.

Il ciclo di vita dei task

A2A classifica le tipologie di task e ne definisce il ciclo di vita. Ad esempio, un task potrebbe completarsi con un singolo messaggio di risposta (stateless) oppure, più frequentemente, essere un oggetto stateful che transita attraverso diversi stati. I client possono dunque far riferimento ad un task attraverso un taskId restituito dall’agente per tutto il ciclo di vita che può anche essere di lunga durata o richiedere più interazioni. Similmente, A2A prevede che nel primo messaggio di risposta, l’agente fornisca anche un contextId per gestire il riferimento al contesto del modello LLM sottostante. La cosa interessante è che il contextId può anche andare oltre il ciclo di vita del singolo task. In questa maniera, i client hanno la possibilità di scomporre autonomamente alcuni processi complessi in task più semplici ed autoconsistenti che però fanno riferimento al medesimo contesto conosciuto e memorizzato dall’agente.

Interscambio di dati

A2A fa una distinzione tra:

• Messages: rappresentano una singola interazione o un’informazione contestuale tra un client e un agente. I messaggi indicano sempre il ruolo del sender (user oppure agent) e vengono utilizzati per istruzioni, prompt, risposte e aggiornamenti di stato.
• Artifacts: rappresentano il vero output del task e vengono dunque generati alla fine dell’esecuzione

Sia i messaggi che gli artefatti sono composti da unità atomiche denominate part, ciascuna delle quali può essere di tipo TextPart, FilePart o DataPart e può contenere anche metadati che aiutano a descriverne il contenuto.

Sicurezza e gestione delle interazioni asincrone

Gli agenti devono autenticare tutte le richieste, in conformità con le specifiche definite nel SecurityScheme della propria AgentCard. A2A prevede che i server possano implementare l’autenticazione tramite i metodi più comuni come, ad esempio:

• OAuth 2.0
• API Key
• OpenAI
• HTTP Basic Auth
• Mutual TLS (mTLS)

Il tema della sicurezza è importante anche per quel che riguarda le Push Notifications, ovvero quel meccanismo che consente agli agenti di inviare aggiornamenti ai client in modo proattivo, tramite la predisposizione da parte dei client di un Webhook dedicato. A2A prevede un processo di Webhook validation, al fine di evitare attacchi di tipo SSRF.

Agent Discovery

Approcci per la Agent Discovery previsti in A2A

Come accennato prima, secondo A2A ogni agente deve produrre una Agent Card secondo le specifiche indicate dal protocollo stesso. Questo documento è dunque di fondamentale importanza per la fase di Agent Discovery, la quale può essere implementata almeno in uno di questi 3 modi (ma A2A lascia spazio anche ad altre alternative):

1. Utilizzo di Well-Known URI: Segue i principi dell’ RFC 8615 secondo cui viene riservato un percorso particolare (".well-known") all’interno degli URI per la condivisione di metadati su una specifica risorsa web. In altre parole, a partire da un dominio (es: www.example.com) e da una risorsa esposta all’interno del dominio (es: “my_resource”), lo standard RFC 8615 definisce il concetto di “Well Known URI” per la risorsa uguale a http://www.example.com/.well-known/my_resource. Secondo il protocollo A2A, le AgentCard potrebbero dunque essere esposte nativamente da parte degli Agent Server tramite degli URI tipo: https://{server_domain}/.well-known/agent-card.json (vedi Sezione 5.3).
2. Agent Registry: Interrogazione di un catalogo centralizzato di agenti, che può essere pubblico o privato.
3. Configurazione diretta: Le applicazioni client possono tranquillamente essere pre-configurate con tutte le informazioni presenti nella Agent Card degli Agent Server a cui deve accedere (per esempio con un inserimento diretto della AgentCard nel codice applicativo).

Breve confronto

Facendo riferimento alle 3 modalità di cui sopra, la terza mi sembra un brutale hard-coding di configurazioni punto-punto ed è sicuramente non elegante e non scalabile. La soluzione 1 è un mero tecnicismo che rimanda semplicemente ad uno standard per l’integrazione tra sistemi nel WEB e di per sè non risolve in alcun modo il problema, perché le applicazioni (o gli agenti) client non sanno a priori quali sono le risorse (ovvero gli Agenti) da ricercare e verso cui indirizzare le chiamate HTTP verso i percorsi “well-known”. A mio avviso, l’unica vera soluzione è la numero 2, ovvero l’utilizzo di un registro centralizzato, che consenta:

• agli Agenti: di essere condivisi e messi a disposizione dell’organizzazione
• ai client: di conoscere quali sono gli agenti a disposizione e le loro caratteristiche di interfaccia

Dal mio punto di vista, accanto a questi 2 macro-requisiti basilari, l’Agent Registry potrebbe anche fornire alcune funzionalità ausiliari per far funzionare tutto l’ecosistema A2A, come ad esempio:

• un meccanismo di healthcheck, per conoscere lo stato di salute dell’agente
• un motore di ricerca per skill, ma anche per capability, tags, descrizione o nome del provider, …
• regole di autorizzazione per la consultazione e l’accesso verso agenti
• acquisto diretto per accesso ad agenti “premium” (Agent Marketplace)

Tuttavia, A2A non definisce nulla di più in merito a come questi Agent Registry devono essere fatti e le specifiche che dovrebbero avere. Anzi, nella specifica del protocollo è scritto chiaramente

The A2A protocol does not currently define a standard API for such registries, though this is an area of potential future exploration and community standardization

Soluzioni aperte per l’Agent Registry

Volendo disegnare un’architettura agnostica e possibilmente “open”, ho fatto qualche ricerca per identificare eventuali tool di mercato che offrono questo tipo di funzionalità e, sorprendentemente, non ho trovato nulla. Anche nelle piattaforme leader di mercato, che promuovono lo sviluppo di architetture multi-agente e di applicazioni agentiche a livello enterprise, mi sembra (ma potrei sbagliarmi) che al momento non ci siano molti segnali di apertura verso questa parte del protocollo A2A. D’altro canto, mi sembra naturale che in questa fase di transizione i big del settore (hyperscalers e big tech) stiano cercando di creare un ecosistema chiuso, dove ogni cliente sviluppa, pubblica ed esegue i propri agenti. In questo scenario, è facile immaginare che ci sia una certa resistenza a standardizzare e aprire l’accesso ad Agent Registries veramente aperti ed interoperabili.

Fatte queste considerazioni, ho pensato: “ok ci metto un po’ di impegno, ma soprattutto un po’ di vibe-coding e me lo sviluppo da solo” 🛠️

Introduzione ad Agent-Reg

Che cos’è Agent-Reg?

Agent-Reg è una implementazione minimale ed open source di un Agent Registry, in maniera conforme alle specifiche A2A. Fornisce una soluzione centralizzata per la discovery e la manutenzione di agenti conformi ad A2A in un modo semplice ed interoperabile. Trovate il codice qui: Agent-Reg GitHub Repository

La soluzione può essere rilasciata ovunque ed è stata progettata mantenendo una completa apertura e indipendenza dalla piattaforma. Nel suo nucleo, Agent-Reg risolve il problema della Discovery attraverso:

• Universal Agent Discovery: Un catalogo ricercabile di tutti gli agenti disponibili
• A2A Protocol Compliance: Supporto per la specifica Agent2Agent e validazione completa in fase di registrazione
• Health Monitoring: Tracciamento real-time della disponibilità e dello stato degli agenti (heartbeat)
• Advanced Search: Ricerca multi-criterio per skill, capabilities, ownership e altri attributi descrittivi

Panoramica dell’Architettura

L’architettura è estremamente semplice e, anche se alcune scelte implementative non sono ancora ottimizzate per la scalabilità (per esempio, l’utilizzo di SQLite), fornisce una base di partenza su cui poter costruire le proprie customizzazioni.

Macrocomponenti

Backend

Il backend è stato sviluppato utilizzando FastAPI, un framework Python moderno che fornisce documentazione API automatica, validazione dei tipi ed eccellenti prestazioni. Altre caratteristiche di rilievo:

• SQLite with JSON extension per la memorizzazione dei dati: un database leggero e ultraconsolidato, con supporto NoSQL tramite JSON, che richiede zero configurazione infrastrutturale aggiuntiva, rendendo semplice il deployment e fornendo prestazioni sufficienti almeno per un PoC o un prototipo funzionante, in grado di gestire qualche migliaio di oggetti
• Strict A2A Schema Validation: Ogni registrazione di agente è validata rispetto allo schema ufficiale di A2A per garantire la conformità al protocollo
• RESTful API Design: Endpoint puliti e intuitivi che seguono le specifiche OpenAPI 3.0

Frontend

L’interfaccia web è costruita con React 18 e TypeScript, fornendo un’esperienza moderna e responsive per la gestione degli agenti:

• Tailwind CSS: Framework CSS semplice e pulito
• Real-time Updates: Monitoraggio live dello stato e salute degli agenti
• Advanced Filtering: Interfaccia di ricerca intuitiva con criteri multipli

Homepage di Agent-Reg

Come Funziona la Registrazione degli Agenti

Il processo di registrazione di un Agente su Agent-Reg assicura che solo gli agenti validi e conformi alle specifiche A2A possano unirsi al registry. Di seguito è riportato un diagramma di sequenza che illustra il flusso di registrazione end-to-end:

Quando un agente vuole registrarsi con Agent-Reg, deve fornire la sua Agent Card. La piattaforma esegue una validazione dell’Agent Card per garantire la conformità, rifiutando la richiesta qualora non siano soddisfatti i requisiti del protocollo. Qualora la validazione abbia esito positivo, l’agente viene registrato a sistema e viene dunque ritornato un identificativo univoco, che l’Agente può in seguito utilizzare per effettuare operazioni sul registro (es: heartbeat).

A livello di interfaccia frontend, la registrazione avviene caricando un’Agent Card o fornendo il percorso di rete verso il descrittore /.well-known/agent-card.json

Smart Agent Discovery

Agent-Reg fornisce un semplicissimo motore di ricerca che consente agli utenti di scoprire gli agenti di interesse in base a vari criteri. Il diagramma seguente illustra l’architettura del motore di ricerca e i filtri applicati:

Capacità di Ricerca

I criteri di ricerca sono dunque i seguenti:

• By Name: Ricerca testuale semplice basata sul nome dell’agente
• By Skills: Trova gli agenti che dichiarano skills specifiche (es. “route-planning”, “image-processing”, etc)
• By Capabilities: Filtra gli agenti basandosi sulle capabilities dichiarate nell’agent card secondo quanto previsto nel protocollo A2A (streaming, push notifications, etc)
• By Owner: Mostra gli agenti gestiti da team o organizzazioni specifiche
• By Liveness: Mostra solo gli agenti che sono attualmente attivi secondo l’heartbeat periodico.

Health Monitoring

In uno scenario realistico, gli agenti saranno molti e potenzialmente instabili a causa della loro continua evoluzione e manutenzione (basti pensare ad un cambio nel prompt o nel modello), ma anche a causa della complessa rete di dipendenze. Ad esempio, un Agente può dipendere da servizi o API esterni ma anche da altri Agenti. Agent-Reg prevede un meccanismo di heartbeat, dove gli agenti registrati notificano periodicamente al registry il loro stato di salute. Questo permette al registry di:

• Fornire ai client informazioni sullo stato di salute in tempo reale
• Filtrare automaticamente gli agenti non responsivi secondo quanto ritornato dai risultati di ricerca
• Abilitare il monitoraggio proattivo e l’alerting per agenti critici

Data Model e Conformità A2A

Agent-Reg aderisce alla specifica del protocollo A2A per la struttura delle agent card, ma è ovviamente un modello semplificato ed estendibile. Ad esempio, non include le definizioni specifiche dei SecurityScheme nelle sue 5 varianti. Di seguito un class diagram che illustra il modello dati logico:

Backend APIs

Agent-Reg fornisce una REST API completa con alcuni metodi che implementano le operazioni principali:

Esempio di Utilizzo nel Mondo Reale

Vediamo come Agent-Reg funziona nella pratica. Immagina di stare costruendo un’applicazione per la pianificazione di viaggi che ha bisogno di trovare un agente di pianificazione percorsi con capabilities di traffico real-time:

# Search for agents with route planning skills and streaming capability
curl "http://localhost:8000/agents?skill=route-optimizer-traffic&capabilities=streaming&only_alive=true"

Il registry restituirà solo agenti attivi che corrispondono a questi criteri, completi dei loro URL di invocazione, requisiti di sicurezza e dettagli delle capability.

A livello di interfaccia utente, è possibile fare la stessa cosa tramite la barra di ricerca.

Perché Agent-Reg?

Agent-Reg cerca di risolvere il problema della Discovery in un ecosistema di agenti basati sullo standard A2A e può essere potenzialmente utile anche per affrontare i temi di sicurezza e governance nelle applicazioni basate su agenti. Ho provato a sintetizzare i pillar principali su cui vorrei far evolvere il tool:

1. Interoperabilità: agenti eterogenei che aderiscono allo standard possono lavorare insieme senza necessità di collegamenti punto-punto o integrazioni complesse e ridondanti
2. Discovery: Le organizzazioni possono mantenere un catalogo completo e costantemente aggiornato dei loro Agenti
3. Affidabilità: Il meccanismo di heartbeat assicura che i client interagiscano solo con agenti responsivi
4. Scalabilità: L’architettura può gestire migliaia di agenti senza requisiti infrastrutturali complessi
5. Apertura: E’ una soluzione open-source, che può essere distribuita ovunque, previene il vendor lock-in e incoraggia l’innovazione

Come Iniziare

Agent-Reg manca ancora di diverse funzionalità ed ottimizzazioni necessarie prima di poterlo realmente usare in un ambiente produttivo (es: autenticazione ed autorizzazione, gestione degli errori, logging, notifiche, supporto ad altri NoSql DB, …), ma è una base su cui costruire un piccolo ecosistema aperto ed estendibile. Avviarlo è semplicissimo:

# Backend setup
cd backend/app
pip install -r requirements.txt
python src/main.py

# Frontend setup
cd frontend
npm install
npm start

Conclusioni

In questo periodo di forte dinamismo in ambito AI, il protocollo A2A fa un passo molto importante, perché mette a fattor comune alcuni concetti di base su cui poter costruire una reale standardizzazione, ma da questo punto di vista a mio avviso non siamo ancora in una fase di maturità. Le specifiche in sé non sono scritte male, ma sono abbastanza generiche (provate a fare il confronto con altri standard, tipo quello di HTTP/2 per capire cosa intendo…) e lasciano ancora molti spazi per estensioni o integrazioni. Uno dei punti importanti che mi sembra sia stato tralasciato è quello della Discovery, per cui ho cercato di immaginare una soluzione centralizzata e aperta.

La metto a disposizione della collettività, sperando che qualche volontario possa aiutarmi contribuendo al suo sviluppo! 😊