Questa pagina è stata tradotta dall'API Cloud Translation.

Crea un sistema multi-agente con ADK, esegui il deployment in Agent Engine e inizia a utilizzare il protocollo A2A

1. Obiettivo di questo lab

In questo lab pratico creerai un'applicazione multiagente che genera un'immagine in base al prompt e la valuta in base al prompt. Se l'immagine non soddisfa in modo soddisfacente i requisiti descritti nel prompt, l'agente genererà continuamente immagini finché non verrà generata l'immagine che soddisfa i tuoi requisiti. Ognuno degli agenti di questo esercizio pratico ha un unico scopo e collabora con gli altri per raggiungere l'obiettivo generale.

Obiettivi didattici

Comprendi le nozioni di base dell'ADK e scopri come creare un sistema multi-agente.
Scopri come eseguire facilmente il deployment e utilizzare gli agenti in Google Cloud.
Comprendere le nozioni di base del protocollo A2A
Scopri come utilizzare insieme il protocollo A2A e ADK per creare agent aperti.

2. Prima di iniziare

Se non hai già un progetto che puoi utilizzare, dovrai crearne uno nuovo nella console GCP.
In questo lab utilizzeremo GCP Cloud Shell per eseguire le nostre attività. Apri Cloud Shell e imposta il progetto utilizzando Cloud Shell.
Apri l'editor di Cloud Shell di GCP premendo il pulsante dell'editor di Cloud Shell. Se viene visualizzato il popup "Autorizza shell", fai clic per autorizzare l'editor di Cloud Shell.
Puoi verificare se il progetto è già autenticato utilizzando il seguente comando.

gcloud auth list

Esegui questo comando in Cloud Shell per confermare il tuo progetto

gcloud config list project

Se il progetto non è impostato, utilizza il seguente comando per impostarlo

gcloud config set project <YOUR_PROJECT_ID>

Per eseguire questo lab, dobbiamo abilitare alcuni servizi. Esegui questo comando in Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Panoramica: vantaggi di Agent Development Kit

Agent Development Kit offre diversi vantaggi chiave per gli sviluppatori che creano applicazioni agentiche:

Sistemi multi-agente: crea applicazioni modulari e scalabili componendo più agenti specializzati in una gerarchia. Consente un coordinamento e una delega complessi.
Ecosistema di strumenti avanzati: dota gli agenti di diverse funzionalità: utilizza strumenti predefiniti (Ricerca, Esecuzione di codice e così via), crea funzioni personalizzate, integra strumenti di framework di agenti di terze parti (LangChain, CrewAI) o utilizza altri agenti come strumenti.
Orchestrazione flessibile: definisci i workflow utilizzando gli agenti di workflow (SequentialAgent, ParallelAgent e LoopAgent) per pipeline prevedibili oppure sfrutta il routing dinamico basato su LLM (trasferimento LlmAgent) per un comportamento adattivo.
Esperienza per sviluppatori integrata: sviluppa, testa ed esegui il debug in locale con una potente CLI e una UI di sviluppo interattiva. Esamina gli eventi, lo stato e l'esecuzione passo passo dell'agente.
Valutazione integrata: valuta sistematicamente le prestazioni dell'agente valutando sia la qualità della risposta finale sia la traiettoria di esecuzione passo passo rispetto a scenari di test predefiniti.
Pronto per il deployment: inserisci i tuoi agenti in un container ed esegui il deployment ovunque: esegui localmente, esegui lo scale con Vertex AI Agent Engine o esegui l'integrazione nell'infrastruttura personalizzata utilizzando Cloud Run o Docker.

Sebbene altri SDK di AI generativa o framework di agenti ti consentano anche di eseguire query sui modelli e persino di potenziarli con strumenti, il coordinamento dinamico tra più modelli richiede un notevole impegno da parte tua.

L'Agent Development Kit offre un framework di livello superiore rispetto a questi strumenti, consentendoti di collegare facilmente più agenti tra loro per workflow complessi ma facili da gestire.

4. Introduzione ad A2A

Il protocollo Agent2Agent (A2A) è uno standard aperto progettato per consentire una comunicazione e una collaborazione fluide e sicure tra agenti di AI autonomi di framework, fornitori e domini diversi.

