02-bis. Les 3 agents sur Agent Runtime, dans Gemini Enterprise

Pour qui : équipes qui veulent la voie recommandée pour un agent ADK : hébergement géré par Google, sessions et journaux inclus, inscription automatique dans Agent Registry. Résultat : « Météo & équipement », « Rédaction & reformulation » et « Traduction Acme » dans le chat Gemini Enterprise, chacun sur Agent Runtime avec son identité, depuis le projet de l'app ou depuis votre propre projet.

Avant de commencer : docs/08, étapes 1 à 4 (prérequis et test local des agents). Pas besoin de Docker : Terraform envoie le code, Google construit et héberge.

 Projet AGENTS (B, ou A si même projet)                          Projet APP (A)
┌─────────────────────────────────────────────────────────┐     ┌────────────────────────────────────┐
│ Agent Runtime (europe-west1)              identité      │     │ App Gemini Enterprise (eu)         │
│  meteo-agent       entrée meteo_agent.agent  meteo-…-sa │◀────┼─ Météo & équipement                │
│  redaction-agent   entrée redaction_agent…   redaction… │ API │  Rédaction & reformulation         │
│  traduction-agent  entrée traduction_agent…  traduction…│     │  Traduction Acme              │
│        │ inscription AUTOMATIQUE                        │     │                                    │
│        ▼                                                │     │ service-NUM_A@gcp-sa-discovery…    │
│ Agent Registry (europe-west1)                           │     │  (compte de Gemini Enterprise)     │
│ IAM, autre projet seulement :                           │     └────────────────────────────────────┘
│  discoveryengine.serviceAgent ──▶ compte GE du projet A │
└─────────────────────────────────────────────────────────┘

Sommaire

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

1. Comprendre ce qui va être créé

Comment le code part chez Google : Terraform compresse ../agents/trio (de façon déterministe : même code = mêmes octets = pas de redéploiement), l'envoie à Agent Runtime avec requirements.txt, et indique le point d'entrée de chaque agent : meteo_agent.agent, objet agent_runtime_app (l'agent avec son plugin Model Armor).

Une identité par agent (meteo-agent-sa…) : l'agent n'a que ses droits (Gemini, journaux, Model Armor), pas ceux du compte partagé du projet.

Le droit d'appel de Gemini Enterprise :

• même projet : rien à faire, Google a déjà donné au compte de Gemini Enterprise le rôle Discovery Engine Service Agent sur son projet ;
• autre projet : ce rôle est donné dans le projet des agents (Terraform le fait, étape 8).

2. Configurer

cd 09-agents-multi-projets-gemini-enterprise/02-bis-agent-runtime/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 6, 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 / response_template. Sinon Terraform crée trio-runtime-prompt-shield / trio-runtime-response-shield dans le projet des agents.

Pourquoi europe-west1 : une app eu n'accepte que des agents Agent Runtime en europe-* (règle Google, vérifiée par Terraform).

3. Déployer les agents

terraform init
terraform plan       # lire : ~27 ressources à créer, dont 3 google_vertex_ai_reasoning_engine (28 en cas A : + 1 droit)
terraform apply      # taper "yes" ; 10 à 15 min (Google installe les dépendances de chaque agent)

Attendu à la fin :

Apply complete! Resources: 28 added, 0 changed, 0 destroyed.     (cas A)
Outputs:
agents = {
  "meteo"      = "projects/aiml-gemini-entreprise-ldbr/locations/europe-west1/reasoningEngines/1111111111"
  "redaction"  = "projects/aiml-gemini-entreprise-ldbr/locations/europe-west1/reasoningEngines/2222222222"
  "traduction" = "projects/aiml-gemini-entreprise-ldbr/locations/europe-west1/reasoningEngines/3333333333"
}

Ces noms de ressource identifient chaque agent : c'est ce qu'on donne à Gemini Enterprise.

Dans la console : 🔎 « Agent Runtime » (menu Agent Platform → Déploiements) → meteo-agent, redaction-agent, traduction-agent. Cliquer sur l'un : onglets Playground (tester), Journaux, Sessions.

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

cd ..                                   # 02-bis-agent-runtime
source ../.venv/bin/activate            # le venv de docs/08 §4 (contient le SDK Agent Platform)
./test.sh

Attendu (extrait) :

== meteo  (projects/…/reasoningEngines/1111111111)
  -> outil : meteo({'ville': 'Lille', 'jours': 2})
  -> outil : conseil_equipement({'temperature_c': 10.7, 'pluie_mm': 6.2, 'vent_kmh': 26.3, 'activite': 'course à pied'})
agent : Demain matin à Lille, pluie faible et 10 °C … veste imperméable et respirante …
== traduction  (…)
  -> outil : glossaire({'langue_cible': 'es'})
  -> outil : verifier_traduction(…)
agent : Tu tienda de campaña Quechua está disponible para recogida en tienda. Contrôle : conforme

Ou, pour un seul agent : Playground de l'agent dans la console, mêmes questions qu'en local (docs/08 §4).

Pourquoi ce test : il appelle l'agent comme le fera Gemini Enterprise (API Agent Runtime, session, utilisateur). Si ici tout marche et que le chat échoue, le problème est dans la publication ou les droits (étapes 6-7).

La toute première question d'un agent peut prendre 20 à 40 secondes : démarrage (0 instance au repos).

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.

5. Vérifier Agent Registry

Un agent Agent Runtime s'inscrit seul dans l'Agent Registry de son projet, dans sa région. Rien à déclarer.

gcloud agent-registry agents list --location=europe-west1 --project=aiml-gemini-entreprise-ldbr
python ../scripts/registry.py aiml-gemini-entreprise-ldbr europe-west1            # depuis 02-bis-agent-runtime

Attendu : meteo-agent, redaction-agent, traduction-agent (vérifié), avec pour chacun la ligne d'ajout adk projects/…/reasoningEngines/….

À quoi ça sert : une autre équipe (ou un de ses agents) trouve vos agents par leur nom ou par recherche (python ../scripts/registry.py aiml-gemini-entreprise-ldbr europe-west1 "traduire un texte"), sans vous demander d'identifiant. Si vous redéployez, l'identifiant change dans le registre, pas le nom.

6. 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 noms de ressource (terraform output agents) : docs/09, étapes 5 et 6. Le droit d'appel (discoveryengine.serviceAgent sur votre projet) 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 ×3, Resources: 4 added (API Discovery Engine + 3 agents dans l'app, mode Agent personnalisé via Agent Runtime). Même projet : aucun droit à ajouter, Google l'a déjà donné.

