Héberger un agent A2UI avec Cloud Run

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

Cet exemple utilise un exemple de code disponible publiquement. 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
/samples/community/agent/adk/gemini_enterprise/v0_9 Répertoire contenant des exemples de configurations et de données pour ce tutoriel.
__init__.py Marque le répertoire comme package Python.
__main__.py Point d'entrée pour exécuter l'agent en local.
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.
deploy.sh Script permettant de créer et de déployer l'agent sur Cloud Run.
examples/ Répertoire contenant des exemples de modèles de composants.
gemini_enterprise_composite_catalog.json Catalogue de composants définissant les composants Gemini Enterprise standards et personnalisés.
main.py Point d'entrée principal de l'application (application FastAPI).
prompt_builder.py Assistant permettant de créer des prompts pour le modèle.
pyproject.toml Configuration et dépendances du projet.
examples/0.9/material_table_orders.json Exemple de modèle d'UI contenant la mise en page et des exemples de données pour la démonstration des commandes récentes.
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 v0_9 :

    git clone https://github.com/a2ui-project/a2ui.git
cd a2ui/samples/community/agent/adk/gemini_enterprise/v0_9

Activer les API

Activez les API suivantes pour votre projet :

Console

Activez les API suivantes :

  • API Vertex AI
  • 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

Octroyer 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 PROJECT_ID a2ui-demo-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 fournie, 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 de service à l'étape suivante.

Enregistrer l'agent avec Gemini Enterprise

Maintenant que votre agent est déployé, vous devez l'enregistrer avec 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": "a2ui-demo-agent",
  "displayName": "A2UI v0.9 Demo Agent",
  "description": "A demo agent that showcases A2UI v0.9 UI templates.",
  "a2aAgentDefinition": {
      "jsonAgentCard": "{\"protocolVersion\": \"0.3.0\", \"name\": \"A2UI v0.9 Demo\", \"description\": \"A demo agent that showcases A2UI v0.9 UIs built from the Material component catalog and Gemini Enterprise custom components (Canvas, Iframe). Ask it what can you do? to see the available demos.\", \"url\": \"AGENT_URL\", \"version\": \"1.0.0\", \"capabilities\": {\"streaming\": true, \"preferredTransport\": \"JSONRPC\", \"extensions\": [{\"uri\": \"https://a2ui.org/a2a-extension/a2ui/v0.9\", \"description\": \"Ability to render A2UI v0.9\", \"required\": false, \"params\": {\"supportedCatalogIds\": [\"https://www.gstatic.com/vertexaisearch/a2ui/v0_9/gemini_enterprise_composite_catalog.json\"]}}]}, \"skills\": [{\"id\": \"a2ui_demo\", \"name\": \"A2UI v0.9 Component Demo\", \"description\": \"Demonstrates A2UI v0.9 UIs built from the Material catalog and Gemini Enterprise custom components: cards, forms & inputs, tabs, tables, progress indicators, dialogs & menus, the Canvas side panel, and the Iframe (IFrameSrcdoc / IFrameUrl) components.\"}], \"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 avec laquelle vous souhaitez enregistrer l'agent.
  • AGENT_URL : par l'URL de service de votre agent déployé.

Annuler l'enregistrement de l'agent (facultatif)

Si vous souhaitez annuler l'enregistrement de l'agent, exécutez la commande curl suivante :

curl -X DELETE -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/AGENT_ID

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 avec laquelle l'agent est enregistré.
  • AGENT_ID : par l'ID de l'agent que vous souhaitez supprimer.

Utiliser l'agent sur l'application Web Gemini Enterprise

Une fois l'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 avec 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 utiliser un prompt tel que Show me the recent orders table (Afficher le tableau des commandes récentes) pour obtenir des informations sur les commandes récentes qui font partie des exemples de données. L'agent récupère les informations de commande à partir de material_table_orders.json et affiche la liste dans le chat à l'aide de composants d'UI personnalisés, comme illustré dans l'exemple suivant :

Exemple de tableau des commandes récentes