Déployer des agents A2A sur Cloud Run

Ce document explique comment déployer votre agent A2A sur Cloud Run. Ces étapes garantissent un fonctionnement sécurisé, efficace et évolutif dans l'environnement cloud.

Avant de commencer

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.

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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.

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

gcloud init

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 (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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.

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

gcloud init

1. Accédez au répertoire qui contient le code source de votre agent A2A :

     cd PATH_TO_YOUR_AGENT_DIRECTORY
     

2. Pour connaître les rôles et autorisations IAM requis, consultez Rôles et autorisations IAM pour les agents Cloud Run A2A.

Configurer l'authentification du service Cloud Run

Une fois votre agent A2A entièrement développé et son environnement de déploiement préparé, vous devez configurer l'authentification et utiliser la commande gcloud run deploy pour déployer l'agent sur Cloud Run.

Utilisez l'une des options suivantes pour configurer l'accès et l'authentification pour votre service A2A Cloud Run :

• Authentification basée sur IAM pour les clients Google Cloud internes : pour les clients opérant dans Google Cloud, tels que les services internes comme Agentspace, l'authentification basée sur IAM est l'approche sécurisée recommandée. Ces clients utilisent des comptes de service et nécessitent le rôle Demandeur Cloud Run (roles/run.invoker) pour appeler votre service Cloud Run. Pour en savoir plus, consultez Authentification de service à service Cloud Run.

  Pour activer l'authentification basée sur IAM pour votre service Cloud Run :

  • Vous devez utiliser l'option --no-allow-unauthenticated lors du déploiement.

• Authentification au niveau de l'agent pour l'exposition publique : si votre serveur A2A est conçu pour l'accès public, il gère l'authentification au niveau de l'agent.

  Pour autoriser l'accès public à votre service Cloud Run :

  • Vous devez 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 A2A Specification: SecurityScheme Object Details (Spécification A2A : détails de l'objet SecurityScheme).
  • Utilisez l'option --allow-unauthenticated lors du déploiement. Pour savoir comment autoriser l'accès public à votre service Cloud Run, consultez Authentification pour l'accès public à Cloud Run.

Déployer l'agent A2A sur Cloud Run

Utilisez l'exemple ADK existant pour déployer votre agent A2A. Spécifiez les paramètres suivants lorsque vous utilisez la commande gcloud run deploy :

• Configuration des accès :
  • Pour utiliser l'authentification de service basée sur IAM, utilisez l'option --no-allow-unauthenticated.
  • Pour rendre les services publics sur Internet, utilisez l'option --allow-unauthenticated.
• Mémoire : la mémoire minimale requise pour que l'instance de conteneur s'exécute est de 1Gi.
• Secrets : pour utiliser des secrets, spécifiez les paramètres DB_USER et DB_PASS.
• Compte de service : pour spécifier un compte de service, utilisez le paramètre a2a-service-account.
• Variables d'environnement : pour spécifier des variables d'environnement, utilisez les variables suivantes :
  • APP_URL
  • DB_INSTANCE
  • DB_NAME
  • GOOGLE_GENAI_USE_VERTEXAI = true

Pour les tests en local, utilisez une configuration TaskStore en mémoire. Pour déployer votre service en production, vous devez utiliser un stockage persistant pour un serveur A2A de production. Consultez un exemple dans la section Déploiement AlloyDB pour PostgreSQL.

Déployer avec une configuration TaskStore en mémoire

Pour déployer votre agent A2A avec une configuration TaskStore en mémoire, utilisez la commande gcloud run deploy suivante :

gcloud run deploy sample-a2a-agent \
    --port=8080 \
    --source="." \
    --no-allow-unauthenticated \
    --region=REGION \
    --project=PROJECT_ID \
    --memory=1Gi \
    --service-account=a2a-service-account \
    --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"

Si vous n'êtes pas dans le répertoire qui contient le code source de votre agent A2A, mettez à jour l'indicateur --source avec le chemin d'accès complet au code de votre agent.

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.

Déployer avec AlloyDB pour PostgreSQL

Pour conserver les tâches A2A, utilisez AlloyDB pour PostgreSQL. Pour déployer votre agent A2A avec AlloyDB for PostgreSQL pour le stockage persistant des tâches, utilisez la commande gcloud run deploy 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 \
    --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"

Si vous n'êtes pas dans le répertoire qui contient le code source de votre agent A2A, mettez à jour l'indicateur --source avec le chemin d'accès complet au code de votre agent.

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.

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

Déboguer les échecs de déploiement

Pour déboguer les é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 concordantes : 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"