Interoperabilità universale:A2A consente agli agenti di lavorare insieme indipendentemente dalle tecnologie sottostanti, promuovendo un ecosistema veramente multi-agente. Ciò significa che gli agenti creati da aziende diverse su piattaforme diverse possono comunicare e coordinarsi.
Rilevamento delle funzionalità:gli agenti possono pubblicizzare le proprie funzionalità utilizzando le "schede dell'agente" (documenti JSON), che descrivono la loro identità, le funzionalità A2A supportate, le competenze e i requisiti di autenticazione. In questo modo, gli altri agenti possono scoprire e selezionare l'agente più adatto per una determinata attività.
Sicurezza per impostazione predefinita: la sicurezza è un principio fondamentale. A2A incorpora meccanismi di autenticazione e autorizzazione di livello aziendale, utilizzando standard come HTTPS/TLS, JWT, OIDC e chiavi API per garantire interazioni sicure e proteggere i dati sensibili.
Indipendente dalla modalità: il protocollo supporta varie modalità di comunicazione, tra cui streaming di testo, audio e video, nonché moduli interattivi e iframe incorporati. Questa flessibilità consente agli agenti di scambiare informazioni nel formato più appropriato per l'attività e l'utente.
Gestione strutturata delle attività:A2A definisce protocolli chiari per la delega, il monitoraggio e il completamento delle attività. Supporta il raggruppamento delle attività correlate e la loro gestione su diversi agenti utilizzando ID attività univoci. Le attività possono passare attraverso cicli di vita definiti (ad es. inviata, in corso, completata).
Esecuzione opaca:una funzionalità importante è che gli agenti non devono rivelare ad altri agenti i loro processi di ragionamento interni, la memoria o strumenti specifici. Espongono solo i propri servizi chiamabili, promuovendo la modularità e la privacy.
Basato su standard esistenti: A2A sfrutta tecnologie web consolidate come HTTP, Server-Sent Events (SSE) per lo streaming in tempo reale e JSON-RPC per lo scambio di dati strutturati, semplificando l'integrazione con l'infrastruttura IT esistente.
Comunicazione asincrona:il protocollo è progettato con la comunicazione asincrona come considerazione principale, facilitando la progressione flessibile delle attività e consentendo le notifiche push per gli aggiornamenti anche quando una connessione non viene mantenuta in modo persistente.

5. Architettura dell'agente

In questo lab creerai un'applicazione multi-agente che genera un'immagine in base alle tue specifiche e la valuta prima di presentartela.

Il sistema è strutturato con un agente principale chiamato image_scoring che coordina l'intero processo. Questo agente principale ha un agente secondario chiamato image_generation_scoring_agent, che a sua volta ha i propri agenti secondari per attività più specifiche. In questo modo viene creata una relazione gerarchica in cui l'agente principale delega le attività ai suoi agenti secondari. Figura 2: flusso complessivo dell'agente.

Elenco di tutti gli agenti

image_scoring (Main Agent):
Scopo: questo è l'agente principale che gestisce il flusso di lavoro complessivo. Esegue ripetutamente image_generation_scoring_agent e checker_agent in un ciclo finché non viene soddisfatta una condizione di terminazione.
Sub-agenti:

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (agente secondario di image_scoring):
Scopo: questo agente è responsabile della logica di base per la generazione e l'assegnazione di punteggi alle immagini. Per farlo, esegue una sequenza di tre subagenti.
Sub-agenti:

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (agente secondario di image_scoring):
Scopo: questo agente verifica se il processo di assegnazione del punteggio alle immagini deve continuare o terminare. Utilizza lo strumento check_tool_condition per valutare la condizione di terminazione.
image_generation_prompt_agent (agente secondario di image_generation_scoring_agent):
Scopo: questo agente è un esperto nella creazione di prompt per la generazione di immagini. Prende un testo di input e genera un prompt dettagliato adatto al modello di generazione di immagini.
image_generation_agent (agente secondario di image_generation_scoring_agent):
Scopo: questo agente è un esperto nella creazione di immagini utilizzando Imagen 3. Prende il prompt da image_generation_prompt_agent e genera un'immagine.
scoring_images_prompt (agente secondario di image_generation_scoring_agent):
Scopo: questo agente è un esperto nella valutazione e nell'assegnazione di punteggi alle immagini in base a vari criteri. Prende l'immagine generata e le assegna un punteggio.

Strumenti utilizzati dagli agenti

