在 Cloud Run 上托管 A2A 智能体概览

本指南概述了如何准备和配置 Agent2Agent (A2A) 智能体以在 Cloud Run 上进行部署。其中涵盖了基本步骤，例如设置云环境、配置所需的 Identity and Access Management (IAM) 角色，以及准备部署智能体。

准备工作

在开始开发和部署 A2A 智能体之前，请先熟悉以下概念和资源：

A2A 智能体部署路线图

如需部署智能体，请完成以下步骤：

概要架构

A2A 智能体的核心是服务和编排层，例如 Cloud Run。该层通过 API 管理与 Gemini 和 Vertex AI 等 AI 模型、AlloyDB 和 A2A TaskStore 等内存存储空间以及外部工具的互动。客户端通过发送“获取智能体卡片”或“发送消息”等请求与智能体互动，并接收任务更新。

下图展示了 A2A 智能体系统的架构，其中显示了 A2A 客户端（用户或智能体）与 A2A 智能体之间的互动。

A2A 智能体架构，显示了客户端通过服务和编排层与智能体的互动。
A2A 智能体架构

如需了解有关 A2A 请求生命周期的信息，请参阅 A2A 请求生命周期部分。

Cloud Run A2A 智能体的 IAM 角色和权限

正确配置 IAM 角色对于 Cloud Run 服务与其他 Google Cloud服务安全互动至关重要。创建专用服务账号并授予以下各部分中列出的特定权限，以确保运营安全和效率。

创建 Cloud Run 服务账号

在运行任何 gcloud 命令之前，确保您已通过身份验证。运行以下命令以登录您的 Google Cloud 账号：

gcloud auth login

专门为已部署的 A2A 服务实例创建服务账号。 使用 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"

将 A2A_SERVICE_ACCOUNT_NAME 替换为服务账号的名称。

为 A2A 智能体配置 IAM 角色

根据 A2A 智能体所互动的 Google Cloud服务，向您的服务账号分配以下 IAM 角色：

安全凭证的 Secret Manager 访问权限

  • 角色：Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

  • 用途：允许 Cloud Run 服务账号从 Secret Manager 安全地提取 Secret（例如数据库凭证）。

    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"

AI 功能的 Vertex AI 模型访问权限

  • 角色：Vertex AI User (roles/aiplatform.user)

  • 用途：Cloud Run 服务账号必须具备此权限，才能在 Vertex AI 模型上调用 Prediction API。

    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"

永久性存储的 Alloy DB 实例访问权限（如果适用）

  • 角色：AlloyDB Client (roles/alloydb.client) 和 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

  • 用途：使 Cloud Run 服务身份能够与 AlloyDB 集群进行互动，以实现持久性任务存储，这对于生产环境中的 A2A 智能体至关重要。

    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"

准备 A2A 智能体进行 Cloud Run 部署

本部分介绍了准备将 A2A 智能体部署到 Cloud Run 所需的配置，以确保在云中安全、高效和可扩缩地运行。

为 Cloud Run 服务配置 Secret

使用安全机制向 A2A 服务器提供所有敏感凭证，例如 API 密钥和数据库密码。Cloud Run 支持将 Secret 作为环境变量提供或动态装载为卷。如需了解详情，请参阅在 Cloud Run 中配置 Secret。

例如，使用 gcloud CLI 在 Google Secret Manager 中创建和管理数据库用户和密码 Secret。如需了解详情，请参阅创建 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"

创建用于容器化的 Dockerfile

Cloud Run 可以从已托管的容器映像部署服务，也可以直接从源代码部署服务。从源代码进行部署时，如果项目根目录中存在 Dockerfile，Cloud Run 会自动构建容器映像。

以下是 A2A 智能体部署的示例 Dockerfile：

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"]

无需 Dockerfile 即可从源代码部署

对于没有 Dockerfile 的源代码库，Cloud Run 为某些热门编程语言提供内置支持，从而简化容器化流程。

后续步骤