将 A2A 智能体部署到 Cloud Run

本文档介绍了如何将 A2A 智能体部署到 Cloud Run。这些步骤可确保在云环境中安全、高效且可扩缩地运行。

准备工作

  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.

    Go to project selector

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

  4. Install the Google Cloud CLI.

  5. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

    Go to project selector

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

  9. Install the Google Cloud CLI.

  10. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. 导航到包含 A2A 智能体源代码的目录：

      cd PATH_TO_YOUR_AGENT_DIRECTORY

  13. 如需了解所需的 IAM 角色和权限，请参阅 Cloud Run A2A 智能体的 IAM 角色和权限。

配置 Cloud Run 服务身份验证

在 A2A 智能体完全开发并准备好部署环境后，您必须配置身份验证并使用 gcloud run deploy 命令将智能体部署到 Cloud Run。

使用以下选项之一为 A2A Cloud Run 服务配置访问权限和身份验证：

  • 针对内部 Google Cloud 客户端的基于 IAM 的身份验证：对于在 Google Cloud内运行的客户端（例如 Agentspace 等内部服务），建议采用基于 IAM 的身份验证这种安全方法。这些客户端使用服务账号，且需要 Cloud Run Invoker (roles/run.invoker) 角色才能调用您的 Cloud Run 服务。如需了解详情，请参阅 Cloud Run 服务间身份验证。

    如需为 Cloud Run 服务启用基于 IAM 的身份验证，请执行以下操作：

    • 您必须在部署期间使用 --no-allow-unauthenticated 标志。

  • 公开曝光的智能体级身份验证：如果您的 A2A 服务器设计为可公开访问，则它会处理智能体级身份验证。

    如需允许公开访问 Cloud Run 服务，请执行以下操作：

将 A2A 智能体部署到 Cloud Run

使用现有的 ADK 示例来部署 A2A 智能体。使用 gcloud run deploy 命令时，请指定以下参数：

  • 访问权限配置：
    • 如需使用基于 IAM 的服务身份验证，请使用 --no-allow-unauthenticated 标志。
    • 如需在互联网上公开服务，请使用 --allow-unauthenticated 标志。
  • 内存：容器实例运行所需的内存下限为 1Gi。
  • Secret：如需使用 Secret，请指定 DB_USER 和 DB_PASS 参数。
  • 服务账号：如需指定服务账号，请使用 a2a-service-account 参数。
  • 环境变量：如需指定环境变量，请使用以下变量：
    • APP_URL
    • DB_INSTANCE
    • DB_NAME
    • GOOGLE_GENAI_USE_VERTEXAI = true

对于本地测试，请使用内存中 TaskStore 配置。如需将服务部署到生产环境，您必须为生产 A2A 服务器使用持久性存储。请参阅 AlloyDB for PostgreSQL 部署部分中的示例。

使用内存中 TaskStore 配置进行部署

如需使用内存中 TaskStore 配置部署 A2A 智能体，请使用以下 gcloud run deploy 命令：

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"

如果您不在包含 A2A 智能体源代码的目录中，请使用智能体代码的完整路径更新 --source 标志。

替换以下内容：

  • REGION：您要在其中部署服务的 Google Cloud 区域。例如：europe-west1。
  • PROJECT_ID：您的项目 ID。
  • PROJECT_NUMBER：您的项目编号。

使用 AlloyDB for PostgreSQL 进行部署

如需持久保留 A2A 任务，请使用 AlloyDB for PostgreSQL。如需使用 AlloyDB for PostgreSQL 部署 A2A 智能体以实现持久性任务存储，请使用以下 gcloud run deploy 命令：

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"

如果您不在包含 A2A 智能体源代码的目录中，请使用智能体代码的完整路径更新 --source 标志。

替换以下内容：

  • REGION：您要在其中部署服务的 Google Cloud 区域。例如：europe-west1。
  • PROJECT_ID：您的项目 ID。
  • PROJECT_NUMBER：您的项目编号。
  • CLUSTER_NAME：AlloyDB for PostgreSQL 集群的名称。

了解 Cloud Run 应用网址

成功部署后，Cloud Run 会自动提供一个 run.app 网址，该网址可作为端点来查询您的有效 A2A 服务。如果服务名称足够短，则网址是确定性的且可预测。

  • Cloud Run 网址格式：https://TAG---SERVICE_NAME-PROJECT_NUMBER.REGION.run.app
  • 示例网址：https://sample-a2a-agent-1234.europe-west1.run.app

调试部署失败问题

如需调试 Cloud Run 部署失败问题，请考虑以下事项：

  • 详细日志：如需查看详细的部署日志，请在 gcloud run deploy 命令中设置 --verbosity=info 标志。

  • 网址不一致：如果部署命令返回的 run.app 网址与预期的确定性网址不同，请更新 Cloud Run 服务的 APP_URL 环境变量：

    1. 使用以下命令更新 APP_URL 环境变量：

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

      替换以下内容：

      • SERVICE_NAME：Cloud Run 服务的名称。
      • PROJECT_ID：您的项目 ID。
      • REGION：您要在其中部署服务的 Google Cloud 区域。例如：europe-west1。
      • CLOUD_RUN_SERVICE_URL：Cloud Run 服务的网址。

    2. 通过描述服务来验证 APP_URL 是否已正确更新：

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