check_tool_condition:
Descrizione: questo strumento controlla se la condizione di terminazione del ciclo è soddisfatta o se è stato raggiunto il numero massimo di iterazioni. Se una di queste condizioni è vera, il ciclo si interrompe.
Utilizzato da: checker_agent_instance
generate_images:
Descrizione: questo strumento genera immagini utilizzando il modello Imagen 3. Può anche salvare le immagini generate in un bucket Google Cloud Storage.
Utilizzata da: image_generation_agent
get_policy:
Descrizione: questo strumento recupera una policy da un file JSON. La norma viene utilizzata da image_generation_prompt_agent per creare il prompt di generazione di immagini e da scoring_images_prompt per assegnare un punteggio alle immagini.
Utilizzato da: image_generation_prompt_agent, scoring_images_prompt
get_image:
Descrizione: questo strumento carica l'artefatto dell'immagine generata in modo che possa essere valutato.
Utilizzata da: scoring_images_prompt
set_score:
Descrizione: questo strumento imposta il punteggio totale dell'immagine generata nello stato della sessione.
Utilizzata da: scoring_images_prompt

6. Attività 1: Installare ADK e configurare l'ambiente

In questo esercizio pratico utilizzeremo Cloud Shell per eseguire le attività.

Abilita le API consigliate di Vertex AI

Nella console Google Cloud, vai a Vertex AI cercandola nella parte superiore della console.
Fai clic su Abilita tutte le API consigliate.

Prepara una scheda dell'editor di Cloud Shell

Con la finestra della console Google Cloud selezionata, apri Cloud Shell premendo il tasto G e poi il tasto S sulla tastiera. In alternativa, puoi fare clic sul pulsante Cloud Shell nell'angolo in alto a destra della console Google Cloud.
Fai clic su Continua.
Quando ti viene chiesto di autorizzare Cloud Shell, fai clic su Autorizza.
Nell'angolo in alto a destra del riquadro Cloud Shell, fai clic sul pulsante Apri in una nuova finestra .
Fai clic sull'icona a forma di matita Apri editor ( ) nella parte superiore del riquadro per visualizzare i file.
Nella parte superiore del menu di navigazione a sinistra, fai clic sull'icona di Esplora risorse per aprire Esplora file.
Fai clic sul pulsante Apri cartella.
Per il resto del lab, puoi lavorare in questa finestra come IDE con l'editor di Cloud Shell e il terminale Cloud Shell.

Scarica e installa l'ADK e gli esempi di codice per questo lab

Esegui i seguenti comandi per clonare l'origine necessaria da GitHub e installare le librerie necessarie.

#create the project directory
mkdir imagescoring
cd imagescoring
#clone the code in the local directory
git clone https://github.com/haren-bh/multiagenthandson.git

#Create the virtual environment
python3 -m venv pythonenv
source pythonenv/bin/activate

#install google-adk and a2a sdk
python3 -m pip install google-adk==1.8.0
python3 -m pip install a2a-sdk==0.2.16

Utilizzeremo poetry per installare i requisiti aggiuntivi:

cd multiagenthandson #go to the application directory
pip install poetry poetry-plugin-export
poetry install --with deployment

Se non hai un bucket di spazio di archiviazione cloud, creane uno nuovo in Google Cloud Storage. Puoi anche creare il bucket utilizzando il comando gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

Nell'editor, vai a Visualizza > Attiva/disattiva file nascosti. Nella cartella image_scoring crea un file .env con i seguenti contenuti. Aggiungi i dettagli richiesti, come il nome del progetto e il bucket Cloud Storage.

GOOGLE_GENAI_USE_VERTEXAI=1 #1 if VERTEXAI has to be used. Can be 0 if API_KEY is specified
GOOGLE_CLOUD_PROJECT=YOUR CLOUD PROJECT NAME
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_CLOUD_STORAGE_BUCKET=YOUR BUCKET NAME  # Only required for deployment on Agent Engine
GCS_BUCKET_NAME=YOUR BUCKET NAME #Bucket for storing generated images.
SCORE_THRESHOLD=40 # Min threshold for image_score. Max Score is 50 , hence should be less than 50. 
#If the computed score is higher then loop will terminate
#MAX_ITERATIONS=5 #Max iterations for evaluating the image_score before terminating the loop.
IMAGEN_MODEL="imagen-3.0-generate-002" 
GENAI_MODEL="gemini-2.5-flash"
#AGENT_ENGINE_ID=<AGENT_ENGINE_ID> #The Agent Engine ID obtained after deploying to the agent engine.

