為 Cloud Run 設定 Agent Platform 功能

Gemini Enterprise Agent Platform 提供 Agent Identity 和 Agent Registry 等功能，內建建構、部署及管理 AI 代理、Model Context Protocol (MCP) 伺服器和工具的功能。為 Cloud Run 資源啟用這些功能後，您就能運用系統管理的身分和自動註冊功能，簡化代理程式工作負載的探索和安全防護作業。

本指南說明如何：

Cloud Run 支援下列 Agent Platform 功能：

  • 代理身分：為工作負載指派可透過加密技術驗證的專屬身分，以便安全連線至其他代理、工具和 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 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  7. 確認您已在專案或機構中設定 Agent Registry。
  8. 安裝並初始化 gcloud CLI。
  9. 更新元件：
    gcloud components update
  10. 如要瞭解 CPU、記憶體和網路輸出定價，請參閱 Cloud Run 定價頁面。您需要支付的費用取決於佈建的磁碟大小，以及使用該磁碟的執行個體生命週期。

必要的角色

如要取得設定 Agent Platform 功能所需的權限，請要求管理員授予您專案的下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

用途

在下列情況下，可搭配 Cloud Run 使用 Agent Platform 功能：

  • 使用與生命週期相關聯的專屬系統管理身分，向其他代理程式、工具和 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. 按一下 [Security] (安全性) 分頁標籤。

「身分」欄位會顯示指派的代理程式身分。

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」。

後續步驟