為 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 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  7. 確認您已在專案或組織中設定 Agent Registry。
  8. 安裝並初始化 gcloud CLI。
  9. 更新元件：
    gcloud components update
  10. 請參閱 Cloud Run 定價頁面，瞭解 CPU、記憶體和網路輸出的費用。佈建磁碟的完整大小和使用該磁碟的執行個體生命週期，都會影響費用。

必要的角色

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

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

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

用途

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

  • 使用與生命週期連結的系統管理專屬身分，向其他代理、工具和 Google Cloud API 驗證代理。
  • 啟用自動探索功能，在組織的 Agent Registry 中尋找代理和 MCP 伺服器。
  • 使用 Identity-Aware Proxy 做為驗證政策，保護 MCP 伺服器。

瞭解函式和身分類型

如要設定 Agent Platform 功能，請在 Cloud Run 資源上設定功能和身分屬性。

這兩個屬性可控制如何註冊及識別工作負載：

  • 功能類型：宣告工作負載的主要用途。設定後，這項屬性就無法變更或取消設定。您可為工作負載指派下列其中一種功能類型：
    • 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 其他或未指定 Error. 具有 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 導覽選單中選取「Services」(服務)，然後按一下您的服務。

  3. 按一下「修訂版本」分頁標籤，然後選取修訂版本。

  4. 按一下 [Security] (安全性) 分頁標籤。

「Identity」(身分) 欄位會顯示指派的代理身分。

gcloud

如要查看代理程式身分，請說明服務修訂版本：

gcloud beta run revisions describe REVISION_NAME

將 REVISION_NAME 替換為服務修訂版本的名稱。

輸出內容會顯示指派的代理身分。

工作

控制台

  1. 前往 Google Cloud 控制台的「Cloud Run」頁面：

    前往 Cloud Run。

  2. 從 Cloud Run 導覽選單中選取「Jobs」(工作)，然後按一下工作。

  3. 按一下「Executions」(執行作業) 分頁標籤，然後選取執行作業。

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

後續步驟