設定環境

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

如需簡化 Agent Runtime 環境設定和部署作業的 Terraform 參考範例，請考慮探索 agent-starter-pack。

使用 Google Cloud設定

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

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.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

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.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

取得必要角色

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

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

為代理設定身分和權限

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

代理程式身分 (建議) 使用 Identity Access Management (IAM) 代理程式身分，在 Agent Runtime Runtime 上使用代理程式時，提供安全性和存取權管理功能。代理身分與每個代理程式相關聯。根據預設，代理會具備「Agent Platform Agent Default Access」(Agent Platform 代理預設存取權) 角色 (roles/aiplatform.agentDefaultAccess)，該角色僅包含基本專案層級的記錄和模型呼叫權限，以及「Agent Platform Agent Context Editor」(Agent Platform 代理環境編輯者) 角色 (roles/aiplatform.agentContextEditor)，該角色會限制代理只能存取自己的工作階段、記憶體和沙箱。

注意：這個角色可存取的部分功能可能處於預先發布版階段
服務帳戶：服務帳戶會與您部署至 Agent Runtime 的代理程式共用。服務帳戶有兩種選項：
- 預設服務代理：根據預設，代理程式會使用 AI Platform Reasoning Engine 服務代理。這個 Google 管理的服務帳戶具有「Gemini Enterprise Agent Platform Reasoning Engine Service Agent」角色 (roles/aiplatform.reasoningEngineServiceAgent)，其中包含已部署代理所需的預設權限。
- 自訂服務帳戶：您可以指定代理程式使用的服務帳戶。這樣一來，您就能更精細地控管授予代理商的權限。

代理身分

如要在部署代理程式前設定 IAM 政策，可以建立代理程式身分，不必部署代理程式碼。如要這麼做，請建立只有 identity_type 欄位的 Agent Platform 執行個體：

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

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

視用途需要，授予代理程式身分其他角色。
使用 agent_engine.update(...) 新增代理程式碼。

預設服務代理

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

如果代理程式需要的權限超出預設權限集，您可以授予這項服務代理其他角色：

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

前往「IAM」頁面
找出與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符的主體。
按一下編輯按鈕，然後按一下儲存按鈕，將必要角色新增至主體。

手動產生預設服務代理

在部署 Agent Runtime 時，系統會自動佈建 Reasoning Engine Service Agent，但有時您可能需要事先手動產生該 Agent。如果您需要授予服務代理人特定角色，確保部署程序具備必要權限並避免潛在部署失敗，這點就特別重要。

如要手動產生 Reasoning Engine 服務代理，請按照下列步驟操作：

使用 Google Cloud CLI 產生 Reasoning Engine 服務代理程式。
```
gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER
```
注意： Google Cloud CLI 指令的回應可能只會顯示 Vertex AI 服務代理程式。不過，系統也會建立 Reasoning Engine 服務代理。
前往「IAM」頁面，然後按一下「授予存取權」。

前往「IAM」頁面
在「新增主體」部分的「New principals」(新增主體) 欄位中輸入 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com。
在「指派角色」部分，找出並選取所需角色。
按一下 [Save] 按鈕。

自訂服務帳戶

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

如果沒有服務帳戶，請建立一個。請參閱「建立服務帳戶」。
將「Agent Platform User」(代理程式平台使用者) (roles/aiplatform.user) 角色授予服務帳戶。
將代理程式碼所需的任何其他角色授予服務帳戶。
如要使用這個服務帳戶部署代理程式，請授予您這個自訂服務帳戶的「服務帳戶使用者」角色 (roles/iam.serviceAccountUser)。
部署代理程式時，請指定自訂服務帳戶的電子郵件地址。詳情請參閱「設定自訂服務帳戶」。

跨專案自訂服務帳戶

如果自訂服務帳戶來自其他專案，您需要在服務帳戶所在的專案，以及部署代理程式的專案中，進行額外設定。

停用跨專案服務帳戶使用組織政策：在服務帳戶所在的專案中，請確保iam.disableCrossProjectServiceAccountUsage組織政策未強制執行。詳情請參閱「停用跨專案服務帳戶使用強制執行」。
授予 Agent Platform 服務代理程式權限：在服務帳戶所在的專案中，將「服務帳戶權杖建立者」(roles/iam.serviceAccountTokenCreator) 角色授予您打算部署代理程式的專案 Agent Platform 服務代理程式 (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)。
授予自訂服務帳戶權限：在您打算部署代理程式的專案中，將必要角色授予自訂服務帳戶。這通常包括「Agent Platform 使用者」角色 (roles/aiplatform.user) 和代理程式碼所需的任何其他角色。

(選用) 建立 Cloud Storage bucket

是否需要 Cloud Storage 值區，取決於 Agent Platform SDK for Python 是否需要暫存代理程式碼，才能進行部署：