Ou dans la console : Gemini Enterprise → l'app → Agents → + Ajouter un agent → Agent personnalisé via Agent Runtime → Nom de l'agent Météo & équipement, Décrivez votre agent (copier depuis ../agents/trio/catalogue.json), Chemin de ressource Agent Runtime : terraform output -json agents → valeur meteo → Créer. Détail de chaque champ : docs/09, 2.1.

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

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

Ce qui s'est passé : Agent Runtime → meteo-agent → Sessions : une session par conversation, avec les appels d'outils ; l'utilisateur est celui du chat.

8. Variante : agents dans un autre projet

C'est le cas A de l'étape 2, 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 suffit :

gcloud projects add-iam-policy-binding VOTRE_PROJET --condition=None \
  --role=roles/discoveryengine.serviceAgent \
  --member=serviceAccount:service-NUM_APP@gcp-sa-discoveryengine.iam.gserviceaccount.com

9. Aller plus loin : un agent qui appelle ces agents

Un agent « assistant magasin » peut déléguer à traduction-agent ou meteo-agent : il le trouve dans Agent Registry, puis l'appelle avec sa propre identité, qui reçoit roles/aiplatform.viewer sur l'agent appelé seulement. Le modèle complet (code, droits, tests) est l'orchestrateur du projet 09 : docs/06.

10. Modifier un agent, en ajouter un

• Modifier : éditer ../agents/trio/<agent>/agent.py, python ../scripts/test_trio.py, puis terraform apply. Les 3 agents partagent le même dossier de code : tous les 3 sont mis à jour (5 à 10 min). Leur nom de ressource ne change pas : rien à refaire dans Gemini Enterprise.
• Nom affiché, description : ../agents/trio/catalogue.json, puis terraform apply.
• Ajouter un agent : un dossier ../agents/trio/mon_agent/ sur le modèle des autres, une entrée dans catalogue.json, terraform apply : agent, identité, droits, registre et publication sont créés.

11. Nettoyer

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

Coût au repos : nul (0 instance minimum). À l'usage : Agent Runtime (temps de calcul), Gemini (jetons), Model Armor.

Dépannage

Voir aussi : les mêmes agents en A2A sur Cloud Run : 01-bis-cloud-run-a2a.