為 Cloud Run 設定 Agent Platform 功能

預覽 — 設定 Cloud Run 的 Agent Platform 功能

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

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

本指南說明如何：

• 建立必要的 IAM 角色
• 瞭解功能和身分類型
• 設定服務和工作的各項功能
• 查看指派的身分
• 在 Agent Registry 中查看已註冊的代理和工具

Cloud Run 支援下列 Agent Platform 功能：

• Agent Identity：為工作負載指派專屬且可透過加密驗證的身分，安全連結其他代理、工具和 Google Cloud API。
• 代理儲存庫： 自動註冊代理和工具，方便貴機構的其他開發人員和代理探索。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自體驗產品的實際應用成效。新客戶還能獲得價值 $300 美元的免費抵免額，能用於執行、測試及部署工作負載。

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

gcloud init

1. 啟用 Cloud Run Admin API、Identity and Access Management API、Agent Registry API 和 App Hub API (如有尚未啟用的 API)。

   啟用 API 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

   啟用 API

2. 確認您已在專案或組織中設定 Agent Registry。
3. 安裝並初始化 gcloud CLI。
4. 更新元件：

   gcloud components update

5. 請參閱 Cloud Run 定價頁面，瞭解 CPU、記憶體和網路 egress 的費用。您需要為佈建的磁碟大小和使用該磁碟的執行個體生命週期付費。

必要的角色

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

• 如要部署及管理 Cloud Run 資源： Cloud Run 管理員 (roles/run.admin)
• 如要管理 App Hub 資源，請具備下列其中一項權限：
  • App Hub 管理員 (roles/apphub.admin)
  • Agent Registry API 管理員 (roles/apiregistry.admin)
• 如要使用特定身分部署，請執行下列任一操作：
  • IAM 服務帳戶使用者 (roles/iam.serviceAccountUser)
  • IAM 服務帳戶管理員 (roles/iam.serviceAccountAdmin)

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

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

用途

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

• 使用與生命週期相關聯的系統管理專屬 ID，向其他代理程式、工具和 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" 註解。請按照指南驗證工具和資源，讓代理能以自身權限或代表使用者執行操作。如要瞭解系統管理代理身分的核心概念和安全性優勢，請參閱「Agent Identity」一文。
  • 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

• 如要更新現有服務，改用 Agent Identity，請按照下列步驟操作：

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

  重要事項： 將現有服務從服務帳戶更新為agent-identity時，Cloud Run 會指派新的主體，不會繼承先前服務帳戶的權限。為避免連線中斷，請使用政策分析工具找出必要角色，並在更新前預先指派給主體 principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME，或使用 --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。

工作

注意：只有 Cloud Run 服務可以公開為 MCP 伺服器。Cloud Run 工作無法公開為 MCP 伺服器，且僅支援 agent 函式類型。

• 如要建立代理程式工作，請指定 --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. 按一下「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」。

後續步驟

• 瞭解如何驗證代理程式，以存取 API 和工具。
• 瞭解如何驗證 MCP 伺服器，確保連線安全。
• 瞭解如何在 Cloud Run 託管 MCP 伺服器。
• 使用 Agent Development Kit 建構自訂代理，並在登錄檔中註冊。
• 如要建構及部署符合 A2A 規格的代理，請參閱「將 A2A 代理部署至 Cloud Run」。
• 如果代理程式註冊或身分指派作業發生問題，請參閱疑難排解指南。