Présentation de l'hébergement d'agents A2A sur Cloud Run

Ce guide explique comment préparer et configurer les agents Agent2Agent (A2A) pour le déploiement sur Cloud Run. Il couvre les étapes essentielles, comme la configuration d'un environnement cloud, la configuration des rôles IAM (Identity and Access Management) requis et la préparation de votre agent au déploiement.

Avant de commencer

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

Feuille de route du déploiement de l'agent A2A

Pour déployer votre agent, procédez comme suit :

Architecture de haut niveau

L'agent A2A est basé sur une couche de diffusion et d'orchestration, telle que Cloud Run. Cette couche gère les interactions avec les modèles d'IA tels que Gemini et Vertex AI, les espaces de stockage de mémoire tels qu'AlloyDB et A2A TaskStore, ainsi que les outils externes via les API. Les clients interagissent avec l'agent en envoyant des requêtes, telles que "Obtenir la fiche de l'agent" ou "Envoyer un message", et reçoivent des informations sur l'état des tâches.

Le schéma suivant illustre l'architecture d'un système d'agent A2A, montrant un client A2A (utilisateur ou agent) interagissant avec l'agent A2A.

Architecture de l'agent A2A montrant l'interaction du client avec l'agent via une couche de diffusion et d'orchestration.
Architecture de l'agent A2A

Pour en savoir plus sur le cycle de vie des requêtes A2A, consultez la section Cycle de vie des requêtes A2A.

Rôles et autorisations IAM pour les agents Cloud Run A2A

Il est important de configurer correctement les rôles IAM pour que votre service Cloud Run puisse interagir de manière sécurisée avec d'autres services Google Cloud. Créez un compte de service dédié et accordez les autorisations spécifiques listées dans les sections suivantes pour garantir la sécurité et l'efficacité opérationnelles.

Créer un compte de service Cloud Run

Avant d'exécuter des commandes gcloud, assurez-vous d'être authentifié. Exécutez la commande suivante pour vous connecter à votre compte Google Cloud  :

gcloud auth login

Créez un compte de service spécifiquement pour votre instance de service A2A déployée. Exécutez la commande gcloud iam service-accounts create.

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="Service account for A2A Cloud Run service" \
  --display-name="A2A Cloud Run Service Account"

Remplacez A2A_SERVICE_ACCOUNT_NAME par le nom du compte de service.

Configurer les rôles IAM pour l'agent A2A

Attribuez les rôles IAM suivants à votre compte de service en fonction des services Google Cloudavec lesquels votre agent A2A interagit :

Accès à Secret Manager pour les identifiants sécurisés

  • Rôle : Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • Objectif : permet au compte de service Cloud Run d'extraire de manière sécurisée des secrets, tels que des identifiants de base de données, depuis Secret Manager.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Accès aux modèles Vertex AI pour les fonctionnalités d'IA

  • Rôle : Vertex AI User (roles/aiplatform.user)

  • Objectif : requis pour que le compte de service Cloud Run puisse appeler les API de prédiction sur les modèles Vertex AI.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Accès à l'instance AlloyDB pour le stockage persistant (le cas échéant)

  • Rôles : AlloyDB Client (roles/alloydb.client) et Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • Objectif : permet à l'identité de service Cloud Run d'interagir avec le cluster AlloyDB pour le stockage persistant des tâches, ce qui est essentiel pour les agents A2A de production.

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

Préparer l'agent A2A pour le déploiement Cloud Run

Cette section décrit les configurations requises pour préparer votre agent A2A au déploiement sur Cloud Run, en garantissant un fonctionnement sécurisé, efficace et évolutif dans le cloud.

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.

Par exemple, créez et gérez des secrets de mot de passe et d'utilisateur de base de données dans Google Secret Manager à l'aide de la CLI gcloud. Pour en savoir plus, consultez Créer un secret.

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"

Créer un fichier 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.

Voici un exemple de fichier Dockerfile pour le déploiement d'un agent A2A :

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 fichier 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 populaires, ce qui simplifie le processus de conteneurisation.

Étapes suivantes