Déployer des agents A2A sur Cloud Run

Préparez et configurez les agents Agent2Agent (A2A) pour le déploiement sur Cloud Run.

Ce guide couvre les étapes essentielles du déploiement des agents A2A :

Examiner la spécification A2A et les exemples d'agents

Avant de commencer à développer et à déployer votre agent A2A, familiarisez-vous avec les concepts et les ressources suivants :

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. Si vous n'avez jamais utilisé Google Cloud, créez un compte pour évaluer les performances de nos produits dans des scénarios réels. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Installez la Google Cloud CLI.

  5. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  6. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  8. Verify that billing is enabled for your Google Cloud project.

  9. Installez la Google Cloud CLI.

  10. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  11. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  12. Pour créer un compte de service, exécutez la commande suivante :
    13. gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

    Remplacez les valeurs suivantes :

    • A2A_SERVICE_ACCOUNT_NAME : nom du compte de service.

    • DESCRIPTION : description facultative du compte de service.

    • DISPLAY_NAME : nom de compte de service à afficher dans la Google Cloud console.

Attribuer des rôles au compte de service

Pour attribuer les rôles IAM requis à votre compte dans votre projet :

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

Remplacez :

  • PROJECT_ID : ID du projet.
  • A2A_SERVICE_ACCOUNT_NAME : nom de votre compte de service.
  • ROLE : rôle que vous ajoutez au compte de service.

Rôles requis

Pour obtenir les autorisations nécessaires afin de déployer des agents A2A, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Attribuer les rôles

Console

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

    Accéder à IAM
  2. Sélectionnez le projet.
  3. Cliquez sur Accorder l'accès.

  4. Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail utilisée pour déployer le service Cloud Run.

  5. Dans la liste Sélectionner un rôle, sélectionnez un rôle.
  6. Pour attribuer des rôles supplémentaires, cliquez sur Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
  7. Cliquez sur Enregistrer.

gcloud

Pour attribuer les rôles IAM requis à votre compte dans votre projet :

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

Remplacez :

  • PROJECT_NUMBER par votre Google Cloud numéro de projet.
  • PROJECT_ID par votre Google Cloud ID de projet.
  • PRINCIPAL par le compte pour lequel vous ajoutez la liaison. Il s'agit généralement de l'adresse e-mail qui est utilisée pour déployer le service Cloud Run.
  • ROLE par le rôle que vous ajoutez au compte du déployeur.

Préparer le déploiement Cloud Run

Cette section décrit les configurations requises pour préparer votre agent A2A au déploiement sur Cloud Run pour un exemple de code Python.

Préparer l'agent A2A

  1. Récupérez l'exemple de code en clonant le dépôt de l'exemple d'application sur votre ordinateur local :

    git clone https://github.com/a2aproject/a2a-samples

  2. Accédez au répertoire qui contient l'exemple de code :

    cd a2a-samples/samples/python/agents/adk_cloud_run

Configurer des secrets pour les services Cloud Run

Fournissez tous les identifiants sensibles, tels que les clés API et les mots de passe de la base de données, à votre serveur A2A à l'aide d'un mécanisme sécurisé. Cloud Run permet de fournir des secrets en tant que variables d'environnement ou volumes montés dynamiquement. Pour en savoir plus, consultez Configurer des secrets dans Cloud Run.

Les agents doivent accéder à des services externes pour effectuer leurs tâches. Les secrets sont le mécanisme sécurisé permettant d'accorder cet accès. Lorsque vous effectuez un déploiement avec AlloyDB pour PostgreSQL, vous avez besoin de l'utilisateur et du mot de passe. Créez et gérez les secrets du mot de passe et de l'utilisateur de la base de données dans Secret Manager en exécutant les commandes suivantes dans la gcloud CLI :

gcloud secrets create alloy_db_user --replication-policy="automatic"
# Create a file user.txt with contents of secret value
gcloud secrets versions add alloy_db_user --data-file="user.txt"

gcloud secrets create alloy_db_pass --replication-policy="automatic"
# Create a file pass.txt with contents of secret value
gcloud secrets versions add alloy_db_pass --data-file="pass.txt"