從來源檔案部署：代理程式以檔案形式存在。Python 適用的 Agent Platform SDK 可直接將這些檔案打包並上傳至部署服務，因此不需要 Cloud Storage 暫存值區。
從代理物件部署：代理存在於記憶體中。Python 適用的 Agent Platform SDK 會封裝這個物件，並上傳至 Cloud Storage bucket，做為部署服務的暫存區。

從來源檔案部署

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

從物件部署

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

如果已設定好儲存空間，可以略過這個步驟。否則，請按照建立值區的標準操作說明進行。

請要求管理員授予您專案的「Storage 管理員」(roles/storage.admin) IAM 角色。

Google Cloud 控制台

前往 Google Cloud 控制台的 Cloud Storage「Buckets」(值區) 頁面。
前往「Buckets」(值區) 頁面
按一下「建立」。
在「建立 bucket」頁面中，輸入 bucket 資訊。如要前往下一個步驟，請按「繼續」。
1. 在「開始使用」部分，執行下列操作：
  - 輸入符合值區命名規定的全域不重複名稱。
  - 如要新增值區標籤，請展開「標籤」部分 ()，按一下「新增標籤」，然後為標籤指定 key 和 value。
2. 在「Choose where to store your data」(選擇資料的儲存位置) 專區中，執行下列操作：
  1. 選取「位置類型」。
  2. 從「位置類型」下拉式選單中，選擇要永久儲存 bucket 資料的位置。
    - 如果您選取「雙區域」位置類型，也可以使用相關核取方塊啟用強化型複製功能。
  3. 如要設定跨值區複製，請選取「透過 Storage 移轉服務新增跨值區複製作業」，然後按照下列步驟操作：
    設定跨 bucket 複製作業
    
    在「Bucket」選單中選取 bucket。
    
    在「複製設定」部分，按一下「設定」，設定複製作業的設定。
    
    系統隨即會顯示「設定跨 bucket 複製作業」窗格。
    
    如要依物件名稱前置字串篩選要複製的物件，請輸入要納入或排除物件的前置字串，然後按一下「新增前置字串」。
    
    如要為複製的物件設定儲存空間級別，請從「儲存空間級別」選單中選取儲存空間級別。如果略過這個步驟，複製的物件預設會使用目標值區的儲存空間級別。
    
    按一下 [完成]。
3. 在「選擇資料儲存方式」部分，執行下列操作：
  1. 選取 bucket 的預設儲存空間級別，或選取「Autoclass」，讓系統自動管理 bucket 資料的儲存空間級別。
  2. 如要啟用階層命名空間，請在「為資料密集型工作負載提供最理想的儲存空間」部分，選取「為這個值區啟用階層命名空間」。
    注意：您無法在現有 bucket 中啟用階層式命名空間。
4. 在「選取如何控制物件的存取權」部分，選取 bucket 是否要強制執行禁止公開存取，並為 bucket 的物件選取存取控管方法。
  注意：如果機構政策強制執行「禁止公開存取」設定，您就無法變更這項設定。
5. 在「選擇保護物件資料的方式」部分，執行下列操作：
  - 在「資料保護」下方，選取要為 bucket 設定的選項。
    - 如要啟用虛刪除，請按一下「虛刪除政策 (用於資料復原)」核取方塊，並指定要保留物件的天數 (刪除後)。
    - 如要設定「物件版本管理」，請按一下「物件版本管理 (用於版本管控)」核取方塊，並指定每個物件的版本數量上限，以及非現行版本失效的天數。
    - 如要為物件和 bucket 啟用資料保留政策，請勾選「保留 (符合法規)」核取方塊，然後執行下列操作：
      - 如要啟用 Object Retention Lock，請按一下「啟用物件保留功能」核取方塊。
      - 如要啟用 Bucket Lock，請勾選「Set bucket retention policy」(設定值區資料保留政策) 核取方塊，然後選擇保留期限的時間單位和長度。
  - 如要選擇物件資料的加密方式，請展開「資料加密」部分 ()，然後選取「資料加密」方法。
點選「建立」。

指令列

將 STORAGE_CLASS 替換成您偏好的儲存空間級別。
將 LOCATION 替換成您偏好的位置 (ASIA、EU 或 US)
將 BUCKET_NAME 替換成符合值區命名規定的值區名稱。

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

安裝並初始化 Python 專用的 Agent Platform SDK

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

(選用) 設定虛擬環境

此外，也建議您設定虛擬環境，隔離依附元件。

安裝

為盡量減少必須安裝的依附元件集，我們已將依附元件分成以下幾類：

agent_engines：部署至 Agent Runtime 時所需的一組套件。
adk：相容的 Agent Development Kit 套件組合。
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 a2a-sdk>=0.3.4

