为 Cloud Run 配置 Agent Platform 功能

Gemini Enterprise Agent Platform 提供内置功能，用于构建、部署和管理 AI 智能体、Model Context Protocol (MCP) 服务器和工具。这样，您就可以利用系统管理的身份和自动注册功能，简化智能体工作负载的发现和安全管理。

  • 代理身份会为您的 Cloud Run 工作负载分配一个唯一的加密身份，以便其可以连接到其他代理、工具和 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. Install the Google Cloud CLI.

  4. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

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

    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. 查看 Cloud Run 价格页面，了解 CPU、内存和网络出站流量的价格。预配磁盘的整个大小以及使用该磁盘的实例的生命周期都会影响您的费用。

所需的角色

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

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

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

使用场景

在以下场景中，将智能体平台功能与 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. 查看执行详情。

Identity 字段会显示分配的代理身份。

gcloud

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

gcloud beta run jobs executions describe EXECUTION_NAME

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

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

在 Agent Registry 中查看代理或 MCP

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

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

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

后续步骤