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 décrit les étapes essentielles pour déployer 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 ressources suivants :

Avant de commencer

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  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. Install the 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. Install the 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 console Google Cloud .

    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 de votre 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 pour 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 avec 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 le numéro de votre projet Google Cloud .
    • PROJECT_ID par l'ID de votre projet Google Cloud .
    • PRINCIPAL par le compte pour lequel vous ajoutez la liaison. Il s'agit généralement de l'adresse e-mail 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 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 installés de manière dynamique. Pour en savoir plus, consultez Configurer des secrets dans Cloud Run.

    Les agents ont besoin d'accéder à des services externes pour accomplir leurs tâches. Les secrets sont le mécanisme sécurisé permettant d'accorder cet accès. Lorsque vous déployez avec AlloyDB pour PostgreSQL, vous avez besoin de l'utilisateur et du mot de passe. Créez et gérez les secrets du nom d'utilisateur et du mot de passe de la base de données dans Secret Manager en exécutant les commandes suivantes dans 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 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. Lorsque vous déployez à 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 fichier Dockerfile détermine les détails de l'image du conteneur. Voici le fichier Dockerfile de l'agent A2A exemple 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âches 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é à 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'approche recommandée pour configurer l'authentification pour les clients Google Cloud internes, tels que Gemini Enterprise, consiste à utiliser l'indicateur --no-allow-unauthenticated lors du déploiement.

    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 pour 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 Google Cloud dans laquelle vous souhaitez déployer votre service, par exemple europe-west1.
    • PROJECT_ID : ID de votre 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 conserver les tâches A2A, 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 Google Cloud dans laquelle vous souhaitez déployer votre service, par exemple europe-west1.
    • PROJECT_ID : ID de votre 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.

    • URL non concordante : si l'URL run.app renvoyée par la commande de déploiement diffère de l'URL déterministe attendue, mettez à jour la variable d'environnement APP_URL 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 de votre projet.
        • REGION : région Google Cloud dans laquelle vous souhaitez déployer votre service. Par exemple : europe-west1.
        • CLOUD_RUN_SERVICE_URL : URL de votre service Cloud Run.

      2. Vérifiez que APP_URL est correctement mis à 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

    Si le déploiement réussit, Cloud Run fournit automatiquement une URL run.app 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. Établissez des pratiques de surveillance rigoureuses pour assurer 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 permet de s'assurer 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 : la fiche de votre agent s'affiche automatiquement.
    • Valide la conformité : vérifie que la fiche respecte les spécifications A2A.
    • Active le chat en direct : vous permet d'envoyer et de recevoir des messages de l'agent.
    • Afficher les données brutes : affiche les messages JSON-RPC 2.0 bruts dans une console pour le débogage.

    Interaction de la CLI avec un agent A2A déployé

    Utilisez les outils de l'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 les jetons du 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é en local. 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é.