設定環境

使用 Agent Runtime 前，請務必先設定環境。您必須擁有已啟用計費功能的 Google Cloud 專案、具備必要權限、設定 Cloud Storage bucket，並安裝 Agent Platform SDK for Python。請參閱下列主題，確保您已準備好開始使用 Agent Runtime。

如需 Terraform 範例，瞭解如何簡化 Agent Runtime 環境設定和部署作業，請參閱 agent-starter-pack。

使用 Google Cloud設定

您可以建立 Google Cloud 專案，為 Agent Runtime 設定 Google Cloud 。

Google Cloud 專案

每項專案都可用專案編號或專案 ID 來識別。PROJECT_NUMBER 是系統在您建立專案時自動產生，而 PROJECT_ID 則是由您或專案建立者所建立。如何設定專案：

登入 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.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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.

Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

注意： 您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您沒有這項權限，請要求管理員授予您 Service Usage 管理員 (roles/serviceusage.serviceUsageAdmin) 角色。

取得必要角色

如要取得使用 Agent Runtime 所需的權限，請要求管理員授予您專案的 Agent Platform 使用者 (roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

設定代理的身分和權限

設定身分和權限時，您可以選擇下列選項：

• 代理身分 (建議) 在 Agent Runtime 使用代理時，透過 Identity Access Management (IAM) 代理身分，提供安全性和存取權管理功能。代理身分會與各個代理繫結。根據預設，代理具有 Agent Platform 代理預設存取權角色 (roles/aiplatform.agentDefaultAccess)，僅包含基本的專案層級記錄和模型呼叫權限，以及 Agent Platform 代理內容編輯者角色 (roles/aiplatform.agentContextEditor)，限制代理只能存取自己的工作階段、記憶和沙箱。

  注意：這個角色可存取的部分功能可能處於預先發布版階段

• 服務帳戶：部署至 Agent Runtime 的代理會共用服務帳戶。服務帳戶有兩種選項：

  • 預設服務代理：根據預設，代理會使用 AI 平台推論引擎服務代理。這個 Google 代管服務帳戶具備 Gemini Enterprise Agent Platform 推論引擎服務代理角色 (roles/aiplatform.reasoningEngineServiceAgent)，其中包含已部署代理所需的預設權限。
  • 自訂服務帳戶：您可以指定要讓代理使用的服務帳戶。這樣一來，您就能更精細地控管授予代理程式的權限。

代理身分

如要在部署代理前設定 IAM 政策，可以建立代理身分，而不部署代理程式碼。方法是建立 Agent Platform 執行個體，並只指定 identity_type 欄位：

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

使用代理身分建立 Agent Platform 執行個體後，您可以執行下列操作：

1. 視用途需要，向代理身分授予其他角色。

2. 使用 agent_engine.update(...) 新增代理程式碼。

預設服務代理

根據預設，系統會使用 AI 平台推論引擎服務代理。如要查看預設權限的完整清單，請參閱 IAM 說明文件。

如果代理需要預設權限以外的權限，您可以為這個服務代理授予其他角色：

1. 前往「IAM」頁面，勾選「包含 Google 提供的角色授予項目」核取方塊。

   前往「IAM」頁面

2. 找出與 [e-mail] 相符的主體。

3. 依序點選「編輯」和「儲存」按鈕，將必要角色新增至主體。

手動產生預設服務代理

雖然部署 Agent Runtime 時，系統會自動佈建推論引擎服務代理，但有時您可能需要事先手動產生。如要將特定角色授予服務代理，確保部署程序具備必要權限，並避免潛在的部署失敗，這項操作就特別重要。

手動產生推論引擎服務代理的步驟如下：

1. 使用 Google Cloud CLI 產生 推論引擎 服務代理。

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

   注意： Google Cloud CLI 指令的回應可能只會顯示 Vertex AI 服務代理。不過，系統也會建立 推論引擎 服務代理。

2. 前往「IAM」頁面，然後點選「授予存取權」。

   前往「IAM」頁面

3. 在「Add principals」(新增主體) 區段的「New principals」(新增主體) 欄位中，輸入 [e-mail]。

4. 在「指派角色」部分，找出並選取所需角色。

5. 按一下 [Save] 按鈕。

自訂服務帳戶

如要使用自己的服務帳戶，您必須授予該帳戶執行代理程式所需的權限。自訂服務帳戶可能需要 Agent Platform 使用者角色 (roles/aiplatform.user)。

1. 如果沒有服務帳戶，請建立一個。請參閱「建立服務帳戶」。

2. 將 Agent Platform 使用者 (roles/aiplatform.user) 角色授予服務帳戶。

3. 將代理程式程式碼所需的任何其他角色授予服務帳戶。

4. 如要使用這個服務帳戶部署代理，請為自己授予這個自訂服務帳戶的服務帳戶使用者角色 (roles/iam.serviceAccountUser)。

5. 部署代理程式時，請指定自訂服務帳戶的電子郵件地址。詳情請參閱「設定自訂服務帳戶」。

跨專案自訂服務帳戶

如果自訂服務帳戶來自其他專案，您必須在服務帳戶所在的專案和部署代理的專案中，進行額外設定。

1. 停用跨專案服務帳戶使用組織政策：在服務帳戶所在的專案中，確認未強制執行 iam.disableCrossProjectServiceAccountUsage 組織政策。詳情請參閱「停用跨專案服務帳戶使用強制執行」。

2. 將權限授予 Agent Platform 服務代理：在服務帳戶所在的專案中，將服務帳戶權杖建立者 (roles/iam.serviceAccountTokenCreator) 角色授予 Agent Platform 服務代理 ([e-mail])，該代理位於您要部署代理的專案中。

3. 將權限授予自訂服務帳戶：在您要部署代理程式的專案中，將必要角色授予自訂服務帳戶。這通常包括 Agent Platform 使用者角色 (roles/aiplatform.user)，以及代理程式碼所需的任何其他角色。

(選用) 建立 Cloud Storage bucket

是否需要 Cloud Storage bucket，取決於 Agent Platform SDK for Python 是否需要在部署前暫存代理程式程式碼：

• 從來源檔案部署：代理以檔案形式存在。Python 版 Agent Platform SDK 可直接將這些檔案組合並上傳至部署服務，因此不需要 Cloud Storage 暫存 bucket。

• 從代理物件部署：代理存在於記憶體中。Agent Platform SDK for Python 會封裝這個物件，並上傳至 Cloud Storage bucket，做為部署服務的暫存區。

從來源檔案部署

如果從來源檔案部署代理，則不需要 Cloud Storage bucket。

從物件部署

從代理物件部署時，Agent Runtime 會在部署過程中，將已部署代理的構件暫存至 Cloud Storage bucket。請確認通過驗證、可使用 Gemini Enterprise Agent Platform 的主體 (您或服務帳戶)，具備這個 bucket 的 Storage Admin 存取權。這是因為 Agent Platform SDK for Python 會將程式碼寫入這個 bucket。

如果已設定 bucket，可以略過這個步驟。否則，請按照標準操作說明建立 bucket。

注意： 強烈建議您在部署代理至 Agent Runtime 的專案中，建立 Cloud Storage bucket。如果使用其他專案中的 bucket，則須手動將 Cloud Storage bucket 的讀取權限授予 Agent Platform 服務代理 ([e-mail])。

請管理員授予您專案的儲存空間管理員 (roles/storage.admin) IAM 角色。

Google Cloud 控制台

1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

   前往「Buckets」(值區) 頁面

2. 點選 「Create」(建立)。
3. 在「Create a bucket」(建立 bucket) 頁面中，輸入 bucket 資訊。如要前往下一個步驟，請按一下「Continue」(繼續)。
   1. 在「Get started」(開始使用) 部分，執行下列操作：
      • 輸入符合 bucket 命名規定的全域不重複名稱。
      • 如要新增值區標籤，請展開「Labels」(標籤) 專區 ()，然後按一下「Add label」(新增標籤) ，並為標籤指定key和value。
   2. 在「Choose where to store your data」(選擇資料的儲存位置) 專區中，執行下列操作：
      1. 選取「位置類型」。
      2. 從「Location type」(位置類型) 下拉式選單中，選擇 bucket 資料的永久儲存位置。
         • 如果選取「雙區域」位置類型，也可以勾選相關核取方塊，啟用強化型複製功能。
      3. 如要設定跨 bucket 複製，請選取「新增透過 Storage 移轉服務執行的跨 bucket 複製作業」，然後按照下列步驟操作：

         設定跨 bucket 複製作業

         1. 在「Bucket」選單中選取 bucket。

         2. 在「Replication settings」(複製設定) 專區中，按一下「Configure」(設定)，即可調整複製工作的設定。

            「Configure cross-bucket replication」(設定跨 bucket 複製作業) 窗格隨即顯示。

            • 如要依物件名稱前置字串篩選要複製的物件，請輸入要納入或排除物件的前置字串，然後按一下「 新增前置字串」。
            • 如要為複製的物件設定儲存空間級別，請從「Storage class」(儲存空間級別) 選單中選取儲存空間級別。如果略過這個步驟，複製的物件預設會使用目的地 bucket 的儲存空間級別。
            • 按一下「完成」。
   3. 在「Choose how to store your data」(選擇資料儲存方式) 部分，執行下列操作：
      1. 選取 bucket 的預設儲存空間級別，或選取 Autoclass，讓系統自動管理 bucket 資料的儲存空間級別。
      2. 如要啟用階層命名空間，請在「Optimize storage for data-intensive workloads」(為資料密集型工作負載提供最理想的儲存空間) 區段中，選取「Enable hierarchical namespace on this bucket」(為這個 bucket 啟用階層命名空間)。
         注意：您無法在現有 bucket 啟用階層命名空間。
   4. 在「Choose how to control access to objects」(選取如何控制物件的存取權) 專區中，選取 bucket 是否強制執行公開存取權防護，並選取 bucket 物件的存取控管方法。
      注意：如果組織政策強制執行「禁止公開存取」設定，您就無法變更該設定。
   5. 在「Choose how to protect object data」(選擇保護物件資料的方式) 專區中，執行下列操作：
      • 在「資料保護」下方，選取要為 bucket 設定的選項。
        • 如要啟用虛刪除功能，請勾選「Soft delete policy (For data recovery)」(虛刪除政策 (用於資料復原)) 核取方塊，並指定物件刪除後要保留的天數。
        • 如要設定物件版本管理，請勾選「Object versioning (For version control)」(物件版本管理 (用於版本管控)) 核取方塊，並指定每個物件的版本數量上限，以及非現行版本的有效天數。
        • 如要啟用物件和 bucket 的資料保留政策，請勾選「資料保留 (法規遵循)」核取方塊，然後執行下列操作：
          • 如要啟用物件保留鎖定功能，請勾選「Enable object retention」(啟用物件保留功能) 核取方塊。
          • 如要啟用值區鎖定功能，請勾選「Set bucket retention policy」(設定值區資料保留政策) 核取方塊，然後選擇保留期限的時間單位和長度。
      • 如要選擇物件資料的加密方式，請展開「Data encryption」(資料加密) 專區 ()，然後選取「Data encryption method」(資料加密方法)。
4. 點選「建立」。

指令列

建立 Cloud Storage bucket，並按照下列方式設定：
• 將 STORAGE_CLASS 替換成您偏好的儲存空間級別。
• 將 LOCATION 替換成您偏好的位置 (ASIA、EU 或 US)
• 將 BUCKET_NAME 替換為符合 bucket 名稱規定的 bucket 名稱。

gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

安裝並初始化 Agent Platform SDK for Python

本節假設您已設定 Python 開發環境，或使用 Colab (或任何其他已為您設定的合適執行階段)。

(選用) 設定虛擬環境

我們也建議設定虛擬環境，以便隔離依附元件。

安裝

為了盡量減少您必須安裝的依附元件，我們將依附元件分為：

• agent_engines：部署至 Agent Runtime 所需的套件組合。
• adk：一組相容的 Agent Development Kit (ADK) 套件。
• langchain：相容的 LangChain 和 LangGraph 套件組合。
• ag2：一組相容的 AG2 套件。
• llama_index：一組相容的 LlamaIndex 套件。

安裝 Agent Platform SDK for Python 時，您可以指定所需的依附元件 (以半形逗號分隔)。如要安裝所有套件，請執行下列指令：

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

如要在 Agent Platform 上使用 Agent2Agent (A2A)，您也必須安裝 a2a-sdk 套件：

pip install google-adk[a2a]

驗證

Colab

請執行下列程式碼：

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

無須採取任何行動。

本機殼層

執行下列指令：

gcloud auth application-default login

匯入及初始化 SDK

執行下列程式碼，匯入並初始化 Agent Runtime 的 SDK：

Google Cloud 專案

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

其中

• PROJECT_ID 是您開發和部署代理的 Google Cloud 專案 ID，
• LOCATION 是支援的地區。

(選用) 自備容器 (BYOC)

如要查看自備容器 (BYOC) 範例，請在下列任一環境中執行「Deploy your containerized agent on Agent Runtime」筆記本：

在 Colab 中開啟 | 在 Colab Enterprise 中開啟 | 在 Agent Platform Workbench 中開啟 | 在 GitHub 中查看

根據預設，Agent Runtime 會在部署過程中為您建構容器。如要建構部署作業專用的自訂容器，請按照本節的指示操作。

如要使用自訂容器部署代理程式，請完成下列高階工作：

1. 建構容器映像檔並推送至 Artifact Registry。
2. 設定代理程式的身分和權限。
3. 將 Artifact Registry 讀取者角色授予 Agent Runtime 預設服務代理。

重要事項： 如要透過 Agent Gateway 轉送 BYOC 代理的流量，請務必設定自訂容器映像檔，信任閘道的根憑證授權單位 (CA)。如需操作說明，請參閱「設定 Agent Gateway 的自訂容器 (BYOC) 代理」。

建構及推送容器映像檔

如要建構及推送容器映像檔，請按照「使用 Cloud Build 建構及推送 Docker 映像檔」中的操作說明操作。

設定 Agent Runtime 的身分和權限

必須有 Agent Runtime 預設服務代理，才能從 Artifact Registry 存放區匯入容器。

根據預設，系統會在專案中自動產生服務代理。如果不存在，請按照「設定代理的身分和權限」一節的操作說明建立及設定。

授予 Artifact Registry 讀取者角色

將 Artifact Registry 讀取者角色 (roles/artifactregistry.reader) 授予預設服務代理 ([e-mail])。

執行下列指令，將必要角色授予預設服務代理：

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:[e-mail]" \
  --role="roles/artifactregistry.reader"

(選用) 授予跨專案權限

如果容器映像檔儲存在 Artifact Registry 存放區，且該存放區與代理部署位置位於不同 Google Cloud 專案，則需要跨專案權限。

在這種情況下，請將 Artifact Registry 讀取者角色授予 Artifact Registry 存放區專案中的 Agent Platform 服務代理 ([e-mail])。

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:[e-mail]" \
  --role="roles/artifactregistry.reader"

後續步驟

總覽

建立代理

瞭解如何使用 Agent Platform 執行階段建立代理。

疑難排解

疑難排解代理建立問題

瞭解如何解決建立自訂代理時的常見錯誤。

資源

取得支援

尋找 Google Agent Platform 的資源和支援。