設定環境

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

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

設定您的 Google Cloud 專案

每項專案都可用專案編號或專案 ID 來識別。PROJECT_NUMBER 是系統在您建立專案時自動產生的，而 PROJECT_ID 則是由您或專案建立者所建立。如要設定專案，請按照下列步驟操作：

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

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 Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

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 Vertex AI, Cloud Storage, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

注意： 如要啟用 API，您需要 serviceusage.services.enable 權限。如果沒有這項權限，請要求管理員授予您服務用量管理員 (roles/serviceusage.serviceUsageAdmin) 角色。

取得必要角色

如要取得使用 Vertex AI Agent Engine 所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

• Vertex AI 使用者 (roles/aiplatform.user)
• 儲存空間管理員 (roles/storage.admin)

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

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

為代理設定身分和權限

在 Vertex AI Agent Engine 上部署的代理程式會使用服務帳戶做為身分執行。

服務帳戶有兩種選項：

• 預設服務代理：根據預設，代理程式會使用 AI Platform Reasoning Engine 服務代理。這個 Google 代管的服務帳戶具有「Vertex AI Reasoning Engine 服務代理人」角色 (roles/aiplatform.reasoningEngineServiceAgent)，其中包含已部署代理程式所需的預設權限。
• 自訂服務帳戶：您可以指定代理程式使用的服務帳戶。這樣一來，您就能更精細地控管授予代理程式的權限。

使用預設服務代理程式

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

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

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

   前往「IAM」頁面

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

3. 按一下編輯按鈕，然後按一下儲存按鈕，將必要角色新增至主體。

手動產生預設服務代理

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

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

1. 使用 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 服務代理。

2. 前往「IAM」頁面，然後按一下「授予存取權」。

   前往「IAM」頁面

3. 在「新增主體」部分的「新增主體」欄位中，輸入 [e-mail]。

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

5. 按一下「儲存」按鈕。

使用自訂服務帳戶

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

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

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

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

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

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

跨專案自訂服務帳戶

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

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

2. 授予 Vertex AI 服務代理程式權限：在服務帳戶所在的專案中，將「服務帳戶憑證建立者」(roles/iam.serviceAccountTokenCreator) 角色授予要部署代理程式的專案 Vertex AI 服務代理程式 ([e-mail])。

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

建立 Cloud Storage 值區

在部署程序中，Vertex AI Agent Engine 會將已部署代理的構件暫存在 Cloud Storage 值區中。請確認經過驗證可使用 Vertex AI 的主體 (您本人或服務帳戶) 具有這個值區的 Storage Admin 存取權。這是因為 Python 適用的 Vertex AI SDK 會將程式碼寫入這個值區。

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

注意： 強烈建議您在將代理程式部署至 Vertex AI Agent Engine 的專案中，建立 Cloud Storage 值區。如果您使用其他專案中的值區，則必須手動將 Cloud Storage 值區的讀取權限授予 Vertex AI 服務代理 ([e-mail])。
1. In the Google Cloud console, go to the Cloud Storage Buckets page.

   Go to Buckets

2. Click Create.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
   1. In the Get started section, do the following:
      • Enter a globally unique name that meets the bucket naming requirements.
      • To add a bucket label, expand the Labels section (), click Add label, and specify a key and a value for your label.
   2. In the Choose where to store your data section, do the following:
      1. Select a Location type.
      2. Choose a location where your bucket's data is permanently stored from the Location type drop-down menu.
         • If you select the dual-region location type, you can also choose to enable turbo replication by using the relevant checkbox.
      3. To set up cross-bucket replication, select Add cross-bucket replication via Storage Transfer Service and follow these steps:

         Set up cross-bucket replication

         1. In the Bucket menu, select a bucket.

         2. In the Replication settings section, click Configure to configure settings for the replication job.

            The Configure cross-bucket replication pane appears.

            • To filter objects to replicate by object name prefix, enter a prefix that you want to include or exclude objects from, then click Add a prefix.
            • To set a storage class for the replicated objects, select a storage class from the Storage class menu. If you skip this step, the replicated objects will use the destination bucket's storage class by default.
            • Click Done.
   3. In the Choose how to store your data section, do the following:
      1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.
      2. To enable hierarchical namespace, in the Optimize storage for data-intensive workloads section, select Enable hierarchical namespace on this bucket.
         Note: You cannot enable hierarchical namespace in existing buckets.
   4. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control method for your bucket's objects.
      Note: You cannot change the Prevent public access setting if this setting is enforced at an organization policy.
   5. In the Choose how to protect object data section, do the following:
      • Select any of the options under Data protection that you want to set for your bucket.
        • To enable soft delete, click the Soft delete policy (For data recovery) checkbox, and specify the number of days you want to retain objects after deletion.
        • To set Object Versioning, click the Object versioning (For version control) checkbox, and specify the maximum number of versions per object and the number of days after which the noncurrent versions expire.
        • To enable the retention policy on objects and buckets, click the Retention (For compliance) checkbox, and then do the following:
          • To enable Object Retention Lock, click the Enable object retention checkbox.
          • To enable Bucket Lock, click the Set bucket retention policy checkbox, and choose a unit of time and a length of time for your retention period.
      • To choose how your object data will be encrypted, expand the Data encryption section (), and select a Data encryption method.
4. Click Create.

安裝並初始化 Vertex AI SDK for Python

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

(選用) 設定虛擬環境

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

安裝

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

• ：部署至 Vertex AI Agent Engine 時所需的一組套件。agent_engines
• adk：相容的 Agent Development Kit 套件組合。
• langchain：相容的 LangChain 和 LangGraph 套件組合。
• ag2：相容的 AG2 套件組合。
• llama_index：相容的 LlamaIndex 套件組合。

安裝 Python 適用的 Vertex AI SDK 時，您可以指定所需依附元件 (以半形逗號分隔)。如要安裝所有擴充功能，請按照下列步驟操作：

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

驗證

Colab

請執行下列程式碼：

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

您無需採取任何動作。

本機殼層

執行下列指令：

gcloud auth application-default login

匯入並初始化 SDK

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

import vertexai
from vertexai import agent_engines

vertexai.init(
    project="PROJECT_ID",
    location="LOCATION",
    staging_bucket="gs://BUCKET_NAME",
)

其中

• PROJECT_ID 是您要 Google Cloud 開發及部署代理程式的專案 ID，
• LOCATION 是支援的區域，且
• BUCKET_NAME 是部署代理程式時，用於暫存構件的 Cloud Storage bucket 名稱。

後續步驟

• 開發代理程式。
• 排解設定環境的問題。
• 取得支援。