部署代理

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

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

您也可以使用代理程式 Starter Pack 範本進行部署。

事前準備

部署服務機器人前，請確認您已完成下列工作：

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)。

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

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

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

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

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

如要指定環境變數，您可以使用以下幾種方法：

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"
#

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": "SECRET_ID", "version": "SECRET_VERSION_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)

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"],
#   }

定義 Cloud Storage 資料夾

如果階段構件對應至 Cloud Storage 值區中現有的資料夾，就會遭到覆寫。如有需要，您可以指定要用於暫存構件的 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 參考資料。

建立 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.
)

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

1. 本機會產生下列成果的套件：

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

2. 套件會上傳至 Cloud Storage (位於對應的資料夾下)，以便布建建構成果。

3. PackageSpec 會指定相應構件的 Cloud Storage URI。

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

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

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

如果已部署的服務代理需要授予其他權限，請按照「設定服務代理權限」中的指示操作。

如果您將密鑰定義為環境變數，就必須授予下列權限：

• Secret Manager 密鑰存取服務 (roles/secretmanager.secretAccessor)

取得代理程式資源 ID

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

remote_agent.resource_name

回應應類似下列字串：

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

其中

• PROJECT_ID 是部署代理程式執行所在的 Google Cloud 專案 ID。

• LOCATION 是部署的服務專員執行的區域。

• RESOURCE_ID 是部署的代理程式 ID，做為 reasoningEngine 資源。

後續步驟

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