Héberger un agent A2UI avec Cloud Run

Ce tutoriel explique comment déployer un agent Agent-to-Agent (A2A), créé avec le kit de développement d'agents (ADK) Google et l'extension A2UI, sur Cloud Run. Vous apprendrez également à enregistrer l'agent déployé auprès de Gemini Enterprise.

L'exemple de code de ce tutoriel présente la structure de dossiers suivante.

Structure des dossiers du tutoriel

Le projet présente la structure de dossiers suivante :

Fichier/Répertoire Description
examples/0.8/ Répertoire contenant des exemples de configurations ou de données.
__init__.py Marque le répertoire comme package Python.
agent.py Définit l'agent, ses compétences et son comportement.
agent_executor.py Gère le flux d'exécution et les interactions avec les outils.
contact_data.json Exemple de données utilisées par l'agent (par exemple, des contacts fictifs).
deploy.sh Script permettant de créer et de déployer l'agent sur Cloud Run.
main.py Point d'entrée principal de l'application (application FastAPI).
prompt_builder.py Assistant permettant de créer des requêtes pour le modèle.
pyproject.toml Configuration et dépendances du projet.
tools.py Définit les outils (fonctions) que l'agent peut utiliser.

Avant de commencer

Avant de commencer, assurez-vous de disposer des éléments suivants :

  • Le rôle Administrateur Discovery Engine.

  • Une application Gemini Enterprise existante. Pour créer une application, consultez Créer une application.

  • Clonez le dépôt et accédez au répertoire d'exemple cloud_run :

    git clone https://github.com/google/A2UI.git
cd A2UI/samples/agent/adk/gemini_enterprise/cloud_run

Activer les API

Activez les API suivantes pour votre projet :

Console

Activez les API suivantes :

  • API Agent Platform
  • API Cloud Build
  • API Artifact Registry
  • API Cloud Run
  • API Cloud Logging
  • API Discovery Engine
  • API Cloud Storage
  • API IAM (Identity and Access Management)

Activer les API

REST

Vous pouvez activer ces API à partir de la Google Cloud console ou à l'aide de la commande gcloud CLI suivante :

gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com run.googleapis.com logging.googleapis.com discoveryengine.googleapis.com storage.googleapis.com iam.googleapis.com

Accorder des autorisations

Accordez l'autorisation au rôle Demandeur Cloud Run (roles/run.invoker).

gcloud projects add-iam-policy-binding PROJECT_ID \
   --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"

Remplacez les éléments suivants :

  • PROJECT_ID : par l'ID du projet.
  • PROJECT_NUMBER : par le numéro de votre Google Cloud projet.

Déployer l'agent

Le script deploy.sh automatise le processus de déploiement. Pour déployer votre agent, exécutez le script à partir du répertoire du projet avec votre Google Cloud ID et un nom pour votre nouveau service. Vous pouvez également spécifier le modèle Gemini à utiliser.

Le script effectue les actions suivantes :

  1. Crée une image de conteneur à partir de votre code source.
  2. Transfère l'image vers Artifact Registry.
  3. Déploie l'image dans Cloud Run.
  4. Définit les variables d'environnement, y compris le MODEL et l'AGENT_URL public du service lui-même.
chmod +x deploy.sh
./deploy.sh YOUR_PROJECT_ID contacts-agent MODEL_NAME

Remplacez les éléments suivants :

  • PROJECT_ID : par l'ID du projet.
  • MODEL_NAME : facultatif. Il s'agit du troisième argument du script. Les valeurs acceptées sont gemini-2.5-pro et gemini-2.5-flash. Si aucune valeur n'est spécifiée, le script utilise par défaut gemini-2.5-flash.

Une fois le script terminé, il affiche l'URL du service de votre agent déployé. Vous aurez besoin de cette URL du service à l'étape suivante.

Enregistrer l'agent auprès de Gemini Enterprise

Maintenant que votre agent est déployé, vous devez l'enregistrer auprès de Gemini Enterprise pour le rendre détectable.

Exécutez la commande curl suivante en remplaçant les espaces réservés par vos propres valeurs :

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/ENGINE_ID/assistants/default_assistant/agents -d '{
"name": "contacts-agent",
"displayName": "Contacts Agent",
"description": "This is a test agent which lists the contacts.",
"a2aAgentDefinition": {
  "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"contacts-agent\", \"description\": \"This is a test agent which lists the contacts.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.8\", \"description\": \"Ability to render A2UI\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://a2ui.org/specification/v0_8/standard_catalog_definition.json\"]}}]}, \"skills\": [], \"defaultInputModes\": [\"text/plain\"], \"defaultOutputModes\": [\"text/plain\"]}"
}
}'

Remplacez les éléments suivants :

  • PROJECT_NUMBER : par le numéro de votre Google Cloud projet.
  • LOCATION : par l'emplacement multirégional de votre data store : global, us ou eu.
  • ENGINE_ID: par l'ID de l'application auprès de laquelle vous souhaitez enregistrer l'agent.
  • AGENT_URL : par l'URL du service de votre agent déployé.

Utiliser l'agent sur l'application Web Gemini Enterprise

Une fois un agent créé et enregistré, vous pouvez commencer à l'utiliser et à interagir avec lui sur l'application Web Gemini Enterprise.

Obtenir l'URL de l'application Web

Pour utiliser l'agent, vous devez d'abord obtenir l'URL de l'application Web. Un administrateur Gemini Enterprise peut obtenir et partager l'URL de l'application Web en procédant comme suit :

  1. Dans la Google Cloud console, accédez à la page Gemini Enterprise.

    Gemini Enterprise

  2. Cliquez sur le nom de l'application auprès de laquelle vous avez enregistré l'agent.

  3. Cliquez sur Integrations (Intégrations).

  4. Copiez le lien vers votre application Web et partagez-le avec les utilisateurs de l'organisation.

Utiliser l'agent

Pour utiliser l'agent et interagir avec lui, procédez comme suit :

  1. Ouvrez l'URL de l'application Web dans un nouvel onglet de navigateur.
  2. Dans le menu de navigation de l'application Web, cliquez sur Agents.
  3. Accédez à la section From your organization (De votre organisation), puis cliquez sur l'agent que vous avez créé.
  4. L'interface de conversation de l'agent s'ouvre. Commencez à poser des questions et à interagir avec l'agent.

Par exemple, vous pouvez demander à l'agent de lister tous les contacts. L'agent utilise l'outil list_contacts pour récupérer les contacts à partir de contact_data.json et affiche la liste dans le chat à l'aide d'éléments d'interface utilisateur personnalisés, comme illustré dans l'exemple suivant :

Exemple d'agent Contacts