驗證

Colab

請執行下列程式碼：

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

您無需採取任何動作。

本機殼層

執行下列指令：

gcloud auth application-default login

匯入並初始化 SDK

執行下列程式碼，匯入及初始化 Agent 執行階段的 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)

Agent Runtime 會在部署程序中為您建構容器。如果您打算自行建構用於部署的容器，請按照下列小節的說明操作。大致來說，這項程序包含下列步驟：

建構容器映像檔並推送至 Artifact Registry。
為 Agent Runtime 設定服務帳戶，對應至使用者專案 (請參閱「為代理程式設定身分和權限」) 和租戶專案 (執行階段所屬專案)。
將 roles/artifactregistry.reader 角色授予使用者專案服務帳戶和租戶專案服務帳戶。

建構及推送容器映像檔

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

設定 Agent Runtime 的服務帳戶

如要設定服務帳戶，請部署會列印租戶服務帳戶的代理程式。

首先，請設定代理程式的原始碼：

開啟終端機視窗
建立名為 byoc_setup 的新目錄
```
mkdir byoc_setup
```

在 byoc_setup 目錄中建立名為 metadata_agent.py 的檔案，並加入以下內容：

class MetadataAgent:

  def query(self):
    import requests
    url = "http://metadata.google.internal/computeMetadata/v1/project/numeric-project-id"
    try:
        response = requests.get(url, headers={"Metadata-Flavor": "Google"})
        response.raise_for_status()
        return f"service-{response.text}@serverless-robot-prod.iam.gserviceaccount.com"
    except Exception:
        return None

root_agent = MetadataAgent()

在 byoc_setup 目錄中建立另一個名為 requirements.txt 的檔案，並加入以下內容：
```
google-cloud-aiplatform[agent_engines]
```

如果尚未安裝，請安裝並初始化 Agent Platform SDK for Python。在初始化 Agent Platform SDK for Python 的相同 Python 工作階段中，執行下列程式碼來列印 TENANT_SERVICE_ACCOUNT：

remote_agent = client.agent_engines.create( # This deploys the agent
    config={
        "source_packages": ["byoc_setup"],
        "entrypoint_module": "byoc_setup.metadata_agent",
        "entrypoint_object": "root_agent",
        "requirements_file": "byoc_setup/requirements.txt",
        "class_methods": [{'api_mode': '', 'name': 'query'}],
    },
)
# This prints the tenant service account
# service-{tenant_project_number}@serverless-robot-prod.iam.gserviceaccount.com
print(remote_agent.query())
# This cleans up the resources
remote_agent.delete(force=True)

在「為代理設定身分和權限」中查閱 USER_SERVICE_ACCOUNT。如果您使用預設服務代理程式，這項值應與 service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com 相符。

授予 Artifact Registry 讀取者角色

執行下列指令，授予必要角色：

gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:USER_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"
gcloud projects add-iam-policy-binding <var>PROJECT_NUMBER</var> \
  --member="serviceAccount:TENANT_SERVICE_ACCOUNT" \
  --role="roles/artifactregistry.reader"

後續步驟

總覽

設定環境

使用 Google Cloud設定

Google Cloud 專案

取得必要角色

為代理設定身分和權限

代理身分

預設服務代理

手動產生預設服務代理

自訂服務帳戶

跨專案自訂服務帳戶

(選用) 建立 Cloud Storage bucket

從來源檔案部署

從物件部署

Google Cloud 控制台

設定跨 bucket 複製作業

指令列

安裝並初始化 Python 專用的 Agent Platform SDK

(選用) 設定虛擬環境

安裝

驗證

Colab

Cloud Shell

本機殼層

匯入並初始化 SDK

Google Cloud 專案

(選用) 自備容器 (BYOC)

建構及推送容器映像檔

設定 Agent Runtime 的服務帳戶

授予 Artifact Registry 讀取者角色

後續步驟

建立代理

排解建立代理程式的問題

取得支援

設定環境 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用 Google Cloud設定

Google Cloud 專案

取得必要角色

為代理設定身分和權限

代理身分

預設服務代理

手動產生預設服務代理

自訂服務帳戶

跨專案自訂服務帳戶

(選用) 建立 Cloud Storage bucket

從來源檔案部署

從物件部署

Google Cloud 控制台

設定跨 bucket 複製作業

指令列

安裝並初始化 Python 專用的 Agent Platform SDK

(選用) 設定虛擬環境

安裝

驗證

Colab

Cloud Shell

本機殼層

匯入並初始化 SDK

Google Cloud 專案

(選用) 自備容器 (BYOC)

建構及推送容器映像檔

設定 Agent Runtime 的服務帳戶

授予 Artifact Registry 讀取者角色

後續步驟

建立代理

排解建立代理程式的問題

取得支援

設定環境