部署代理

如要在 Vertex AI Agent Engine 部署代理，請按照下列步驟操作：

1. 設定要部署的代理程式。
2. 建立 AgentEngine 執行個體。
3. 授予已部署代理程式權限。
4. 取得代理程式資源 ID。

您也可以使用 Agent Starter Pack 範本進行部署。

注意： Vertex AI Agent Engine 部署作業僅支援 Python。

事前準備

部署代理程式前，請務必完成下列工作：

1. 設定環境。
2. 開發代理程式。

設定要部署的代理程式

您可以進行下列選用設定：

• 套件規定
• 其他套件
• 環境變數
• 建構選項
• Cloud Storage 資料夾
• 資源中繼資料
• 自訂服務帳戶

定義套件需求

提供代理程式部署作業所需的一組套件。這組套件可以是 pip 要安裝的項目清單，也可以是符合需求檔案格式的檔案路徑。請遵循下列最佳做法：

1. 固定套件版本，確保建構可重現。常見的追蹤套件包括：google-cloud-aiplatform、cloudpickle、langchain、langchain-core、langchain-google-vertexai 和 pydantic。

2. 盡可能減少代理程式中的依附元件數量。這樣一來，更新依附元件和代理程式時，重大變更的數量就會減少。

如果代理程式沒有任何依附元件，您可以將 requirements 設為 None：

requirements = None

如果代理程式使用架構專屬範本，開發代理程式時，您應指定匯入的 SDK 版本 (例如 1.77.0)。

ADK

預先發布版

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

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

LangChain

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

AG2

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

LlamaIndex

預先發布版

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

以下操作說明適用於 LlamaIndex 查詢管道：

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

您也可以使用套件 requirements 執行下列操作：

• 為指定套件 (例如 google-cloud-aiplatform) 設定版本上限或固定版本：

  requirements = [
      # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
      "google-cloud-aiplatform[agent_engines,adk]==1.88.0",
  ]
  

• 新增其他套件和限制：

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk]==1.88.0",
      "cloudpickle==3.0", # new
  ]
  

• 指向 GitHub 分支版本或提取要求中的套件版本：

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
      "cloudpickle==3.0",
  ]
  

• 在檔案 (例如 path/to/requirements.txt) 中維護需求清單：

  requirements = "path/to/requirements.txt"
  

  其中 path/to/requirements.txt 是遵循需求檔案格式的文字檔案。例如：

  google-cloud-aiplatform[agent_engines,adk]
  cloudpickle==3.0
  

定義其他套件

您可以加入本機檔案或目錄，其中包含本機所需的 Python 來源檔案。相較於套件需求，這項功能可讓您使用自行開發的私人公用程式，這些公用程式在 PyPI 或 GitHub 上無法取得。

如果代理程式不需要任何額外套件，您可以將 extra_packages 設為 None：

extra_packages = None

你也可以使用 extra_packages 執行下列操作：

• 加入單一檔案 (例如 agents/agent.py)：

  extra_packages = ["agents/agent.py"]
  

• 在整個目錄中加入檔案集 (例如 agents/)：

  extra_packages = ["agents"] # directory that includes agents/agent.py
  

• 指定 Python Wheel 二進位檔 (例如 path/to/python_package.whl)：

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk]",
      "cloudpickle==3.0",
      "python_package.whl",  # install from the whl file that was uploaded
  ]
  extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading
  

定義環境變數

如果代理程式需要使用環境變數，您可以在 env_vars= 引數中指定這些變數。如果代理程式不依附任何環境變數，可以設為 None：

env_vars = None

警告： 請勿設定下列環境變數：GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_QUOTA_PROJECT、GOOGLE_CLOUD_LOCATION、PORT、K_SERVICE、K_REVISION、K_CONFIGURATION 和 GOOGLE_APPLICATION_CREDENTIALS。此外，請避免使用 GOOGLE_CLOUD_AGENT_ENGINE 前置字串，以免與 Vertex AI Agent Engine 環境變數發生命名衝突。

如要指定環境變數，有幾種不同的做法：

字典

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

如要參照 Secret Manager 中的密鑰，並將其做為環境變數 (例如 CLOUD_SQL_CREDENTIALS_SECRET)，請先按照操作說明在專案中為 CLOUD_SQL_CREDENTIALS_SECRET建立密鑰，然後指定環境變數，如下所示：

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": "SECRET_ID", "version": "SECRET_VERSION_ID"},
}

其中

• SECRET_VERSION_ID 是密鑰版本的 ID。
• SECRET_ID 是密鑰的 ID。

注意： 您只能參照與已部署代理程式位於同一專案中管理的密鑰 (及其版本)。

