Cette page a été traduite par l'API Cloud Translation.

Créer un système multi-agent avec ADK, le déployer dans Agent Engine et commencer à utiliser le protocole A2A

1. Objectif de cet atelier

Dans cet atelier pratique, vous allez créer une application multi-agents qui génère une image en fonction de votre requête et l'évalue par rapport à celle-ci. Si l'image ne répond pas de manière satisfaisante aux exigences décrites dans la requête, l'agent continuera à générer des images jusqu'à ce qu'il trouve celle qui répond à vos exigences. Chacun des agents de cet atelier pratique a un objectif unique. Les agents coopèrent entre eux pour atteindre l'objectif global.

Points abordés

Comprendre les bases de l'ADK et apprendre à créer un système multi-agents.
Découvrez comment déployer et utiliser facilement les agents dans GCP.
Comprendre les bases du protocole A2A
Découvrez comment utiliser le protocole A2A et l'ADK ensemble pour créer des agents ouverts.

2. Avant de commencer

Si vous ne disposez pas déjà d'un projet que vous pouvez utiliser, vous devrez en créer un dans la console GCP.
Dans cet atelier, nous allons utiliser GCP Cloud Shell pour effectuer nos tâches. Ouvrez Cloud Shell et définissez le projet à l'aide de Cloud Shell.
Ouvrez l'éditeur Cloud Shell de GCP en appuyant sur le bouton de l'éditeur Cloud Shell. Si la fenêtre pop-up "Autoriser Shell" s'affiche, cliquez dessus pour autoriser l'éditeur Cloud Shell.
Vous pouvez vérifier si le projet est déjà authentifié à l'aide de la commande suivante.

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour confirmer votre projet

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Nous devons activer certains services pour exécuter cet atelier. Exécutez la commande suivante dans Cloud Shell.

gcloud services enable aiplatform.googleapis.com

3. Présentation : avantages d'Agent Development Kit

L'Agent Development Kit offre plusieurs avantages clés aux développeurs qui créent des applications agentives :

