为 Cloud Run 配置 Agent Platform 功能

Gemini Enterprise Agent Platform 的智能体身份和Agent Registry等功能可提供内置功能，用于构建、部署和管理 AI 智能体、Model Context Protocol (MCP) 服务器和工具。为 Cloud Run 资源启用这些功能后，您可以利用系统管理的身份和自动注册来简化代理工作负载的发现和安全性。

本指南介绍了如何执行以下操作：

Cloud Run 支持以下 Agent 平台功能：

  • 代理身份：为您的工作负载分配唯一的加密可验证身份，从而实现与其他代理、工具和 Google Cloud API 的安全连接。
  • Agent Registry：自动注册您的智能体和工具，以便组织中的其他开发者和智能体可以发现它们。

准备工作

  1. 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

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

  3. 安装 Google Cloud CLI。

  4. 配置 gcloud CLI 以使用您的联合身份。

    如需了解详情，请参阅使用联合身份登录 gcloud CLI。

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

    gcloud init

  6. 启用 Cloud Run Admin API、Identity and Access Management API、Agent Registry API 和 App Hub API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  7. 确保您已在项目或组织中设置 Agent Registry。
  8. 安装并初始化 gcloud CLI。
  9. 更新组件： 
    gcloud components update
  10. 如需了解 CPU、内存和网络出站流量的价格，请查看 Cloud Run 价格页面。预配磁盘的整个大小以及使用该磁盘的实例的生命周期都会影响您的费用。

所需的角色

如需获得配置代理平台功能所需的权限，请让管理员向您授予项目的以下 IAM 角色：

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

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

使用场景

在以下场景中将 Agent Platform 功能与 Cloud Run 搭配使用：

  • 使用与其生命周期相关联的唯一系统管理身份，向其他代理、工具和 Google Cloud API 验证代理的身份。
  • 在组织的 Agent Registry 中自动发现代理和 MCP 服务器。
  • 使用 Identity-Aware Proxy 作为身份验证政策来保护 MCP 服务器。

了解功能类型和身份类型

您可以通过在 Cloud Run 资源上设置功能和身份属性来配置 Agent Platform 功能。

这两个属性用于控制如何注册和识别工作负载：

  • 功能类型：声明工作负载的主要用途。 此属性一经设置便无法更改或取消设置。您可以为工作负载分配以下功能类型之一：
    • agent：将工作负载指定为 AI 智能体。此类工作负载必须使用 agent-identity 类型。
    • mcp-server：将工作负载指定为用户管理的 MCP 服务器。 此类型可以使用任何受支持的身份类型。
  • 身份类型：指定分配给工作负载的身份类型。 此属性一经设置便无法更改或取消设置。您可以为工作负载分配以下任一类型的身份：
    • agent-identity：分配专为代理设计的系统管理的代理身份。当您使用 agent-identity 进行部署时，Agent Platform 默认启用身份证书。如需选择不使用此功能，请使用 --no-identity-certificate 标志更新服务或设置 run.googleapis.com/identity-certificate-enabled: "false" 注解。 请按照指南对工具和资源进行身份验证，以便代理自行或代表最终用户执行操作。如需了解系统管理的代理身份的核心概念和安全优势，请详细了解代理身份。
    • service-account：使用标准的 Google Cloud 服务账号。

配置行为

功能属性和身份属性的行为取决于您选择的组合：

功能类型 身份类型 引发的行为
agent agent-identity 工作负载在 Agent Registry 中注册为代理，并分配有系统管理的代理身份。
agent 其他或未指定 错误。具有 functional-type=agent 的工作负载必须使用 identity-type=agent-identity。
mcp-server agent-identity、service-account 或未指定 工作负载在 Agent Registry 中注册为 MCP 服务器 (/mcpServers)。如果未指定，则默认为服务账号身份。
未指定 service-account 工作负载作为标准 Cloud Run 服务或作业运行。

在服务和作业中配置功能

您可以使用 Google Cloud CLI 在 Cloud Run 服务和作业中配置 Agent Platform 功能。

服务

  • 如需部署代理，请指定 --functional-type=agent 和 --identity-type=agent-identity：

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=agent \
    --identity-type=agent-identity

    替换以下内容：

    • SERVICE_NAME：Cloud Run 服务的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式

  • 如需更新现有服务以使用代理身份，请执行以下操作：

    gcloud beta run services update SERVICE_NAME \
    --functional-type=agent \
    --identity-type=agent-identity \
    --no-traffic

    替换以下内容：

    • SERVICE_NAME：Cloud Run 服务的名称。
    • ORGANIZATION_ID：您的 Google Cloud组织 ID。
    • PROJECT_NUMBER：您的 Google Cloud 项目编号。
    • REGION：服务部署所在的区域。

  • 如需部署用户管理的 MCP 服务器，请指定 --functional-type=mcp-server。您可以选择使用 --identity-type 指定身份类型：

    gcloud beta run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --functional-type=mcp-server \
    --identity-type=IDENTITY_TYPE

    替换以下内容：

    • SERVICE_NAME：Cloud Run 服务的名称。
    • IMAGE_URL：对容器映像的引用，例如 us-docker.pkg.dev/cloudrun/container/hello:latest。如果您使用 Artifact Registry，则必须预先创建制品库 REPO_NAME。网址采用 LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG 格式
    • IDENTITY_TYPE：可选。分配给工作负载的身份类型。指定 agent-identity 或 service-account。默认值为 service-account。

作业

  • 如需创建代理作业，请指定 --functional-type=agent 和 --identity-type=agent-identity：

    gcloud beta run jobs create JOB_NAME \
  --image=IMAGE_URL \
  --functional-type=agent \
  --identity-type=agent-identity

    替换以下内容：

    • JOB_NAME：Cloud Run 作业的名称。
    • IMAGE_URL：对容器映像的引用。

查看已分配的身份

您可以通过 Google Cloud 控制台或 gcloud CLI 查看分配的代理身份。

服务

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run：

    转到 Cloud Run

  2. 从 Cloud Run 导航菜单中选择服务，然后点击您的服务。

  3. 点击修订版本标签页，然后选择一个修订版本。

  4. 点击安全标签。

身份字段会显示分配的客服人员身份。

gcloud

如需查看代理身份，请描述服务的修订版本：

gcloud beta run revisions describe REVISION_NAME

将 REVISION_NAME 替换为服务修订版本的名称。

输出中会显示分配的代理身份。

作业

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run：

    转到 Cloud Run

  2. 从 Cloud Run 导航菜单中选择作业，然后点击您的作业。

  3. 点击执行标签页，然后选择一个执行。

  4. 查看执行详情。

身份字段会显示分配的客服人员身份。

gcloud

如需查看作业执行的代理身份，请描述执行情况：

gcloud beta run jobs executions describe EXECUTION_NAME

将 EXECUTION_NAME 替换为作业执行的名称。

输出中会显示分配的代理身份。

在 Agent Registry 中查看代理或 MCP

当您使用 --functional-type=agent 或 --functional-type=mcp-server 部署 Cloud Run 资源时，该资源会自动注册到您组织的 Agent Registry 中。

  • 代理在代理目录 (/agents) 下注册。
  • MCP 服务器已在 MCP 服务器目录 (/mcpServers) 下注册。

如需查看注册表中已注册的代理和工具，并了解如何安全地存储和发现代理和工具，请探索 Agent Registry。

后续步骤