12-1-6. Ajouter un agent dans l'app Gemini Enterprise : méthode **console** (interface Google Cloud)

Le but : dans l'app Gemini Enterprise de production de Acme, à la souris, ajouter un agent déjà en ligne, donner l'accès à un groupe, et le tester dans le chat. Mode par mode : Agent Runtime, A2A (Cloud Run), Dialogflow.

On part de là :

• les agents sont déployés et répondent dans le projet des agents aiml-gemini-ent-exp-0zga (12-1-1 Shell · 12-1-2 Terraform · 12-1-3 Console) ;
• l'app a le droit de les appeler (12-1-4) ;
• la simulation a répondu ACCEPTÉ (12-1-5).

Ici, on ne touche qu'à l'app Gemini Enterprise. Aucun rôle IAM, aucune API, aucun agent n'est créé ou modifié.

Pas testé en vrai. Les projets de test n'ont pas d'app Gemini Enterprise : les écrans sont décrits d'après la documentation officielle de Google (liens en fin de guide). Les libellés sont donnés en anglais, comme dans la documentation, avec la traduction probable quand la console est en français : ils peuvent légèrement varier selon la langue et la version de la console. Les commandes citées (scripts, curl, terraform output) sont celles des guides 12-1-1 et 12-1-2.

Sommaire

0. Avant de commencer
1. Production : les règles de prudence
2. Ouvrir l'app et noter ses valeurs
3. Récupérer, dans le projet des agents, ce que l'app demande
4. Ajouter l'agent dans l'app, mode par mode
5. Donner l'accès aux utilisateurs
6. Tester dans le chat
7. Modifier ou retirer un agent
8. Ce qui peut arriver

0. Avant de commencer

Les valeurs de ce guide :

Les noms des agents (exemple meteo), selon la méthode de déploiement :

La liste à cocher :

1. Production : les règles de prudence

C'est l'app que les collaborateurs utilisent. Quatre règles :

1. Un seul agent d'abord. Ajoutez meteo seul, testez-le jusqu'au bout (parties 4 à 6), puis les autres.
2. Un petit groupe de test d'abord. Donnez l'accès à votre adresse ou à un groupe de 2 ou 3 testeurs. Le groupe de toute l'équipe (equipe-agents@acme.example) seulement quand tout marche.
3. Savoir retirer vite (partie 7) :
   • le plus rapide : retirer le groupe dans User permissions de l'agent : l'agent disparaît pour eux, il reste dans l'app ;
   • définitif : supprimer l'agent de l'app (./scripts/add_agent_to_ge.sh delete "Météo & équipement"). L'agent lui-même (Cloud Run, Agent Runtime) n'est pas touché.
4. Rien ici ne change l'IAM. Ajouter un agent ou donner Agent User ne crée aucun rôle sur les projets. Les droits de l'app sur les agents se donnent (et se retirent) en 12-1-4.

Et : jamais deux agents du même nom dans l'app (les utilisateurs ne sauraient pas lequel choisir, et les scripts retrouvent les agents par leur nom).

Quota. Chaque ajout consomme une unité du quota quotidien de création d'agents du projet de l'app (documentation Google). En cas d'erreur 429 RESOURCE_EXHAUSTED, réessayez le lendemain.

2. Ouvrir l'app et noter ses valeurs