Pour en savoir plus, consultez la section Créer un secret.

Dockerfile pour la conteneurisation

Cloud Run peut déployer des services à partir d'images de conteneurs déjà hébergées ou directement à partir de votre code source. Lors du déploiement à partir du code source, Cloud Run crée automatiquement une image de conteneur si un Dockerfile est présent dans le répertoire racine de votre projet.

Le Dockerfile détermine les détails de l'image de conteneur. Voici le Dockerfile de l'exemple d'agent A2A que vous avez cloné précédemment :

FROM python:3.13-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
EXPOSE 8080
WORKDIR /app
COPY . ./
RUN uv sync
ENTRYPOINT ["uv", "run", ".", "--host", "0.0.0.0", "--port", "8080"]

Déployer à partir du code source sans Dockerfile

Pour les dépôts de code source sans Dockerfile, Cloud Run offre une prise en charge intégrée de certains langages de programmation courants, ce qui simplifie le processus de conteneurisation.

Déployer l'agent A2A sur Cloud Run

Déployez votre application A2A avec une configuration TaskStore en mémoire ou avec AlloyDB pour PostgreSQL.

  • Une configuration TaskStore en mémoire stocke toutes ses données exclusivement dans l'instance de conteneur Cloud Run. Cela signifie que toutes les données de tâche sont perdues lorsque l'instance de conteneur s'arrête, est réduite ou redémarre.
  • AlloyDB pour PostgreSQL assure la persistance des données, ce qui permet aux agents de s'adapter horizontalement et garantit que les tâches survivent aux redémarrages de conteneurs, aux événements de scaling et aux déploiements.

Une configuration TaskStore en mémoire est adaptée au développement d'agents A2A dans l'environnement local, et AlloyDB pour PostgreSQL est adaptée à la mise à l'échelle de l'agent A2A en production.

Les commandes suivantes montrent comment utiliser l'authentification basée sur IAM pour votre service Cloud Run. L'utilisation de l'indicateur --no-allow-unauthenticated lors du déploiement est l'approche recommandée pour configurer l'authentification pour les clients internes, tels que Gemini Enterprise. Google Cloud

Si votre serveur A2A est conçu pour un accès public et doit gérer l'authentification au niveau de l'agent, vous pouvez spécifier l'indicateur --allow-unauthenticated lors du déploiement. Pour en savoir plus, consultez Authentification de l'accès public à Cloud Run. Pour autoriser l'accès public à votre service Cloud Run, vous devez également fournir des informations d'authentification essentielles dans la fiche de votre agent A2A à l'aide des paramètres securitySchemes et security. Pour en savoir plus, consultez Spécification A2A : Détails de l'objet SecurityScheme.

Déployer avec une configuration TaskStore en mémoire

Pour déployer votre agent A2A avec une configuration TaskStore en mémoire, exécutez la commande suivante dans le répertoire contenant le code source de votre agent A2A :

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app"

Remplacez les éléments suivants :

  • REGION : région dans laquelle vous souhaitez déployer votre service, par exemple europe-west1. Google Cloud
  • PROJECT_ID : ID du projet.
  • PROJECT_NUMBER : votre numéro de projet.
  • A2A_SERVICE_ACCOUNT_NAME : nom de votre compte de service A2A.

Déployer avec AlloyDB pour PostgreSQL

Pour rendre les tâches A2A persistantes, utilisez AlloyDB pour PostgreSQL. Pour déployer votre agent A2A avec AlloyDB pour PostgreSQL pour le stockage persistant des tâches, utilisez la commande suivante :

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --update-secrets=DB_USER=alloy_db_user:latest,DB_PASS=alloy_db_pass:latest \
    --service-account=A2A_SERVICE_ACCOUNT_NAME \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT="PROJECT_ID",GOOGLE_CLOUD_LOCATION="REGION",APP_URL="https://sample-a2a-agent-PROJECT_NUMBER.REGION.run.app",USE_ALLOY_DB="True",DB_INSTANCE="projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_NAME/instances/primary-instance",DB_NAME="postgres"

