08. Tutoriel complet : 3 agents utiles, 2 hébergements, même projet ou autre projet

Pour qui : les équipes qui veulent construire de vrais agents (avec des outils) et les rendre utilisables dans Gemini Enterprise, en code (Terraform), de façon reproductible. Résultat : trois agents dans le chat Gemini Enterprise, déployés au choix sur Cloud Run (A2A) ou sur Agent Runtime, dans le projet de l'app ou dans un autre projet, inscrits dans Agent Registry.

Les tutoriels 02 et 03 font la même chose à la main, dans la console, avec un seul agent. Celui-ci est la version industrialisée : trois agents, tout en Terraform, testé à chaque étape. Ce document contient les étapes communes ; chaque hébergement a ensuite son pas à pas.

Sommaire

1. Les 3 agents
2. Choisir : Cloud Run + A2A ou Agent Runtime ? Même projet ou autre projet ?
3. Prérequis (une fois)
4. Tester les agents sur votre poste
5. Déployer : la suite dans 01-bis ou 02-bis
6. Ce qui est vérifié

1. Les 3 agents

Le code est dans agents/trio/, une seule fois : les deux hébergements déploient exactement les mêmes fichiers.

agents/trio/
├── commun.py            accès au modèle Gemini (identité Vertex AI, ou clé d'API) + plugin Model Armor (obligatoire hors local)
├── catalogue.json       noms affichés, descriptions, compétences A2A : lu par Terraform (01-bis et 02-bis)
├── requirements.txt
├── meteo_agent/         agent.py : root_agent (l'agent), app (agent + Model Armor), agent_runtime_app (Agent Runtime)
├── redaction_agent/
└── traduction_agent/

Le catalogue contient aussi Conseil taille (taille_agent), Retours produits (retour_agent) et Identité utilisateur (identite_agent) : Terraform (01-bis, 02-bis) déploie toutes les entrées du catalogue, soit 6 agents. Ajouter le vôtre : docs/12-3.

Pourquoi un agent = des outils + des consignes : l'outil fait ce qu'un modèle fait mal (données réelles, calculs, règles exactes) ; le modèle fait ce qu'un outil fait mal (comprendre la demande, rédiger). Chaque consigne dit quand appeler chaque outil. C'est ce qui rend l'agent fiable.

Accès au modèle : identité (par défaut) ou clé d'API. commun.py choisit selon l'environnement :

Déployé, la clé n'est jamais en clair : on la range dans Secret Manager, puis on renseigne model_api_key_secret (et model_api_key_type) dans terraform.tfvars. Chaque agent ne peut lire que ce secret.

printf '%s' "VOTRE_CLE" | gcloud secrets create gemini-api-key --data-file=- --project=PROJET_DES_AGENTS
# terraform.tfvars : model_api_key_secret = "gemini-api-key"   model_api_key_type = "gemini"

Pourquoi Model Armor est dans l'agent : Gemini Enterprise ne filtre pas les agents qu'on lui ajoute (Agent Runtime comme A2A). Chaque agent filtre donc lui-même questions et réponses, et refuse de démarrer sans template (sauf en local, avec LOCAL_DEV=1).

2. Choisir

Hébergement

Les deux peuvent coexister : les noms affichés diffèrent (« … (A2A) » pour Cloud Run).

Même projet ou autre projet

Les deux fonctionnent avec le même code, et ont été testés entre deux vrais projets. Dans terraform.tfvars :

agents_project_id = "equipe-pricing-prod"   # le projet qui héberge les agents (le vôtre, ou celui de l'app)
ge_project_number = "98547854221"          # le NUMÉRO du projet de l'app, donné par l'admin Gemini Enterprise

Une équipe n'a besoin d'aucun droit sur le projet de l'app : Terraform ne s'en sert que pour publier, si l'on renseigne ge_project_id et ge_app_id (admin, ou tout dans le projet de l'app). Le pas à pas entre projets, avec le rôle de chacun : docs/09, partie 3.

Détail et règle générale : 05 – droits et régions.

3. Prérequis (une fois)

3.1 Les outils

Le plus simple : Cloud Shell (console Google Cloud, icône >_), où tout est installé. Sur un poste :

3.2 Se connecter

gcloud auth login                         # pour gcloud (et Cloud Build, qui construit les images de 01-bis)
gcloud auth application-default login     # pour Terraform et les tests Python
gcloud config set project aiml-gemini-entreprise-ldbr

3.3 Les projets

Dans chaque projet, activer les deux API dont Terraform a besoin avant son premier lancement (Terraform lit le numéro du projet, ce qui exige ces API ; sans elles : 403 Cloud Resource Manager API has not been used) :

for P in aiml-gemini-entreprise-ldbr acme-agents-demo; do      # un seul projet ? une seule valeur
  gcloud services enable cloudresourcemanager.googleapis.com serviceusage.googleapis.com --project=$P
done

Les autres API (Cloud Run, Agent Platform, Model Armor, Agent Registry…) sont activées par Terraform.

3.4 Vos droits

En CI, c'est le compte de service de la CI qui a ces rôles.

3.5 L'app Gemini Enterprise

• Elle existe (projets 06 / 08) : noter son ID (Gemini Enterprise → l'app → Présentation) et sa localisation (eu).
• Sinon : la créer (tutoriel 02, étape 1), en eu. Gemini Enterprise demande un compte d'organisation (Workspace / Cloud Identity), pas un Gmail.
• Pas encore d'app ? Vous pouvez tout faire sauf la publication : laissez ge_project_number vide. Les agents sont déployés, inscrits dans Agent Registry et testés ; on renseignera ge_project_number (et, pour publier soi-même, ge_project_id + ge_app_id) puis on relancera terraform apply.

3.6 Model Armor

4. Tester les agents sur votre poste

Pourquoi d'abord en local : si un agent ne marche pas ici, il ne marchera pas dans Gemini Enterprise. On sépare les problèmes d'agent des problèmes de droits.

cd 09-agents-multi-projets-gemini-enterprise
uv venv -p '>=3.12' .venv && source .venv/bin/activate
uv pip install -r agents/trio/requirements.txt

# 1. Tests hors ligne : outils, Model Armor obligatoire, points d'entrée (aucun appel Google ni Internet)
python scripts/test_trio.py                     # -> tests trio OK (9 scénarios, 6 agents)

# 2. Les agents en vrai (Gemini via Vertex AI, votre identité, sans clé d'API)
export LOCAL_DEV=1 GOOGLE_CLOUD_PROJECT=acme-agents-demo
adk web --port 8080 agents/trio                 # Cloud Shell : Aperçu sur le Web > port 8080

Dans l'interface, choisir l'agent en haut à gauche :

Ctrl+C pour arrêter.

No API key was provided : le modèle part vers l'API Gemini au lieu de Vertex AI. Vérifier que google-adk est bien en 2.10 dans le venv (pip show google-adk). default credentials were not found : refaire l'étape 3.2.

5. Déployer

Les deux suivent le même plan : configurer (terraform.tfvars) → déployer (terraform apply) → tester sans Gemini Enterprise (./test.sh) → vérifier Agent Registry → publier dans l'app → donner l'accès → tester dans le chat → nettoyer.

Tout rejouer d'un coup, commande par commande, avec la sortie attendue de chaque commande (projet X, projet A, simulateur, appel agent → agent entre projets) : docs/10.

Connecter à Gemini Enterprise (tous les modes de la fenêtre Ajouter un agent, procédure entre projets, simulateur, fiche de demande) : docs/09.

6. Ce qui est vérifié

Déployé de bout en bout sur un vrai projet Google Cloud (octobre 2026, même projet, sans app Gemini Enterprise : la publication dans l'app demande un compte d'organisation), puis entièrement supprimé avec terraform destroy.

Défauts trouvés par le déploiement réel, et corrigés (ils auraient bloqué n'importe qui suivant le tutoriel) :