Systèmes multi-agents : créez des applications modulaires et évolutives en composant plusieurs agents spécialisés dans une hiérarchie. Permet une coordination et une délégation complexes.
Écosystème d'outils riches : dotez les agents de diverses fonctionnalités. Utilisez des outils prédéfinis (Recherche, Exécution de code, etc.), créez des fonctions personnalisées, intégrez des outils à partir de frameworks d'agents tiers (LangChain, CrewAI) ou utilisez même d'autres agents comme outils.
Orchestration flexible : définissez des workflows à l'aide d'agents de workflow (SequentialAgent, ParallelAgent et LoopAgent) pour des pipelines prévisibles, ou utilisez le routage dynamique basé sur les LLM (transfert LlmAgent) pour un comportement adaptatif.
Expérience de développement intégrée : développez, testez et déboguez en local avec une CLI puissante et une UI de développement interactive. Inspectez les événements, l'état et l'exécution de l'agent étape par étape.
Évaluation intégrée : évaluez systématiquement les performances de l'agent en comparant la qualité de la réponse finale et la trajectoire d'exécution étape par étape à des cas de test prédéfinis.
Prêt pour le déploiement : conteneurisez et déployez vos agents où vous le souhaitez (exécutez-les en local, faites-les évoluer avec Vertex AI Agent Engine ou intégrez-les à une infrastructure personnalisée à l'aide de Cloud Run ou Docker).

Bien que d'autres SDK d'IA générative ou frameworks d'agents vous permettent également d'interroger des modèles et même de leur fournir des outils, la coordination dynamique entre plusieurs modèles nécessite un travail considérable de votre part.

Le kit de développement d'agents offre un framework de niveau supérieur à ces outils, ce qui vous permet de connecter facilement plusieurs agents les uns aux autres pour des workflows complexes, mais faciles à gérer.

4. Présentation d'A2A

Le protocole Agent2Agent (A2A) est une norme ouverte conçue pour permettre une communication et une collaboration fluides et sécurisées entre des agents d'IA autonomes provenant de différents frameworks, fournisseurs et domaines.

Interopérabilité universelle : A2A permet aux agents de travailler ensemble, quelles que soient leurs technologies sous-jacentes, favorisant ainsi un véritable écosystème multi-agents. Cela signifie que les agents créés par différentes entreprises sur différentes plates-formes peuvent communiquer et se coordonner.
Découverte des capacités : les agents peuvent annoncer leurs capacités à l'aide de "cartes d'agent" (documents JSON), qui décrivent leur identité, les fonctionnalités A2A prises en charge, les compétences et les exigences d'authentification. Cela permet aux autres agents de découvrir et de sélectionner l'agent le plus adapté à une tâche donnée.
Sécurité par défaut : la sécurité est un principe fondamental. L'A2A intègre des mécanismes d'authentification et d'autorisation de niveau entreprise, en utilisant des normes telles que HTTPS/TLS, JWT, OIDC et les clés API pour garantir des interactions sécurisées et protéger les données sensibles.
Agnostique de la modalité : le protocole est compatible avec différentes modalités de communication, y compris le texte, le streaming audio et vidéo, ainsi que les formulaires interactifs et les iFrames intégrés. Cette flexibilité permet aux agents d'échanger des informations dans le format le plus approprié à la tâche et à l'utilisateur.
Gestion structurée des tâches : A2A définit des protocoles clairs pour la délégation, la surveillance et l'exécution des tâches. Il permet de regrouper les tâches associées et de les gérer sur différents agents à l'aide d'ID de tâches uniques. Les tâches peuvent passer par des cycles de vie définis (par exemple, "envoyée", "en cours", "terminée").
Exécution opaque : une fonctionnalité importante est que les agents n'ont pas besoin de révéler leurs processus de raisonnement internes, leur mémoire ou leurs outils spécifiques à d'autres agents. Ils n'exposent que leurs services appelables, ce qui favorise la modularité et la confidentialité.
Basé sur des normes existantes : A2A s'appuie sur des technologies Web établies telles que HTTP, les événements envoyés par le serveur (SSE) pour le streaming en temps réel et JSON-RPC pour l'échange de données structurées, ce qui facilite l'intégration à l'infrastructure informatique existante.
Communication asynchrone : le protocole est conçu en tenant compte de la communication asynchrone comme élément principal. Il facilite la progression flexible des tâches et permet les notifications push pour les mises à jour, même lorsqu'une connexion n'est pas maintenue en permanence.

5. Architecture de l'agent

Dans cet atelier, vous allez créer une application multi-agents qui génère une image selon vos spécifications et l'évalue avant de vous la présenter.

Le système est structuré avec un agent principal appelé image_scoring qui orchestre l'ensemble du processus. Cet agent principal possède un sous-agent appelé image_generation_scoring_agent, qui possède lui-même ses propres sous-agents pour des tâches plus spécifiques. Cela crée une relation hiérarchique dans laquelle l'agent principal délègue des tâches à ses sous-agents. Figure 2 : Flux global de l'agent.

Liste de tous les agents

image_scoring (Main Agent):
Objectif : il s'agit de l'agent racine qui gère le workflow global. Il exécute en boucle les image_generation_scoring_agent et checker_agent jusqu'à ce qu'une condition d'arrêt soit remplie.
Sous-agents :

image_generation_scoring_agent
checker_agent_instance

image_generation_scoring_agent (sous-agent de image_scoring) :
Objectif : cet agent est responsable de la logique de base de la génération et de la notation des images. Pour ce faire, il exécute une séquence de trois sous-agents.
Sous-agents :

image_generation_prompt_agent
image_generation_agent
scoring_images_prompt

checker_agent_instance (sous-agent de image_scoring) :
Objectif : cet agent vérifie si le processus de notation des images doit se poursuivre ou s'arrêter. Il utilise l'outil check_tool_condition pour évaluer la condition d'arrêt.
image_generation_prompt_agent (sous-agent de image_generation_scoring_agent) :
Objectif : cet agent est un expert en création de requêtes pour la génération d'images. Il prend un texte en entrée et génère une requête détaillée adaptée au modèle de génération d'images.
mage_generation_agent (sous-agent de image_generation_scoring_agent) :
Objectif : cet agent est un expert en création d'images à l'aide d'Imagen 3. Il prend la requête de l'image_generation_prompt_agent et génère une image.
scoring_images_prompt (sous-agent de image_generation_scoring_agent) :
Objectif : cet agent est un expert en évaluation et en notation d'images selon différents critères. Il prend l'image générée et lui attribue un score.

Outils utilisés par les agents

check_tool_condition:
Description : cet outil vérifie si la condition d'arrêt de la boucle est remplie ou si le nombre maximal d'itérations a été atteint. Si l'une de ces conditions est remplie, la boucle s'arrête.
Utilisé par : checker_agent_instance
generate_images:
Description : cet outil génère des images à l'aide du modèle Imagen 3. Il peut également enregistrer les images générées dans un bucket Google Cloud Storage.
Utilisé par : image_generation_agent
get_policy:
Description : cet outil récupère une règle à partir d'un fichier JSON. Cette règle est utilisée par l'agent de requête de génération d'images pour créer la requête de génération d'images et par l'agent de requête de notation d'images pour noter les images.
Utilisé par : image_generation_prompt_agent, scoring_images_prompt
get_image:
Description : cet outil charge l'artefact d'image généré afin qu'il puisse être noté.
Utilisé par : scoring_images_prompt
set_score:
Description : cet outil définit le score total de l'image générée dans l'état de la session.
Utilisé par : scoring_images_prompt

6. Tâche 1 : Installer l'ADK et configurer votre environnement

Dans cet atelier pratique, nous allons utiliser Cloud Shell pour effectuer les tâches.

Activer les API recommandées Vertex AI

En haut de la console Google Cloud, recherchez Vertex AI, puis accédez à la page correspondante.
Cliquez sur Activer toutes les API recommandées.

Préparer un onglet de l'éditeur Cloud Shell

Sélectionnez la fenêtre de la console Google Cloud, puis ouvrez Cloud Shell en appuyant sur les touches G, puis S de votre clavier. Vous pouvez également cliquer sur le bouton Cloud Shell en haut à droite de la console Google Cloud.
Cliquez sur Continuer.
Lorsque vous êtes invité à autoriser Cloud Shell, cliquez sur Autoriser.
En haut à droite du volet Cloud Shell, cliquez sur le bouton Ouvrir dans une nouvelle fenêtre .
Cliquez sur l'icône en forme de crayon Ouvrir l'éditeur ( ) en haut du volet pour afficher les fichiers.
En haut du menu de navigation de gauche, cliquez sur l'icône Explorateur pour ouvrir l'explorateur de fichiers.
Cliquez sur le bouton Ouvrir le dossier.
Pour le reste de cet atelier, vous pouvez travailler dans cette fenêtre comme IDE avec l'éditeur Cloud Shell et le terminal Cloud Shell.

Télécharger et installer l'ADK et les exemples de code pour cet atelier

Exécutez les commandes suivantes pour cloner la source nécessaire à partir de GitHub et installer les bibliothèques requises.

#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

Nous allons utiliser poetry pour installer des exigences supplémentaires :

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

Si vous n'avez pas de bucket Cloud Storage, créez-en un dans Google Cloud Storage. Vous pouvez également créer le bucket à l'aide de la commande gsutil.

gsutil mb gs://YOUR-UNIQUE-BUCKETNAME

Dans l'éditeur, accédez à Afficher > Activer/Désactiver les fichiers cachés. Dans le dossier image_scoring, créez un fichier .env avec le contenu suivant. Ajoutez les informations requises, comme le nom de votre projet et le 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.

Examinez la structure de l'agent dans le code source, en commençant par agent.py . Cet agent contient l'agent racine qui se connectera aux autres agents.
Retournez au répertoire racine multiagenthandson dans le terminal et exécutez la commande suivante pour exécuter l'agent localement.

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

Figure 1

Appuyez sur Ctrl+clic (CMD+clic pour macOS) sur l'URL http:// affichée dans le terminal pour ouvrir le client GUI basé sur le navigateur de l'ADK. Elle devrait ressembler à la figure 2.

Générons quelques images. Essayez les requêtes suivantes ou les vôtres.
Paysage de montagne paisible au coucher du soleil
Un chat à vélo

Figure 2

7. Tâche 2 : Déployer sur Agent Engine

Nous allons maintenant déployer l'agent sur Agent Engine. Agent Engine est un service entièrement géré permettant de déployer des agents dans GCP. Agent Engine est compatible avec ADK. Les agents créés avec ADK peuvent donc être déployés dans Agent Engine.

Définir certaines variables d'environnement

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

Créez le fichier requirements.txt à l'aide de Poetry. Poetry utilisera pyproject.toml pour créer le fichier requirements.txt. Après avoir exécuté la commande, vérifiez si le fichier requirements.txt a été créé.

# 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

Créez le package. Nous devons regrouper notre application dans un package Python .whl. Nous utiliserons poetry pour cela. Une fois la commande exécutée, assurez-vous qu'un dossier "dist" a été créé et qu'il contient le fichier .whl.

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

Nous allons maintenant préparer le script de déploiement. Le script de déploiement déploie notre agent ou notre service d'évaluation des images. Veuillez modifier le contenu de deploy.py dans le dossier image_scoring comme suit.

# 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)

Nous pouvons maintenant exécuter le script de déploiement.

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

Une fois le déploiement effectué, vous devriez voir un résultat semblable à celui ci-dessous,

Figure 3

Testons maintenant l'agent déployé. Pour tester le moteur de l'agent déployé à distance, commencez par copier l'emplacement de l'agent à partir de la sortie du déploiement dans le terminal. Elle devrait ressembler à ceci : projects/85469421903/locations/us-central1/reasoningEngines/7369674597261639680 .
Accédez au dossier testclient,ouvrez le fichier remote_test.py et modifiez les lignes suivantes.

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. Tâche 3 : Créer un agent A2A

Dans cette étape, nous allons créer un agent A2A simple basé sur l'agent que nous avons créé lors des étapes précédentes. Les agents ADK existants peuvent être publiés sous le protocole A2A. Voici les principaux points que vous allez apprendre dans cette étape.

Découvrez les principes de base du protocole A2A.
Découvrez comment les protocoles ADK et A2A fonctionnent ensemble.
Découvrez comment interagir avec le protocole A2A.

Dans cet exercice pratique, nous allons utiliser le code du dossier image_scoring_adk_a2a_server. Avant de commencer la tâche, veuillez accéder à ce dossier.

Créer une fiche d'agent A2A

Le protocole A2A nécessite une fiche d'agent contenant toutes les informations sur l'agent, telles que ses capacités, son guide d'utilisation, etc. Une fois un agent A2A déployé, la fiche d'agent est visible à l'aide du lien .well-known/agent-card.json. Les clients peuvent se référer à ces informations pour envoyer la demande aux agents.

Dans le dossier remote_a2a/image_scoring, vérifiez que le fichier agents.json contient le contenu suivant.

{
 "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"
     ]
   }
 ]
}

