将 A2A 智能体部署到 Cloud Run

准备和配置 Agent2Agent (A2A) 代理以在 Cloud Run 上进行部署。

本指南介绍了部署 A2A 代理的基本步骤：

配置您的项目
建立 IAM 角色
配置云环境
部署代理
调试部署失败问题
测试和监控

查看 A2A 规范和示例代理

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

查看官方 A2A 规范和代理通信概念，了解代理通信。
探索现有的示例代理。
查看 ADK Cloud Run 示例。

准备工作

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

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

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。

如需初始化 gcloud CLI，请运行以下命令：

gcloud init

要创建服务账号，请运行以下命令：

gcloud iam service-accounts create A2A_SERVICE_ACCOUNT_NAME \
  --description="DESCRIPTION" \
  --display-name="DISPLAY_NAME"

替换以下值：

A2A_SERVICE_ACCOUNT_NAME：服务账号的名称
DESCRIPTION：服务账号的可选说明
DISPLAY_NAME：要在 Google Cloud 控制台中显示的服务账号名称

向服务账号授予角色

如需向您的账号授予针对项目的所需 IAM 角色，请执行以下操作：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member="serviceAccount:A2A_SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
         --role="ROLE"

您需要进行如下替换：

PROJECT_ID：您的项目 ID
A2A_SERVICE_ACCOUNT_NAME：您的服务账号的名称
ROLE：您要添加到服务账号的角色

所需的角色

如需获得部署 A2A 代理所需的权限，请让您的管理员为您授予以下 IAM 角色：

