01-bis. Les agents du trio sur Cloud Run, en A2A, dans Gemini Enterprise

Pour qui : équipes qui hébergent leurs agents sur Cloud Run et veulent les rendre utilisables dans Gemini Enterprise, depuis le projet de l'app ou depuis leur propre projet. Résultat : « Météo & équipement (A2A) », « Rédaction & reformulation (A2A) », « Traduction Acme (A2A) » et les autres agents de agents/trio/catalogue.json (6 en tout) dans le chat Gemini Enterprise, chacun sur son service Cloud Run privé, déclaré dans Agent Registry. Le schéma ci-dessous en montre 3.

Pas besoin de Docker : les images sont construites dans Google Cloud par Cloud Build (gcloud builds submit, lancé par Terraform). Un terminal Linux ou Mac, ou Cloud Shell, avec gcloud et Terraform suffit.

Avant de commencer : docs/08, étapes 1 à 4 (prérequis et test local des agents). Différence avec le projet 01 : 01 sert l'API REST d'ADK (pour vos applications) ; 01-bis sert le protocole A2A v0.3, le seul que Gemini Enterprise accepte pour un agent Cloud Run.

 Projet AGENTS (B, ou A si même projet)                       Projet APP (A)
┌──────────────────────────────────────────────────────┐     ┌──────────────────────────────────────┐
│ Artifact Registry : agents-a2a/<agent>:<hash>        │     │ App Gemini Enterprise (eu)           │
│                                                      │     │  Agents :                            │
│ Cloud Run (privé, europe-west1)          identité    │     │   Météo & équipement (A2A) ─────┐    │
│  meteo-a2a      AGENT=meteo_agent      meteo-a2a-sa  │◀────┼── Rédaction & reformulation (A2A)│    │
│  redaction-a2a  AGENT=redaction_agent  redaction-…   │ A2A │   Traduction Acme (A2A)    │    │
│  traduction-a2a AGENT=traduction_agent traduction-…  │ v0.3│                                 │    │
│     ▲ run.invoker (sur chaque service) ──────────────┼─────┼─ service-NUM_A@gcp-sa-discovery…◀┘   │
│ Agent Registry (europe-west1) : 3 cartes A2A         │     │   (compte de Gemini Enterprise)      │
│ Model Armor : templates (ici ou projet 08)           │     └──────────────────────────────────────┘
└──────────────────────────────────────────────────────┘

Sommaire

1. Comprendre ce qui va être créé
2. Tester le conteneur en local (optionnel, 5 min)
3. Configurer
4. Déployer les agents
5. Tester les agents déployés, sans Gemini Enterprise
6. Vérifier Agent Registry
7. Publier dans l'app Gemini Enterprise
8. Donner l'accès et tester dans le chat
9. Variante : agents dans un autre projet
10. Modifier un agent, en ajouter un
11. Nettoyer
12. Dépannage

1. Comprendre ce qui va être créé

Trois idées à retenir :

1. Un service par agent. Chaque agent a son URL, son identité et son droit d'appel. On peut ouvrir un agent à Gemini Enterprise sans ouvrir les autres.
2. La carte A2A (JSON) décrit l'agent : nom, description, compétences, URL. Gemini Enterprise la lit pour savoir quoi proposer et où appeler. Terraform l'écrit une fois et la met à trois endroits : dans le service (servie sur /.well-known/agent-card.json), dans Agent Registry, et dans l'app.
3. Les services restent privés. Gemini Enterprise s'authentifie avec son compte de service (service-NUM_A@gcp-sa-discoveryengine.iam.gserviceaccount.com), qui reçoit run.invoker sur chaque service. Pas d'accès public, pas de clé.

Pourquoi l'URL est calculée d'avance : la carte contient l'URL du service, et le service sert sa carte. Terraform utilise donc l'URL déterministe de Cloud Run, https://SERVICE-NUMERO_PROJET.REGION.run.app, et vérifie après création que c'est bien la vraie (sinon terraform apply s'arrête avec un message clair). Gemini Enterprise exige d'ailleurs l'URL .run.app par défaut pour son authentification automatique (pas de domaine personnalisé).