Créer un agent A2A

Dans le dossier racine image_scoring_adk_a2a_server, vérifiez qu'il existe un fichier a2a_agent.py, qui est le point d'entrée de l'agent a2a. Il doit contenir les éléments suivants :

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
)

Exécuter l'agent A2A

Nous sommes maintenant prêts à exécuter l'agent. Pour exécuter l'agent, exécutez la commande suivante à partir du dossier racine 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

Tester l'agent A2A

Une fois l'agent en cours d'exécution, nous pouvons maintenant le tester. Commençons par examiner la fiche de l'agent.

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

L'exécution de la commande ci-dessus devrait afficher la fiche de l'agent A2A, qui correspond principalement au contenu du fichier agent.json que nous avons créé à l'étape précédente.

Envoyons maintenant une requête à l'agent. Nous pouvons utiliser curl pour envoyer une requête à l'agent.

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"
      }
    }
  }'

Dans la requête ci-dessus, vous pouvez modifier le prompt en changeant la ligne "Create an image of a cat" (Crée une image de chat). Une fois la commande exécutée, vous pouvez rechercher l'image de sortie dans le stockage Google Cloud spécifié.

9. Effectuer un nettoyage

Nettoyons maintenant ce que nous venons de créer.

Supprimez le serveur Agent Engine que nous venons de créer. Accédez à Vertex AI en saisissant "Vertex AI" dans la barre de recherche de la console Google Cloud. Cliquez sur "Agent Engine" (Moteur d'agent) sur la gauche.Vous pouvez supprimer l'agent en cliquant sur "Delete" (Supprimer).

Figure 4

Supprimez les fichiers dans Cloud Shell.

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

Supprimez le bucket. Vous pouvez accéder à la console GCP > Cloud Storage , sélectionner votre bucket et le supprimer.