Utilizzare il protocollo A2A per la comunicazione con l'agente AI

Il protocollo A2A, o Agent2Agent, è uno standard aperto che consente la comunicazione strutturata tra agenti AI, client e strumenti. In questo tutorial, è possibile creare un sistema di agenti in cui un client di chat elabora le query degli utenti e le invia a un agente AI in esecuzione su un server compatibile con A2A.

La maggior parte delle applicazioni di agentic AI implementa una comunicazione personalizzata tra i componenti (ad esempio, ChatChain di ChatDev), rendendo difficile il riutilizzo dello stesso agente in diverse applicazioni o l'integrazione di strumenti esterni. Questa mancanza di standardizzazione impedisce l'interoperabilità e limita lo sviluppo di un ecosistema di agenti più ampio.

A2A risolve questa limitazione separando il livello di comunicazione dalla logica dell'agente attraverso un protocollo standardizzato basato su HTTP, JSON-RPC 2.0 e Server-Sent Events (SSE). Questo disaccoppiamento consente agli agenti di collaborare con altri agenti, soddisfare le richieste dei clienti e accedere a strumenti esterni senza codice di integrazione personalizzato.

A2A supporta architetture decentralizzate che consentono ai team di far evolvere i propri sistemi di AI in modo incrementale senza violare il codice del cliente. I team possono aggiornare gli strumenti, scambiare modelli o modificare il comportamento degli agenti mantenendo un'interfaccia coerente attraverso i workflow complessi.

Gli agenti si scambiano informazioni in messaggi strutturati nel formato JSON-RPC che includono metadati che arricchiscono le interazioni degli agenti con chiarezza e coerenza. Ogni server A2A espone una AgentCard a un endpoint noto (.well-known/agent-card.json) che descrive le funzionalità dell'agente come dati JSON strutturati. Pertanto, consente ai clienti di scoprire dinamicamente cosa può fare un agente, in modo simile a come la documentazione dell'API descrive gli endpoint disponibili.

Segui la creazione e l'esecuzione di un sistema di agenti A2A e acquisisci esperienza pratica con:

• BeeAI: un framework agentico open source per la creazione di agenti AI.
• Protocollo A2A: un protocollo di comunicazione standardizzato per l'interoperabilità degli agenti.
• Ollama: uno strumento per l'esecuzione di modelli linguistici di grandi dimensioni (LLM) in locale.
• Strumenti per agenti: funzionalità specializzate tra cui ricerca web (DuckDuckGo), dati meteorologici (OpenMeteo), accesso a Wikipedia (WikipediaTool) e ragionamento (ThinkTool)

Nota: se hai lavorato con ACP (Agent Communication Protocol), puoi riconoscere le somiglianze. ACP, originariamente sviluppato da BeeAI di IBM, ha unito le forze con Google A2A nell'ambito della Linux Foundation. BeeAI ora utilizza gli adattatori A2A (A2AServer e A2AAgent) per fornire comunicazioni conformi allo standard A2A. A2A collabora anche con MCP (Model Context Protocol) per consentire agli agenti di interagire con fonti e strumenti di dati, creando ecosistemi di agenti interoperabili.

Questo progetto dimostra come l'A2A consenta una separazione netta tra l'interfaccia client e la logica dell'agente.

Il workflow segue questa sequenza:

1. Input dell'utente: il client acquisisce gli input dell'utente tramite l'interfaccia del terminale.
2. Richiesta A2A: il client formatta l'input come payload di messaggi JSON-RPC e lo invia al server dell'agente.
3. Elaborazione dell'agente: il server inoltra la richiesta alRequirementAgent , che analizza l'attività ed esegue gli strumenti appropriati in base alle esigenze.
4. Risposta A2A : il server restituisce la risposta dell'agente come dati strutturati in formato JSON-RPC, trasmettendo i risultati in tempo reale man mano che vengono generati.
5. Visualizza: il client estrae e visualizza il testo della risposta nel terminale.

Questo workflow dimostra un modello riutilizzabile applicabile ai casi d'uso che richiedono una comunicazione strutturata client-agente come chatbot, sistemi di automazione, agenti di supporto clienti e assistenti di ricerca con orchestrazione degli strumenti.

Questo progetto utilizza un singolo Agente AI con molteplici funzionalità di strumenti. Nei sistemi più complessi, è possibile implementare più agenti specializzati, ciascuno focalizzato su domini o attività specifici.

RequirementAgent (BeeAI): un agente dichiarativo che seleziona e coordina dinamicamente più strumenti in base alla richiesta dell'utente. Utilizza:

• ThinkTool per il ragionamento e le operazioni logiche
• DuckDuckGoSearchTool per ricerche web
• OpenMeteoTool  per i dati meteo
• WikipediaTool per il reperimento di informazioni