Esamina la struttura dell'agente nel codice sorgente, a partire da agent.py . Questo agente contiene l'agente principale che si connetterà agli altri agenti.
Torna alla directory principale multiagenthandson nel terminale ed esegui questo comando per eseguire l'agente in locale:

# Run the following command to run agents locally
export GCS_BUCKET_NAME=your gcs bucket name
adk web

Figura 1

Premi Ctrl+clic (CMD+clic per macOS) sull'URL http:// visualizzato sul terminale per aprire il client GUI basato su browser dell'ADK. Dovrebbe avere l'aspetto della Figura 2

Generiamo alcune immagini. Prova i seguenti prompt o i tuoi.
Un tranquillo paesaggio montano al tramonto
Un gatto in bicicletta

Figura 2

7. Attività 2: Esegui il deployment in Agent Engine

Ora eseguiamo il deployment dell'agente in Agent Engine. Agent Engine è un servizio completamente gestito per il deployment di agenti in GCP. Agent Engine è compatibile con ADK, quindi gli agenti creati con ADK possono essere implementati in Agent Engine.

Definisci alcune variabili di ambiente

export GOOGLE_CLOUD_LOCATION='us-central1'
export GOOGLE_CLOUD_PROJECT='your project id'

Crea il file requirements.txt utilizzando Poetry. Poetry utilizzerà pyproject.toml per creare il file requirements.txt. Dopo aver eseguito il comando, controlla se è stato creato il file requirements.txt.

# Go to the parent folder containing pyproject.toml file
# install poetry-plugin-export
pip install poetry-plugin-export

#Create requirements.txt file
poetry export -f requirements.txt --output requirements.txt --without-hashes

Crea il pacchetto. Dobbiamo raggruppare la nostra app in un pacchetto Python .whl. Useremo la poesia per farlo. Dopo aver eseguito il comando, assicurati che sia stata creata una cartella dist e che contenga il file .whl.

# Go to the parent folder containing pyproject.toml file
#Create python package, to create whl file
poetry build

Ora prepareremo lo script di deployment. Lo script di deployment eseguirà il deployment del nostro agente di valutazione delle immagini o del servizio del motore dell'agente. Modifica i contenuti di deploy.py all'interno della cartella image_scoring come indicato di seguito.

# Change the content of the following. Look for #change this comment
import vertexai
from .agent import root_agent
import os
import glob # To easily find the wheel file

PROJECT_ID = "YOUR PROJECT ID" #change this your project
LOCATION = "us-central1" #change this
STAGING_BUCKET = "gs://YOUR BUCKET " #change this to your bucket

from vertexai import agent_engines

vertexai.init(
   project=PROJECT_ID,
   location=LOCATION,
   staging_bucket=STAGING_BUCKET,
)

remote_app = agent_engines.create(
   agent_engine=root_agent,
   requirements=open(os.path.join(os.getcwd(), "requirements.txt")).readlines()+["./dist/image_scoring-0.1.0-py3-none-any.whl"],#change this to your local location
   extra_packages=[
       "./dist/image_scoring-0.1.0-py3-none-any.whl", # change this to your location
   ]
)

print(remote_app.resource_name)

Ora possiamo eseguire lo script di deployment.

#run deploy script from the parent folder containing deploy.py
python3 -m image_scoring.deploy

Dopo il deployment, dovresti vedere qualcosa di simile a questo,

Figura 3

Ora testiamo l'agente di cui è stato eseguito il deployment. Per testare il motore dell'agente di cui è stato eseguito il deployment da remoto, copia prima la posizione dell'agente dall'output del deployment nel terminale. Dovrebbe avere un aspetto simile a questo: projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Vai alla cartella testclient,apri il file remote_test.py e modifica le seguenti righe.

PROJECT_ID = "" #change this
LOCATION = "" #change this
STAGING_BUCKET = "" #change this

#replace the id with your own.
reasoning_engine_id="your agent engine id"

#You can replace this with your own prompt
image_prompt="A cat riding a bicycle"

#execute remote_test.py
python3 remote_test.py

8. Attività 3: Crea un agente A2A

In questo passaggio creeremo un semplice agente A2A basato sull'agente creato nei passaggi precedenti. Gli agenti ADK esistenti possono essere pubblicati con il protocollo A2A. Questi sono gli aspetti chiave che imparerai in questo passaggio.

Scopri le nozioni di base del protocollo A2A.
Scopri come funzionano insieme i protocolli ADK e A2A.
Scopri come interagire con il protocollo A2A.