在代理程式碼中，您可以參照密鑰，如下所示：

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON payloads.
  return json.loads(secret)

清單

注意： 這個選項不支援 Secret Manager 整合。如要指定受管理密鑰，請以字典形式指定環境變數。

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

定義建構選項

您可以為代理程式指定建構選項，例如建構代理程式容器映像檔時要執行的安裝指令碼。這項功能可用於安裝系統依附元件 (例如 gcloud cli、npx) 或其他自訂設定。指令碼會以 Root 權限執行。

如要使用安裝指令碼，請建立名為 installation_scripts 的目錄，並將 Shell 指令碼放在該目錄中：

.
├── ...
└── installation_scripts/
    └── install.sh

接著，在 extra_packages 中指定 installation_scripts 目錄，並在 build_options 中指定指令碼路徑：

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

定義 Cloud Storage 資料夾

如果暫存構件對應於 Cloud Storage bucket 中的現有資料夾，則會遭到覆寫。如有需要，您可以指定暫存構件的 Cloud Storage 資料夾。如果您不介意可能覆寫預設資料夾中的檔案，可以將 gcs_dir_name 設為 None：

gcs_dir_name = None

為避免覆寫檔案 (例如用於開發、測試和實際工作等不同環境)，您可以設定對應的資料夾，並指定要將構件暫存到哪個資料夾：

gcs_dir_name = "dev" # or "staging" or "prod"

如要避免發生衝突，可以產生隨機 uuid：

import uuid
gcs_dir_name = str(uuid.uuid4())

設定資源中繼資料

您可以為ReasoningEngine資源設定中繼資料：

display_name = "Currency Exchange Rate Agent (Staging)"

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

如需完整參數集，請參閱 API 參考資料。

設定自訂服務帳戶

您可以將自訂服務帳戶設為已部署代理程式的身分，而非預設身分。

如要這麼做，請在建立或更新 Agent Engine 執行個體時，將自訂服務帳戶的電子郵件地址指定為 service_account，例如：

# Create a new instance
agent_engines.create(
  local_agent=<my-agent>,
  service_account="[e-mail]",
  ...
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
  resource_name,
  service_account="[e-mail]",
  ...
)

注意： 請只指定服務帳戶電子郵件地址，而非完整資源 URI，例如 projects/{project_id}/serviceAccounts/{service_account_email}。

建立 AgentEngine 執行個體

如要在 Vertex AI 上部署代理程式，請使用 agent_engines.create 傳遞 local_agent 物件和任何選用設定：

remote_agent = agent_engines.create(
    local_agent,                     # Optional.
    requirements=requirements,       # Optional.
    extra_packages=extra_packages,   # Optional.
    gcs_dir_name=gcs_dir_name,       # Optional.
    display_name=display_name,       # Optional.
    description=description,         # Optional.
    env_vars=env_vars,               # Optional.
    build_options=build_options,     # Optional.
    service_account=service_account, # Optional.
)

部署作業需要幾分鐘，期間系統會在背景執行下列步驟：

1. 系統會在本地產生下列構件套件：

   • *.pkl 對應於 local_agent 的 Pickle 檔案。
   • requirements.txt：包含套件需求的文字檔。
   • dependencies.tar.gz，其中包含任何額外套件。

2. 套件會上傳至 Cloud Storage (位於對應的資料夾)，用於暫存構件。

3. 各個構件的 Cloud Storage URI 會在 PackageSpec 中指定。

4. Vertex AI Agent Engine 服務會接收要求、建構容器，並在後端啟動 HTTP 伺服器。

部署延遲時間取決於安裝必要套件的總時間。部署完成後，remote_agent 會對應至在 Vertex AI 上執行的 local_agent 執行個體，可供查詢或刪除。與代理程式的本機執行個體不同。

授予已部署的代理程式權限

如果部署的代理程式需要額外權限，請按照「為代理程式設定身分和權限」一文中的操作說明進行。

如果您將密鑰定義為環境變數，則需要授予下列權限：

• Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

取得代理程式資源 ID

每個已部署的代理程式都有專屬 ID。您可以執行下列指令，取得已部署代理程式的 resource_name ID：

remote_agent.resource_name

回應應如下列字串所示：

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

其中

• PROJECT_ID 是已部署代理程式的 Google Cloud 專案 ID。

• LOCATION 是部署的代理程式執行的區域。

• RESOURCE_ID 是已部署代理程式的 ID，以 reasoningEngine 資源形式呈現。

後續步驟

• 使用代理程式。
• 管理已部署的代理程式。
• 排解代理程式部署問題。
• 取得支援。