Remplacez les éléments suivants :

  • REGION : région dans laquelle vous souhaitez déployer votre service, par exemple europe-west1. Google Cloud
  • PROJECT_ID : ID du projet.
  • PROJECT_NUMBER : votre numéro de projet.
  • CLUSTER_NAME : nom de votre cluster AlloyDB pour PostgreSQL.
  • A2A_SERVICE_ACCOUNT_NAME : nom de votre compte de service A2A.

Déboguer les échecs de déploiement

Si vous rencontrez des erreurs ou des échecs de déploiement Cloud Run, tenez compte des points suivants :

  • Journaux détaillés : pour obtenir des journaux de déploiement détaillés, définissez l'indicateur --verbosity=info dans votre commande gcloud run deploy.

  • Incompatibilité d'URL : si l'run.app URL renvoyée par la commande de déploiement diffère de l'URL déterministe attendue, mettez à jour la APP_URL variable d'environnement pour votre service Cloud Run :

    1. Utilisez la commande suivante pour mettre à jour la variable d'environnement APP_URL :

      gcloud run services update SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION" \
    --update-env-vars=APP_URL="CLOUD_RUN_SERVICE_URL"

      Remplacez les éléments suivants :

      • SERVICE_NAME : nom de votre service Cloud Run.
      • PROJECT_ID : ID du projet.
      • REGION : région dans laquelle vous souhaitez déployer votre service. Google Cloud Par exemple, europe-west1.
      • CLOUD_RUN_SERVICE_URL : URL de votre service Cloud Run.

    2. Vérifiez que l'URL APP_URL est correctement mise à jour en décrivant le service :

      gcloud run services describe SERVICE_NAME \
    --project="PROJECT_ID" \
    --region="REGION"

Comprendre l'URL de l'application Cloud Run

Une fois le déploiement réussi, Cloud Run fournit automatiquement une run.app URL qui sert de point de terminaison pour interroger votre service A2A actif. L'URL est déterministe et prévisible si le nom de votre service est suffisamment court.

  • Format de l'URL Cloud Run https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
  • Exemple d'URL : https://sample-a2a-agent-1234.europe-west1.run.app

Tester et surveiller le déploiement de l'agent A2A

Une fois votre agent A2A déployé sur Cloud Run, testez minutieusement ses fonctionnalités. Mettez en place des pratiques de surveillance rigoureuses pour garantir des performances et une fiabilité continues.

Inspecteur A2A : valider la conformité de l'agent

Utilisez l'outil a2a-inspector pour inspecter, déboguer et valider votre agent Google A2A déployé. Cet outil garantit que votre agent est entièrement conforme à la spécification A2A et qu'il fonctionne correctement.

Une fois la connexion établie, l'inspecteur effectue les actions suivantes :

  • Affiche la fiche de l'agent : affiche automatiquement la fiche de votre agent.
  • Valide la conformité : vérifie que la fiche est conforme aux spécifications A2A.
  • Active le chat en direct : vous permet d'envoyer et de recevoir des messages avec l'agent.
  • Affiche les données brutes : affiche les messages JSON-RPC 2.0 bruts dans une console pour le débogage.

Interaction CLI avec un agent A2A déployé

Utilisez les outils d'interface de ligne de commande (CLI) du dépôt d'exemples A2A pour interagir avec votre service déployé. Cette CLI est compatible avec l'authentification basée sur un jeton porteur.

Si votre service utilise l'authentification basée sur IAM, exportez le jeton gcloud pour une interaction réussie :

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

Remplacez CLOUD_RUN_SERVICE_URL par l'URL de votre service Cloud Run déployé.

Tests locaux des services A2A déployés

Vous pouvez tester votre service Cloud Run déployé localement. Cela est particulièrement utile lors de l'implémentation de l'authentification basée sur IAM.

Tester l'authentification basée sur IAM pour les agents Cloud Run

Les clients qui interagissent avec votre service Cloud Run sécurisé par Identity and Access Management (IAM) doivent disposer du rôle IAM roles/run.invoker.

Testez localement le flux d'authentification de votre service déployé à l'aide de la commande gcloud auth print-identity-token :

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

Remplacez CLOUD_RUN_SERVICE_URL par l'URL de votre service Cloud Run déployé.