2. Tester le conteneur en local (optionnel)

Seulement si vous avez Docker (sinon passez à l'étape 3 : le test de l'étape 5 se fait sur Cloud Run, et les agents se testent sans conteneur avec PROMPT_TEMPLATE= RESPONSE_TEMPLATE= LOCAL_DEV=1 adk web, voir docs/08). Ce test lance la même recette d'image que Cloud Run, et lui parle comme Gemini Enterprise. Depuis le dossier du projet (sans AGENT_DIR, l'image contient tous les agents) :

cd 09-agents-multi-projets-gemini-enterprise
docker build -f 01-bis-cloud-run-a2a/Dockerfile -t trio-a2a:local .

docker run --rm -d --name meteo-local -p 8080:8080 \
  -e AGENT=meteo_agent -e LOCAL_DEV=1 -e GOOGLE_CLOUD_PROJECT=acme-agents-demo \
  -e GOOGLE_APPLICATION_CREDENTIALS=/adc.json \
  -v $HOME/.config/gcloud/application_default_credentials.json:/adc.json:ro \
  trio-a2a:local

URL=http://localhost:8080 ./01-bis-cloud-run-a2a/test.sh meteo
docker stop meteo-local

Attendu :

== meteo  carte : meteo_agent (A2A 1.0)
   Q1 > Quel temps fait-il à Chamonix ?
   R1 < À Chamonix, le temps est aux averses avec une température de 9°C …
   Q2 > Et pour y randonner, quoi porter ?
   R2 < … sous-vêtement technique à manches longues, une polaire et une veste imperméable …
OK : les agents répondent en A2A v0.3, avec mémoire de conversation

La 2e réponse prouve que l'agent garde la conversation (« y » = Chamonix) : c'est ce que fait Gemini Enterprise d'un message à l'autre. En local, la carte est générée automatiquement (format A2A 1.0) ; sur Cloud Run, c'est la carte v0.3 écrite par Terraform. Le serveur accepte les deux versions du protocole.

3. Configurer

cd 09-agents-multi-projets-gemini-enterprise/01-bis-cloud-run-a2a/terraform
cp terraform.tfvars.example terraform.tfvars

Choisir son cas, puis remplir terraform.tfvars :

Cas A : l'admin vous a donné le numéro du projet de l'app (NUM_APP).

agents_project_id = "equipe-pricing-prod"   # VOTRE projet
ge_project_number = "98547854221"          # NUM_APP, donné par l'admin Gemini Enterprise
ge_location       = "eu"
region            = "europe-west1"

Cas B : le projet de l'app héberge aussi les agents.

agents_project_id = "aiml-gemini-entreprise-ldbr"
ge_project_number = "98547854221"          # gcloud projects describe aiml-gemini-entreprise-ldbr --format='value(projectNumber)'
ge_location       = "eu"
region            = "europe-west1"
# ge_project_id = "aiml-gemini-entreprise-ldbr"       # à l'étape 7, pour publier
# ge_app_id     = "ID_DE_L_APP"

Juste essayer, sans Gemini Enterprise ? Laisser ge_project_number vide : les agents sont déployés et testés, sans droit pour Gemini Enterprise.

Templates Model Armor du projet 08 : décommenter prompt_template et response_template. Sinon, Terraform crée une paire de templates trio-a2a-prompt-shield / trio-a2a-response-shield dans le projet des agents.

Pourquoi europe-west1 : l'app est en eu. Agents, registre et données restent en Europe.

4. Déployer les agents

terraform init
terraform plan       # lire : 57 ressources à créer pour les 6 agents (63 avec ge_project_number : + 1 droit d'appel par agent)
terraform apply      # taper "yes" ; ~10 min (une image par agent, construite par Cloud Build, ~1 min 20 s chacune, puis les services)

Le plan compte 22 ressources pour un seul agent (agents = ["meteo"]), +7 par agent en plus ; avec ge_project_number : 23, +8 par agent. On y voit notamment google_service_account.build (le compte qui construit les images, agents-a2a-build-sa), ses 3 rôles google_project_iam_member.build["roles/…"], google_project_service.agents["cloudbuild.googleapis.com"] et un terraform_data.image["<agent>"] par agent.