In questo esercizio pratico utilizzeremo il codice nella cartella image_scoring_adk_a2a_server. Prima di iniziare l'attività, cambia la directory in questa cartella.

Crea una scheda dell'agente A2A

Il protocollo A2A richiede una scheda dell'agente che contenga tutte le informazioni sull'agente, come le funzionalità, la guida all'utilizzo e così via. Una volta implementato un agente A2A, la scheda dell'agente è visibile utilizzando il link ".well-known/agent-card.json". I clienti possono fare riferimento a queste informazioni per inviare la richiesta agli agenti.

Nella cartella remote_a2a/image_scoring verifica che sia presente il file agents.json con i seguenti contenuti.

{
 "name": "image_scoring",
 "description": "Agent that generates images based on user prompts and scores their adherence to the prompt.",
 "url": "http://localhost:8001/a2a/image_scoring",
 "version": "1.0.0",
 "defaultInputModes": ["text/plain"],
 "defaultOutputModes": ["image/png", "text/plain"],
 "capabilities": {
   "streaming": true,
   "functions": true
 },
 "skills": [
   {
     "id": "generate_and_score_image",
     "name": "Generate and Score Image",
     "description": "Generates an image from a given text prompt and then evaluates how well the generated image adheres to the original prompt, providing a score.",
     "tags": ["image generation", "image scoring", "evaluation", "AI art"],
     "examples": [
       "Generate an image of a futuristic city at sunset",
       "Create an image of a cat playing a piano",
       "Show me an image of a serene forest with a hidden waterfall"
     ]
   }
 ]
}

Crea un agente A2A

Nella cartella principale image_scoring_adk_a2a_server, verifica che sia presente un file a2a_agent.py, che è il punto di ingresso per l'agente a2a. Deve contenere i seguenti contenuti:

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

root_agent = RemoteA2aAgent(
   name="image_scoring",
   description="Agent to give interesting facts.",
   agent_card="http://localhost:8001/a2a/image_scoring/.well-known/agent.json",
  
   # Optional configurations
   timeout=300.0,          # HTTP timeout (seconds)
   httpx_client=None,      # Custom HTTP client
)

Esegui l'agente A2A

Ora siamo pronti per eseguire l'agente. Per eseguire l'agente, esegui il seguente comando dall'interno della cartella principale image_scoring_adk_a2a_server

#set some environmental variables
export GOOGLE_CLOUD_PROJECT=datapipeline-372305
export GOOGLE_CLOUD_LOCATION=us-central1
export GCS_BUCKET_NAME=haren-genai-bucket

#following command runs the ADK agent as a2a agent
adk api_server --a2a --port 8001 remote_a2a

Testare l'agente A2A

Una volta che l'agente è in esecuzione, possiamo testarlo. Innanzitutto, controlliamo la scheda dell'agente.

#Execute the following 
curl http://localhost:8001/a2a/image_scoring/.well-known/agent.json

L'esecuzione del comando precedente dovrebbe mostrare la scheda dell'agente per il nostro agente A2A, che corrisponde principalmente ai contenuti di agent.json che abbiamo creato nel passaggio precedente.

Ora inviamo una richiesta all'agente. Possiamo utilizzare curl per inviare la richiesta all'agente,

curl -X POST   http://localhost:8001/a2a/image_scoring   -H 'Content-Type: application/json'   -d '{
    "id": "uuid-123",
    "params": {
      "message": {
        "messageId": "msg-456",
        "parts": [{"text": "Create an image of a cat"}],
        "role": "user"
      }
    }
  }'

Nella richiesta riportata sopra, puoi modificare il prompt modificando la riga "Crea un'immagine di un gatto". Dopo aver eseguito il comando, puoi controllare l'immagine di output nell'archivio Google Cloud specificato.

9. Esegui la pulizia

Ora puliamo ciò che abbiamo appena creato.

Elimina il server Agent Engine che abbiamo appena creato. Vai a Vertex AI digitando Vertex AI nella barra di ricerca della console Google Cloud. Fai clic su Agent Engine a sinistra.Puoi eliminare l'agente facendo clic su Elimina.

Figura 4

Elimina i file in Cloud Shell

#Execute the following to delete the files
rm -R imagescoring

Elimina il bucket. Puoi andare alla console GCP -> Cloud Storage , selezionare ed eliminare il bucket.