04. Votre agent est déjà dans un Agent Registry : comment l'ajouter à notre stack ?

Pour qui : les équipes qui ont déjà un agent enregistré dans leur Agent Registry (leur projet GCP) et veulent qu'il soit utilisable dans notre app Gemini Enterprise, ou par nos agents. En une phrase : le registre sert à trouver l'agent et à savoir comment le joindre. Ensuite, l'ajout se fait par l'une de trois voies, selon le type d'agent et le niveau de gouvernance voulu.

Notre stack, c'est :

• le projet A, avec l'app Gemini Enterprise (eu), ses agents, et à terme son Agent Gateway et son registre ;
• votre projet B, avec votre agent et votre registre.

1. Les trois voies, en un tableau

Pourquoi on ne branche pas « directement votre registre » sur notre app. Gemini Enterprise n'importe des agents que depuis le registre relié à son Agent Gateway, dans la région de l'app (europe-west1 ou eu pour une app eu). Votre registre est dans votre projet ; le relier à notre passerelle d'un autre projet n'est pas documenté par Google (point à valider). Les voies 1 et 2 fonctionnent aujourd'hui, et la voie 3 passe par une déclaration de votre agent dans notre registre.

2. Étape commune : lire votre entrée de registre

Il faut d'abord savoir ce qu'est votre agent dans le registre. Trois façons, au choix.

Console (projet B) : 🔎 « Agent Registry » → région de l'agent (souvent europe-west1) → onglet Agents → cliquer sur l'agent → noter :

• l'identifiant (URN) ;
• les interfaces (URL, protocole) ;
• la présence d'une carte A2A.

gcloud :

gcloud agent-registry agents list --location=europe-west1 --project=VOTRE_PROJET
gcloud agent-registry agents describe NOM_AGENT --location=europe-west1 --project=VOTRE_PROJET

Notre script (il dit directement comment l'ajouter) :

python scripts/registry.py VOTRE_PROJET europe-west1
# - stock-agent: Donne le stock d'un article…
#     ajout : adk  projects/123/locations/europe-west1/reasoningEngines/456
# - pricing-a2a: Prix et promotions…
#     ajout : a2a  https://pricing-a2a-123.europe-west1.run.app/a2a/pricing/.well-known/agent-card.json  [carte A2A dans le registre]

Lire l'URN :

Contrôles avant d'aller plus loin :

• Région : notre app est en eu, donc l'agent doit être en europe-*. Sinon il faut le redéployer.
• A2A : la carte doit annoncer protocolVersion: "0.3". Un agent Cloud Run qui ne parle pas A2A (simple API REST) ne peut pas être ajouté tel quel : il faut l'exposer en A2A (ADK : adk deploy cloud_run --a2a, voir tutoriel 03, méthode 2).

3. Voie 1 : agent Agent Runtime, par nom de ressource

En une commande (pose aussi le droit si vous l'exécutez avec un compte qui a l'accès IAM au projet B) :

export GE_PROJECT=acme-ge-recette GE_APP=acme-ge GE_LOCATION=eu
./scripts/add_agent_to_ge.sh adk projects/123/locations/europe-west1/reasoningEngines/456 "Stock magasin" "Stock par magasin"

En production, par PR (Terraform pose le droit et publie) :

external_adk_agents = {
  stock = {
    engine       = "projects/acme-agents-supply/locations/europe-west1/reasoningEngines/456"
    display_name = "Stock magasin (Supply)"
    description  = "Stock d'un article par magasin, à partir du code article."
  }
}

4. Voie 2 : agent A2A, par sa carte

./scripts/add_agent_to_ge.sh a2a https://pricing-a2a-123.europe-west1.run.app/a2a/pricing/.well-known/agent-card.json "Prix et promotions"

Ce qui change par rapport à la voie 1 : Gemini Enterprise ne passe pas par Agent Gateway pour un agent A2A ajouté ainsi, et le Model Armor de l'app ne le filtre pas. Votre agent doit donc filtrer lui-même (plugin Model Armor).

5. Voie 3 : par notre registre et notre Agent Gateway (cible)

L'idée : notre registre devient le catalogue de tout ce que notre app peut joindre, y compris vos agents ; Agent Gateway refuse le reste.

Déclaration en Terraform (projet A) :

resource "google_agent_registry_service" "pricing" {
  location     = "europe-west1"
  service_id   = "pricing-a2a"
  display_name = "Prix et promotions (équipe Pricing)"
  description  = "Prix, promotions en cours et historique de prix d'un article."
  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = file("cards/pricing.json")      # la carte fournie par l'équipe ; son champ "url" donne l'adresse
  }
  # Pas de bloc interfaces avec une carte A2A : l'API le refuse (vérifié au déploiement de 01-bis).
}

resource "google_iap_agent_registry_agent_iam_member" "ge_to_pricing" {
  location = "europe-west1"
  agent_id = "pricing-a2a"                      # identifiant attribué par le registre (à vérifier après création)
  role     = "roles/iap.egressor"
  member   = "serviceAccount:service-NUM_A@gcp-sa-discoveryengine.iam.gserviceaccount.com"
}

Prérequis de la voie 3 : Agent Gateway liée à l'app (projet 08, enable_agent_gateway). Attention : notre projet 08 relie aujourd'hui la passerelle au registre global. Pour l'import dans une app eu, Google demande un registre europe-west1 ou eu : à corriger avant d'ouvrir cette voie.

6. Et si c'est un de nos agents qui doit appeler le vôtre ?

C'est le cas de l'« Assistant magasin » qui appelle l'agent stock (doc 06). Votre registre sert alors en direct : notre agent y cherche le vôtre. Vous donnez à l'identité de notre agent :

• roles/agentregistry.viewer sur votre projet (pour le trouver) ;
• roles/aiplatform.viewer sur votre agent (pour l'appeler), ou roles/run.invoker s'il est sur Cloud Run.

Rien à ajouter dans l'app : c'est un appel d'agent à agent.

7. Ce que l'équipe doit nous fournir (modèle de demande)

Avec ces informations, la voie 1 ou 2 se fait le jour même. La checklist de sécurité est celle de la doc 07, §6.

8. Résumé visuel

 VOTRE PROJET B                                         NOTRE PROJET A
 ┌─────────────────────────────┐                        ┌───────────────────────────────────────────┐
 │ Votre Agent Registry        │  (1) on lit l'entrée   │                                           │
 │  • agent Agent Runtime ─────┼──── nom de ressource ─▶│ Voie 1 : App GE → "via Agent Runtime"     │
 │  • agent A2A (Cloud Run) ───┼──── carte A2A ────────▶│ Voie 2 : App GE → "via A2A"               │
 │                         └───┼──── carte A2A ────────▶│ Voie 3 : NOTRE registre → Agent Gateway   │
 │                             │                        │           → import dans l'app             │
 │ IAM donné par VOUS :        │                        │                                           │
 │  discoveryengine.serviceAgent / run.invoker ────────▶│ compte de service de Gemini Enterprise    │
 │  agentregistry.viewer + aiplatform.viewer ──────────▶│ identité de NOS agents (appel direct, §6) │
 └─────────────────────────────┘                        └───────────────────────────────────────────┘

Voir aussi :

• 01 – modalités d'ajout ;
• 03 – matrice des droits ;
• 04 – pas à pas console ;
• 05 – qui peut le faire.