Ce que fait apply, dans l'ordre : active les API (dont Cloud Build) → crée les templates Model Armor (si besoin) → crée le dépôt d'images et le compte de construction → fait construire l'image de chaque agent dans Google Cloud (gcloud builds submit ; jusqu'à 4 essais, le temps que les droits du compte tout neuf s'appliquent) → crée une identité par agent et ses droits → crée les services Cloud Run → vérifie leurs URL → donne run.invoker au compte de Gemini Enterprise sur chacun → inscrit les cartes dans Agent Registry.

Vos rôles doivent permettre de lancer une construction : Cloud Build Editor, Service Account User, Storage Admin (gcloud crée le bucket gs://PROJET_cloudbuild à la 1re construction), ou Owner.

Attendu à la fin :

Apply complete! Resources: 63 added, 0 changed, 0 destroyed.
Outputs:
cards = { meteo = "{\"protocolVersion\":\"0.3\", … }", … }
urls = {
  "meteo"      = "https://meteo-a2a-NUMERO_PROJET_AGENTS.europe-west1.run.app"
  "redaction"  = "https://redaction-a2a-NUMERO_PROJET_AGENTS.europe-west1.run.app"
  "traduction" = "https://traduction-a2a-NUMERO_PROJET_AGENTS.europe-west1.run.app"
  …
}

Dans la console : 🔎 « Cloud Build » → Historique (région europe-west1) : une construction par agent, statut réussi, avec son journal. 🔎 « Cloud Run » → les services meteo-a2a, redaction-a2a, traduction-a2a, …, coche verte. Onglet Sécurité : Authentification requise. Ouvrir une URL dans le navigateur donne 403 Forbidden : c'est voulu (service privé).

5. Tester les agents déployés, sans Gemini Enterprise

cd ..          # 01-bis-cloud-run-a2a
./test.sh

Le script lit les URL des services, prend votre jeton d'identité (vous êtes autorisé en tant que propriétaire du projet), lit chaque carte, pose 2 questions par agent dans la même conversation. Attendu : un bloc par agent comme à l'étape 2, avec carte : meteo_agent (A2A 0.3), puis OK : ….

Pourquoi ce test : si l'étape 5 marche et que l'agent échoue dans Gemini Enterprise, le problème est dans la publication ou les droits (étapes 7-8), pas dans l'agent.

Voir ce qui s'est passé : 🔎 « Cloud Run » → meteo-a2a → Journaux : requêtes POST / en 200, appels d'outils.

Vérifier l'accès de Gemini Enterprise, avant l'ajout dans l'app : le simulateur appelle l'agent avec un compte du projet de l'app qui a les mêmes droits que Gemini Enterprise : docs/09, étape 4.

6. Vérifier Agent Registry

Agent Registry est le catalogue des agents du projet : les autres équipes (et leurs agents) y trouvent les vôtres, avec leur carte, sans vous demander d'URL.

gcloud agent-registry services list --location=europe-west1 --project=aiml-gemini-entreprise-ldbr
python ../scripts/registry.py aiml-gemini-entreprise-ldbr europe-west1          # depuis 01-bis-cloud-run-a2a

Attendu : meteo-a2a Météo & équipement, redaction-a2a Rédaction & reformulation, traduction-a2a Traduction Acme (vérifié). Côté agents (gcloud agent-registry agents list …), ils apparaissent sous le nom de leur carte : meteo_agent, redaction_agent, traduction_agent.

Console : 🔎 « Agent Registry » → région europe-west1 → les agents (un par entrée du catalogue), type A2A.

L'import dans l'app depuis Agent Registry (Agents from agent registry) exige une Agent Gateway reliée à l'app, qui fait passer tout le trafic de l'app par la passerelle : c'est la méthode 3 du tutoriel 03. Ici, on publie directement par la carte A2A (étape 7), qui fonctionne sans passerelle.

7. Publier dans l'app Gemini Enterprise

Cas A (votre projet, app de l'admin) : vous ne publiez pas vous-même. Envoyez à l'admin la fiche de demande avec les cartes (terraform output -json cards) : docs/09, étapes 5 et 6. Le droit d'appel est déjà posé par Terraform.

Cas B (projet de l'app) : en Terraform. Dans terraform/terraform.tfvars, ajouter puis relancer :

ge_project_id = "aiml-gemini-entreprise-ldbr"
ge_app_id     = "ID_DE_L_APP"          # Gemini Enterprise → l'app → Présentation

cd terraform && terraform apply

Attendu : registered Météo & équipement (A2A), … (un par agent), Resources: 7 added (API Discovery Engine + 6 agents dans l'app, mode Agent personnalisé via A2A).

Ou dans la console (même résultat, pour comprendre) : Gemini Enterprise → l'app → Agents → + Ajouter un agent → Agent personnalisé via A2A → coller la carte (terraform output -json cards | python3 -c 'import json,sys; print(json.load(sys.stdin)["meteo"])') → Prévisualiser les détails de l'agent (nom, description, 2 compétences) → Suivant → Authentification : ignorer → Terminer. Détail de chaque champ : docs/09, 2.2.

8. Donner l'accès et tester dans le chat

1. Accès : app → Agents → Météo & équipement (A2A) → Autorisations utilisateur → Ajouter → le groupe des testeurs → rôle Agent User → Enregistrer. Idem pour les deux autres.
2. Test : ouvrir le lien de l'app web avec un compte testeur → Agents → Météo & équipement (A2A).

La toute première réponse peut prendre quelques secondes de plus (démarrage du conteneur : 0 instance au repos).

9. Variante : agents dans un autre projet

C'est le cas A de l'étape 3, et le cas Acme courant. Testé de bout en bout entre deux vrais projets. Le pas à pas complet (qui fait quoi, commandes, simulateur, fiche de demande) est dans docs/09, partie 3. En résumé :

Votre agent n'est pas déployé avec ce modèle ? Une commande par service suffit :

gcloud run services add-iam-policy-binding NOM_DU_SERVICE --region=europe-west1 --project=VOTRE_PROJET \
  --role=roles/run.invoker --member=serviceAccount:service-NUM_APP@gcp-sa-discoveryengine.iam.gserviceaccount.com

VPC Service Controls (projet 08) : si un périmètre entoure le projet de l'app, autoriser la sortie vers les services Cloud Run : docs/05 §3.

10. Modifier un agent, en ajouter un

• Modifier (consignes, outil) : éditer ../agents/trio/<agent>/agent.py, relancer python ../scripts/test_trio.py, puis terraform apply. L'empreinte du code de cet agent change → nouvelle image (Cloud Build) → nouvelle révision de son service seulement (modifier commun.py ou requirements.txt refait toutes les images). Rien d'autre à faire dans Gemini Enterprise : l'URL et la carte ne changent pas.
• Modifier la description ou les compétences : ../agents/trio/catalogue.json, puis terraform apply (carte mise à jour dans le service, le registre et l'app).
• Ajouter un agent : un dossier ../agents/trio/mon_agent/ (__init__.py + agent.py sur le modèle des autres) et une entrée dans catalogue.json (python ../scripts/nouvel_agent.py fait les deux), puis terraform apply. Rien à changer dans le Dockerfile. Terraform construit son image, crée le service, l'identité, les droits, l'entrée de registre et la publication. Pas à pas : docs/12-3.

11. Nettoyer

cd terraform && terraform destroy     # retire aussi les agents de l'app Gemini Enterprise

Destroy complete! avec autant de ressources que l'apply (63 pour 6 agents, 70 s'ils ont été publiés dans l'app). Les API restent activées (elles servent peut-être à autre chose). Le bucket gs://PROJET_cloudbuild (créé par Google pour les constructions) reste : à la main, gcloud storage rm -r gs://PROJET_cloudbuild. Inventaire de ce qui reste dans le projet (dont les comptes de construction) : python ../scripts/nettoyer.py (et --supprimer).

Dépannage

Ensuite : les mêmes agents sur Agent Runtime (hébergement géré, sessions gérées) : 02-bis-agent-runtime.