1. console.cloud.google.com, avec votre compte.
2. En haut, le sélecteur de projet → choisir acme-gemini-prod (le projet de l'app, pas celui des agents).
3. 🔎 « Gemini Enterprise » → la page Apps (Applications) s'ouvre : la liste des apps du projet.
4. Repérer l'app et noter :

Où voir ce compte : c'est lui qui appelle les agents. Dans le projet des agents, 🔎 « IAM » : il y figure (après 12-1-4) avec Discovery Engine Service Agent et/ou, sur chaque service Cloud Run, Demandeur Cloud Run (Cloud Run Invoker). Dans le projet de l'app, cochez Inclure les attributions de rôles fournies par Google pour le voir. Vous n'avez rien à faire avec ce compte ici.

Les mêmes valeurs en commandes (configuration chargée, comme en 12-1-4) :

./scripts/connecter_app.sh apps                    # LECTURE SEULE : APP_ID (1re colonne), emplacement (2e), nom
gcloud projects describe acme-gemini-prod --format='value(projectNumber)'    # 523307489860

Accès direct à la page des agents de l'app (le lien que Terraform affiche dans ge_agents_page) : https://console.cloud.google.com/gemini-enterprise/locations/eu/engines/dev_gemini-entreprise-app/agents?project=acme-gemini-prod

3. Récupérer, dans le projet des agents, ce que l'app demande

Changez de projet en haut : aiml-gemini-ent-exp-0zga. Ce que l'app demandera dépend du mode :

3.1 Agent Runtime : le nom de ressource

Console : 🔎 « Agent Runtime » (anciennement « Agent Engine », dans Vertex AI) → Déploiements → l'agent (meteo-shell, meteo-agent ou meteo-console) → en haut de la page, le nom de ressource projects/100000000002/locations/europe-west1/reasoningEngines/<ID> → copier.

Ou en commande (12-1-1, 8.2) :

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://europe-west1-aiplatform.googleapis.com/v1/projects/aiml-gemini-ent-exp-0zga/locations/europe-west1/reasoningEngines" \
  | python3 -c 'import json,sys; [print(e["displayName"], e["name"]) for e in json.load(sys.stdin).get("reasoningEngines",[])]'

Attendu : une ligne par agent, meteo-shell projects/100000000002/locations/europe-west1/reasoningEngines/…. Copiez la 2e colonne.

Ou, déployé par Terraform (12-1-2) :

cd $DOSSIER/02-bis-agent-runtime/terraform && terraform output agents

La région doit commencer par europe- : l'app est en eu (règle Google : app eu → agents en europe-*).

3.2 A2A (Cloud Run) : la carte de l'agent

La carte se fabrique avec le script du dépôt, à partir de l'URL du service (🔎 « Cloud Run » → le service → URL qui contient 433175138344) :

python3 scripts/carte_a2a.py meteo https://meteo-a2a-shell-433175138344.europe-west1.run.app > carte-meteo.json
cat carte-meteo.json

Attendu : une seule ligne de JSON, qui commence par {"protocolVersion": "0.3", "name": "meteo_agent", …. Copiez-la en entier, du premier { au dernier } (une ligne : rien à couper par erreur). Remplacez meteo-a2a-shell par meteo-a2a-console si l'agent a été déployé par la console.

Ou, déployé par Terraform (12-1-2 ; la sortie cards contient une carte par agent) :

cd $DOSSIER/01-bis-cloud-run-a2a/terraform
terraform output -json cards | python3 -c 'import json,sys; print(json.load(sys.stdin)["meteo"])'

Ou la lire sur l'agent en ligne (c'est la même, servie par l'agent) :

curl -s -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  https://meteo-a2a-shell-433175138344.europe-west1.run.app/.well-known/agent-card.json

(Elle contient en plus un champ supportedInterfaces, sans effet. Préférez carte-meteo.json.)

Les champs qui comptent (détail : 12-1-1, 7.6) :

3.3 Dialogflow : la source de l'agent

🔎 « Conversational Agents » → l'agent (ex. Accueil magasin) → Paramètres de l'agent (Agent settings) → copier le nom projects/…/locations/europe-west1/agents/<ID>.

Où créer l'agent Dialogflow : la documentation Google le décrit dans le projet de l'app ; un agent Dialogflow dans un autre projet n'y est pas documenté. Pour ce mode, créez-le dans acme-gemini-prod : 12-2.

3.4 Agent Registry : import depuis le catalogue

La tuile Agents from Agent Registry de l'app ne lit que le catalogue du projet de l'app : les agents du projet aiml-gemini-ent-exp-0zga n'y apparaissent pas. Pour ce mode : 12-2. Ici, utilisez Agent Runtime ou A2A.

4. Ajouter l'agent dans l'app, mode par mode

Le chemin commun, pour tous les modes :

1. Sélecteur de projet en haut : acme-gemini-prod.
2. 🔎 « Gemini Enterprise » → Apps → cliquer sur le nom de l'app (dev_gemini-entreprise-app).
3. Menu de gauche de l'app : Agents.
4. + Add agent (+ Ajouter un agent). Le panneau Choose an agent type (Choisir un type d'agent) s'ouvre, avec des tuiles :

Les noms à donner (les mêmes que les scripts et Terraform, pour s'y retrouver) :

Si l'agent est déjà dans l'app sous ce nom (via le script ou Terraform) : ne l'ajoutez pas une deuxième fois.

4.1 Agent Runtime

5. Sur la tuile Custom agent via Agent Runtime → Add (Ajouter).
6. Écran Authorizations (Autorisations) : n'ajoutez rien (nos agents n'agissent pas au nom de l'utilisateur). → Next (Suivant). Agent qui doit agir avec le compte de l'utilisateur (OAuth) : 12-1-7.
7. Écran de configuration :

8. Create (Créer).

Attendu : retour à la liste Agents, avec Météo & équipement (type Agent Runtime / ADK).

4.2 A2A (Cloud Run)

5. Sur la tuile Custom agent via A2A → Add (Ajouter).
6. Champ Agent card JSON (JSON de la carte d'agent) : coller toute la carte copiée en 3.2.
7. Preview agent details (Prévisualiser les détails de l'agent). Attendu : le nom, la description et les compétences de la carte s'affichent (pour meteo : « Météo d'une ville », « Quoi porter »). Sinon : partie 8.
8. Next (Suivant).
9. Écran d'autorisation (Client ID, Client secret…) : ne remplissez rien → Skip & Finish (Ignorer et terminer). Les champs OAuth ne servent que si l'agent agit avec le compte de l'utilisateur : 12-1-7.

Attendu : l'agent dans la liste Agents, type A2A (Custom).

Le nom affiché : l'app reprend celui de la carte (meteo_agent). Pour le renommer en Météo & équipement (A2A) : partie 7 (Edit), ou ajoutez-le par le script, qui prend le nom en paramètre : ./scripts/add_agent_to_ge.sh a2a carte-meteo.json "Météo & équipement (A2A)".

4.3 Dialogflow

5. Sur la tuile Custom agent via Dialogflow → Add (Ajouter). Le panneau Configuration s'ouvre.

6. Create (Créer). Attendu : Accueil magasin dans la liste Agents.

5. Donner l'accès aux utilisateurs

Un agent ajouté n'est visible de personne tant qu'on ne l'a pas partagé.

1. App → Agents → cliquer sur le nom de l'agent (Météo & équipement).
2. Onglet User permissions (Autorisations utilisateur). La page Permissioned users s'affiche.
3. Add user (Ajouter un utilisateur). La fenêtre « Add user permissions roles to agent » s'ouvre.
4. Remplir :

5. Save (Enregistrer).

Attendu : le groupe dans la liste Permissioned users, avec Agent User.

6. Tester dans le chat

1. App → menu de gauche Integration (Intégration) → copier le lien de l'app web.
2. L'ouvrir dans une fenêtre de navigation privée, connecté avec un membre du groupe (ou votre adresse, si c'est elle qui a reçu Agent User).
3. Dans l'app web : Agents → l'agent → poser la question d'exemple :

Attendu : une réponse en 20 à 40 secondes la première fois (l'agent démarre : cold start), plus vite ensuite. Pour meteo : la météo de la ville et un conseil de tenue.

Voir l'appel côté agents (sélecteur de projet → aiml-gemini-ent-exp-0zga) :

Rien dans les journaux alors que le chat affiche une erreur : l'app n'a pas pu appeler l'agent (partie 8).

Ensuite : les autres agents, un par un (parties 3 à 6), puis le groupe de toute l'équipe (partie 1).

7. Modifier ou retirer un agent

Modifier (nom, description, chemin, carte) : app → Agents → le nom de l'agent → Edit (Modifier) → changer les champs (Agent Runtime : Display name, Description, chemin ; A2A : Agent card JSON) → Save (Enregistrer).

Retirer l'accès (le plus rapide) : l'agent → User permissions → le groupe → supprimer (icône corbeille ou Remove) → Save. L'agent reste dans l'app, invisible pour ce groupe.

Supprimer de l'app : la documentation Google ne décrit la suppression que par l'API. Dans la console, selon la version : la liste Agents → le menu ⋮ de la ligne → Delete (Supprimer). Sinon, et pour être sûr, le script (configuration chargée) :

./scripts/add_agent_to_ge.sh list                                # les agents de l'app : nom affiché, type, ID
./scripts/add_agent_to_ge.sh delete "Météo & équipement"         # nom affiché EXACT ; l'agent lui-même reste

Tout défaire pour un agent (le retirer de l'app et retirer les droits de l'app sur lui, demande confirmation) :

./scripts/connecter_app.sh retirer meteo

Les droits : voir 12-1-4. L'agent (Cloud Run, Agent Runtime) se supprime ensuite, s'il le faut, avec 12-1-3, partie 10.

8. Ce qui peut arriver

Les sources Google : ajouter un agent ADK (Agent Runtime) · ajouter un agent A2A · ajouter un agent Dialogflow · partager un agent · rôles et licences.

Les autres guides : 12-1-4 Connecter (droits + script) · 12-1-5 Simuler l'appel · 12-1-7 Agents OAuth · 12-2 Agents dans le projet de l'app · 12-3 Ajouter des agents un par un.