Héberger un agent A2UI avec Cloud Run

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

Cet exemple utilise un exemple de code accessible au public. L'exemple de code de ce tutoriel présente la structure de dossiers suivante.

Structure des dossiers du tutoriel

La structure de dossiers du projet est la 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 en tant que package Python.
__main__.py Point d'entrée pour exécuter l'agent localement.
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 l'agent et de le déployer 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 Material standards et les composants Gemini Enterprise personnalisés.
main.py Le point d'entrée principal de l'application (application FastAPI).
prompt_builder.py Outil d'aide pour créer des requêtes pour le modèle.
pyproject.toml Configuration et dépendances du projet.
examples/0.9/material_table_orders.json Exemple de modèle d'interface utilisateur contenant la mise en page et les données fictives 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, vérifiez que vous disposez 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 de l'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 depuis la console Google Cloud 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 : ID de votre projet.
  • PROJECT_NUMBER : numéro de votre projet Google Cloud .

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 ID Google Cloud 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 l'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 gemini-2.5-flash par défaut.

Une fois l'exécution du script terminée, l'URL du service de votre agent déployé s'affiche. Vous aurez besoin de cette URL de 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 qu'il soit visible.

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 : numéro de votre projet Google Cloud .
  • LOCATION : emplacement multirégional de votre data store : global, us ou eu
  • ENGINE_ID : ID de l'application auprès de laquelle vous souhaitez enregistrer l'agent.
  • AGENT_URL : 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 : numéro de votre projet Google Cloud .
  • LOCATION : emplacement multirégional de votre data store : global, us ou eu
  • ENGINE_ID : ID de l'application auprès de laquelle l'agent est enregistré.
  • AGENT_ID : ID de l'agent que vous souhaitez supprimer.

Utiliser l'agent sur l'application Web Gemini Enterprise

Une fois qu'un agent est créé et enregistré, vous pouvez commencer à l'utiliser et à interagir avec lui dans 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 console Google Cloud , 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 du navigateur.
  2. Dans le menu de navigation de l'application Web, cliquez sur Agents.
  3. Accédez à la section De votre organisation, puis cliquez sur l'agent que vous avez créé.
  4. L'interface conversationnelle 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 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'interface utilisateur personnalisés, comme illustré dans l'exemple suivant :

Exemple de tableau des commandes récentes