Il server A2A (beeai-a2a-server/beeai_chat_server.py ) espone la funzionalità dell'agente tramite un'API HTTP. Gestisce tre responsabilità chiave:

1. Inizializzazione LLM: carica un modello linguistico locale attraverso Ollama

2. Configurazione dell'agente: crea un RequirementAgent con strumenti e memoria per gestire il ciclo di vita dell'agente.

3. Configurazione del server: espone l'agente tramite endpoint HTTP conformi a A2A

Il server espone automaticamente una AgentCard all'indirizzo /.well-known/agent-card.json che descrive le funzionalità dell'agente e aiuta a convalidarne le configurazioni.

Il client A2A (beeai-a2a-client/beeai_chat_client.py ) fornisce l'interfaccia utente e gestisce la comunicazione con il server utilizzando l'SDK A2A e la libreria asyncio di Python per la gestione asincrona dei messaggi.

Configurazione della connessione: crea una scheda client A2A

Ilurl specifica l'endpoint del server conforme ad A2A (impostazione predefinita:http://127.0.0.1:9999 ). Thememory memorizza la cronologia delle conversazioni localmente, consentendo al client di mantenere il contesto durante le interazioni e supportare attività di lunga durata.

Scambio di messaggi: invia prompt asincroni ed elabora le risposte:

IlA2AAgent è un adattatore lato client che astrae i dettagli della comunicazione JSON-RPC. Non è un agente autonomo: converte semplicemente l'input degli utenti in messaggi conformi ad A2A e gestisce le risposte del server, consentendo lo scambio di dati e l'observability senza interruzioni.

Ecco i requisiti di sistema per eseguire questo progetto:

• Sistema operativo: macOS, Linux o Windows
• Memoria (RAM): >= 8 GB (consigliato: 16 GB o più per l'esecuzione di LLM locali)
• Spazio su disco: >= 5 GB di spazio libero (consigliato: 10 GB o più per adattarsi all'ambiente Python e ai modelli locali)
• Versione Python: >= 3.11

Prima di iniziare, ecco una panoramica degli strumenti necessari per questo progetto:

• BeeAI: un kit di sviluppo di agenti open source per la creazione di agenti AI. BeeAI supporta diversi provider LLM, tra cui Ollama (utilizzato in questo tutorial), OpenAI e Anthropic.
• Ollama: per gestire LLM locali per potenziare l'agente AI.
• Protocollo A2A: integrato nel framework BeeAI per consentire una comunicazione strutturata tra client e server.
  
• Terminale o IDE: un terminale o un IDE come Visual Studio Code (suggerito per la gestione di più terminali e la visualizzazione dei log).
  
• Ambiente virtuale Python: per isolare le dipendenze tra client e server.

Questo progetto utilizza Ollama come fornitore di modelli per l'agente AI. Segui questi passaggi per configurare Ollama:

1. Scarica e installa Ollama:
   - Visita Ollama e installa l'applicazione per il tuo sistema operativo
2. Avvia il server Ollama 
   -   Apri un terminale ed esegui:
   ollama serve
3. Estrai il modello predefinito (richiede circa 5 GB di spazio su disco):
   
   ollama pull granite3.3:8b

Nota: puoi utilizzare qualsiasi modello compatibile con Ollama, impostando la variabile d'ambienteBEEAI_MODEL . Controlla la libreria dei modelli Ollama per i modelli disponibili e le loro dimensioni.

Per eseguire questo progetto, clona il repository GitHub utilizzando https://github.com/IBM/ibmdotcom-tutorials.git come URL HTTPS. Per i passaggi dettagliati su come clonare un repository, consulta la documentazione di GitHub.

Questo tutorial è reperibile all'interno della directory projects del repository.

All'interno di un terminale, vai alla directory di questo tutorial:

Questo progetto richiede due script Python separati per l'esecuzione simultanea, uno per il server e l'altro per il client. È necessario aprire due finestre o schede del terminale.

Tieni aperto il suo terminale attuale, poi apri un secondo terminale e assicurati che entrambi siano indirizzati nella directory di progetto corretta (la directory principalea2a_tutorial ).

Utilizzi un IDE?

Se stai usando un IDE come Visual Studio Code, puoi utilizzare la funzionalità di suddivisione del terminale per gestire più terminali fianco a fianco.

In alternativa, apri due finestre di terminale autonome e accedi in ciascuna alla directory del progetto.

Gli ambienti virtuali aiutano a mantenere separate e mantenute le dipendenze. Per mantenere separate le dipendenze tra server e client, crea un ambiente virtuale per ogni componente.

Per il server:

Vai alla directorybeeai-a2a-server :

Crea un ambiente virtuale con Python 3.11:

Attiva l'ambiente virtuale:

Nota per gli utenti Windows: usa venv\ Scripts\ activate per attivare l'ambiente virtuale.

Per il client:

Vai alla directorybeeai-a2a-client :

Crea e attiva un ambiente virtuale:

Installa le dipendenze richieste per ogni componente eseguendo questo codice in ogni terminale:

Puoi eseguirepip freeze nel terminale per verificare che l'ambiente sia aggiornato con le dipendenze.

Nel primo terminale, avvia il server dell'agente A2A:

Dovresti vedere:

Il server è ora in ascolto delle richieste in ingresso dall'applicazione client, pronto a supportare la comunicazione da agente ad agente.

Nell'altro terminale, avvia il client A2A:  

Questo dovrebbe richiedere l'input:

Digita un messaggio nel terminale client e premiEnter . L'agente elabora la query e risponde:

Nel terminale del server, puoi vedere i log del protocollo A2A che mostrano la comunicazione con le notifiche push:

La prima richiesta recupera l'oggetto AgentCard che descrive le funzionalità dell'agente. La seconda richiesta invia il tuo messaggio comeTextPart (un'unità di contenuto testuale all'interno del messaggio A2A) e riceve la risposta.

Nota: gli output degli LLM sono probabilistici e possono variare ogni volta che esegui il workflow, anche con lo stesso input.

Sperimenta con diversi tipi di query per testare i vari strumenti dell'agente:

• Ricerca sul web: "Cerca notizie recenti sull'intelligenza artificiale"
• Dati meteo: "Che tempo fa a Tokyo?".
• Wikipedia: "Parlami di quantum computing"
• Ragionamento: "Quali sono tre motivi per cui il cielo è blu?"

Accedi a https://0.0.0.0:9999/.well-known/agent-card.json nel tuo browser per visualizzareRequirementAgent di AgentCard.

Questo documento JSON descrive:

• Il nome dell'agente (RequirementAgent) e una breve descrizione delle sue funzionalità.
• I protocolli di comunicazione e i formati dei messaggi supportati
• Eventuali requisiti o vincoli

Questa AgentCard consente a qualsiasi cliente conforme ad A2A di scoprire e interagire con l'agente senza conoscere preventivamente i dettagli di implementazione.

In questo tutorial, hai creato un sistema di chat utilizzando un server di reclamo A2A che esponeva un'interfaccia strutturata per la comunicazione tra il client e l'agente. Separando il livello di messaggistica dalla logica interna, il protocollo Agent2Agent consente ai team di aggiornare le funzionalità degli agenti, scambiare modelli o modificare le configurazioni degli strumenti senza modificare il codice del client. Questa flessibilità è particolarmente utile quando si coordinano le attività che richiedono input, si monitora lo stato delle attività o si tratta di ogni operazione come un'unità di lavoro discreta.

L'A2A funziona definendo un formato di messaggio comune che qualsiasi componente conforme può comprendere, consentendo agli agenti autonomi di collaborare con altri agenti. La specifica del protocollo definisce il modo in cui i messaggi sono strutturati in formato JSON-RPC e arricchiti con metadati per garantire coerenza e chiarezza tra le interazioni.

Questo tutorial si basa sugli esempi fondamentali forniti dal repository di campioni A2A. Per ulteriori informazioni sull'implementazione originale, fai riferimento al file readme nel repository, che fornisce più contesto ed esempi per la creazione di sistemi conformi ad A2A.

Per le distribuzioni nel mondo reale, i server A2A possono implementare meccanismi di autenticazione per proteggere gli endpoint, utilizzare gli eventi inviati dal server per lo streaming delle risposte e scalare per gestire i workflow. Seguendo questo workflow, hai visto come un client a riga di comando può interagire con un agente AI attraverso un protocollo standardizzato, che consente all'agente AI di coordinare più strumenti e fornire risposte contestuali. Questo approccio dimostra la potenza dell'A2A nell'abilitare sistemi AI manutenibili, scalabili e flessibili.

Una volta terminati gli esperimenti con il sistema, segui questi passaggi per arrestare correttamente tutti i componenti in esecuzione:

In ogni finestra del terminale, premi Ctrl+C per interrompere il processo in esecuzione.

Dovresti vedere un output simile a questo:

Se il server non risponde o si blocca durante l'arresto, è possibile arrestarlo forzatamente:

Trova l'ID del processo (PID):

Identifica il PID del processo che stai tentando di interrompere.

Termina il processo:

Se necessario, ripeti questa procedura per ogni server.

Questo è tutto. Hai eseguito con successo un sistema di chat completo conforme ad A2A.