项目的 Cloud Run Source Developer (roles/run.sourceDeveloper) 角色
针对项目的 Project IAM Admin (roles/resourcemanager.projectIamAdmin)
项目的 Secret Manager Admin (roles/secretmanager.admin)
服务身份的 Service Account User (roles/iam.serviceAccountUser) 角色
服务账号的 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)
服务账号的 Vertex AI User (roles/aiplatform.user)
如果您要使用 AlloyDB for PostgreSQL 进行部署，请授予以下角色：
- 服务账号的 AlloyDB for PostgreSQL Client (roles/alloydb.client)
- 服务账号的 Project IAM Admin (roles/resourcemanager.projectIamAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

授予角色

控制台

在 Google Cloud 控制台中，前往 IAM 页面。
前往 IAM
选择相应项目。
点击 授予访问权限。
在新的主账号字段中，输入您的用户标识符。这通常是用于部署 Cloud Run 服务的邮箱。
在选择角色列表中，选择一个角色。
如需授予其他角色，请点击 添加其他角色，然后依次添加所需角色。
点击保存。

gcloud

如需向您在项目中的账号授予所需的 IAM 角色，请执行以下操作：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=PRINCIPAL \
         --role=ROLE

您需要进行如下替换：

将 PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。
将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。
将 PRINCIPAL 替换为要为其添加绑定的账号。这通常是用于部署 Cloud Run 服务的邮箱。
将 ROLE 替换为要添加到部署者账号的角色。

准备 Cloud Run 部署

本部分介绍了准备将 A2A 代理部署到 Cloud Run 所需的配置（针对 Python 代码示例）。

准备 A2A 代理

通过将示例应用代码库克隆到本地机器来检索代码示例：
```
git clone https://github.com/a2aproject/a2a-samples
```

转到包含示例代码的目录：

cd a2a-samples/samples/python/agents/adk_cloud_run

为 Cloud Run 服务配置 Secret

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

代理需要访问外部服务才能完成任务。Secret是授予该访问权限的安全机制。使用 AlloyDB for PostgreSQL 进行部署时，您需要提供用户名和密码。在 gcloud CLI 中运行以下命令，在 Secret Manager 中创建和管理数据库用户和密码 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"

如需了解详情，请参阅创建 Secret。

用于容器化的 Dockerfile

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

Dockerfile 决定了容器映像的详细信息。以下是您之前克隆的示例 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 为某些热门编程语言提供内置支持，从而简化容器化流程。

Cloud Run 上的 Python 应用：Cloud Run 会查找 main.py 文件来构建和部署 Python 服务。如需了解详情，请参阅在 Cloud Run 上部署 Python 服务快速入门。
Cloud Run 上的 Node.js 应用：Cloud Run 会查找 index.js 文件，以构建和部署 Node.js 服务。请参阅在 Cloud Run 上部署 Node.js 服务快速入门。

将 A2A 智能体部署到 Cloud Run

使用内存中 TaskStore 配置或使用 AlloyDB for PostgreSQL 部署 A2A 应用。

内存中 TaskStore 配置会将其所有数据完全存储在 Cloud Run 容器实例中。这意味着，当容器实例关闭、缩减或重启时，所有任务数据都会丢失。
AlloyDB for PostgreSQL 提供数据持久性，使代理能够横向扩缩，并确保任务在容器重启、扩缩事件和部署后仍能继续运行。

内存中的 TaskStore 配置适合在本地环境中开发 A2A 代理，而 AlloyDB for PostgreSQL 适合在生产环境中扩缩 A2A 代理。

以下命令展示了如何为 Cloud Run 服务使用基于 IAM 的身份验证。建议在部署时使用 --no-allow-unauthenticated 标志来为内部 Google Cloud 客户端（例如 Gemini Enterprise）配置身份验证。

如果您的 A2A 服务器设计为可公开访问，并且需要处理代理级身份验证，您可以在部署期间指定 --allow-unauthenticated 标志。如需了解详情，请参阅 Cloud Run 公开访问身份验证。如需允许公开访问 Cloud Run 服务，您还必须使用 securitySchemes 和 security 参数在 A2A 代理的卡片中提供关键的身份验证信息。如需了解详情，请参阅 A2A 规范：SecurityScheme 对象详细信息。

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

如需使用内存中 TaskStore 配置部署 A2A 代理，请在包含 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"

替换以下内容：

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

使用 AlloyDB for PostgreSQL 进行部署

如需持久保留 A2A 任务，请使用 AlloyDB for PostgreSQL。如需使用 AlloyDB for PostgreSQL 部署 A2A 代理以实现持久性任务存储，请使用以下命令：

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"

替换以下内容：

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

调试部署失败问题

如果您遇到错误或 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"
```

了解 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

测试和监控 A2A 代理部署

成功将 A2A 代理部署到 Cloud Run 后，请全面测试其功能。建立完善的监控实践，以确保持续的性能和可靠性。

A2A 检查器：验证代理合规性

使用 a2a-inspector 工具检查、调试和验证已部署的 Google A2A 代理。此工具可确保您的代理完全符合 A2A 规范并正常运行。

成功连接后，检查器会执行以下操作：

显示代理卡片：自动显示代理的卡片。
验证合规性：检查卡片是否符合 A2A 规范。
启用实时聊天：让您可以通过代理发送和接收消息。
显示原始数据：在控制台中显示原始 JSON-RPC 2.0 消息以进行调试。

通过 CLI 与已部署的 A2A 代理进行交互

使用 A2A 示例仓库中的命令行界面 (CLI) 工具与已部署的服务进行交互。此 CLI 支持基于不记名令牌的身份验证。

如果您的服务使用基于 IAM 的身份验证，请导出 gcloud 令牌以成功进行交互：

export A2A_CLI_BEARER_TOKEN=$(gcloud auth print-identity-token)
# From CLI directory
uv run . --agent CLOUD_RUN_SERVICE_URL

将 CLOUD_RUN_SERVICE_URL 替换为已部署的 Cloud Run 服务的网址。

注意：成功部署并调用后，系统会显示代理卡片，启动新任务并提示您输入内容。CLI 中的每个事件都包含任务 ID、状态和时间戳等详细信息。

对已部署的 A2A 服务进行本地测试

您可以在本地测试已部署的 Cloud Run 服务。在实现基于 IAM 的身份验证时，此操作特别有用。

测试基于 IAM 的 Cloud Run 代理身份验证

与受 Identity and Access Management (IAM) 保护的 Cloud Run 服务进行交互的客户端必须拥有 roles/run.invoker IAM 角色。

使用 gcloud auth print-identity-token 命令在本地测试已部署服务的身份验证流程：

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" CLOUD_RUN_SERVICE_URL/.well-known/agent.json

将 CLOUD_RUN_SERVICE_URL 替换为已部署的 Cloud Run 服务的网址。

将 A2A 智能体部署到 Cloud Run 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

查看 A2A 规范和示例代理

准备工作

向服务账号授予角色

所需的角色

授予角色

控制台

gcloud

准备 Cloud Run 部署

准备 A2A 代理

为 Cloud Run 服务配置 Secret

用于容器化的 Dockerfile

无需 Dockerfile 即可从源代码部署

将 A2A 智能体部署到 Cloud Run

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

使用 AlloyDB for PostgreSQL 进行部署

调试部署失败问题

了解 Cloud Run 应用网址

测试和监控 A2A 代理部署

A2A 检查器：验证代理合规性

通过 CLI 与已部署的 A2A 代理进行交互

对已部署的 A2A 服务进行本地测试

测试基于 IAM 的 Cloud Run 代理身份验证

将 A2A 智能体部署到 Cloud Run

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