部署代理

如要在 Vertex AI Agent Engine 部署代理，請選擇下列兩種主要方法：

  • 從虛擬服務專員物件部署：適合在 Colab 等環境中進行互動式開發，可部署記憶體內 local_agent 物件。如果代理程式的結構不含複雜的非可序列化元件，最適合使用這個方法。
  • 從來源檔案部署：這個方法非常適合自動化工作流程，例如 CI/CD 管道和基礎架構即程式碼工具 (如 Terraform)，可實現完全宣告式和自動化部署。這項工具會直接從本機原始碼部署代理程式，不需要 Cloud Storage bucket。

如要開始使用，請按照下列步驟操作：

  1. 完成必要條件。
  2. (選用) 設定要部署的代理程式。
  3. 建立 AgentEngine 執行個體。
  4. (選用) 取得代理程式資源 ID。
  5. (選用) 列出支援的作業。
  6. (選用) 授予已部署的代理程式權限。

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

必要條件

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

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

(選用) 設定要部署的代理程式

您可以為代理程式設定下列選用項目：

建立 AgentEngine 執行個體

本節說明如何建立 AgentEngine 執行個體來部署代理程式。

如要在 Vertex AI Agent Engine 部署代理，可以選擇下列方法：

  • 從代理物件部署，進行互動式開發。

  • 從來源檔案部署，以自動執行檔案工作流程。

從代理程式物件

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

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

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

  1. 系統會在本機產生一組構件，當中含有：

    • *.pkl 對應 local_agent 的 pickle 檔案。
    • requirements.txt：包含套件需求的文字檔。
    • dependencies.tar.gz 包含額外套件的 tar 檔案。

  2. 為了暫存構件，這個檔案包會上傳至 Cloud Storage (位於對應的資料夾)。

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

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

部署延遲時間取決於安裝必要套件的總時間。部署完成後，remote_agent 會對應至在 Vertex AI 上執行的 local_agent 執行個體，且可查詢或刪除。

remote_agent 物件對應於 AgentEngine 類別，其中包含下列屬性：

從來源檔案

如要從 Vertex AI 上的來源檔案部署，請使用 client.agent_engines.create，並在設定字典中提供 source_packages、entrypoint_module、entrypoint_object 和 class_methods，以及其他選用設定。使用這種方法時，您不需要傳遞代理程式物件或 Cloud Storage bucket。

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

內嵌來源部署作業的參數如下：

  • source_packages (必要，list[str])：要納入部署作業的本機檔案或目錄路徑清單。source_packages 中的檔案和目錄總大小不得超過 8 MB。
  • entrypoint_module (必填，str)：包含代理程式進入點的完整 Python 模組名稱 (例如 agent_dir.agent)。
  • entrypoint_object (必要，str)：entrypoint_module 中可呼叫物件的名稱，代表代理程式應用程式 (例如 root_agent)。

  • class_methods (必要，list[dict])：定義代理程式公開方法的字典清單。每個字典都包含 name (必填)、api_mode (必填) 和 parameters 欄位。如要進一步瞭解自訂代理程式的方法，請參閱「列出支援的作業」。

    例如：

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file (選用，str)：source_packages 中指定路徑內的 pip 需求檔案路徑。預設值為封裝來源根目錄中的 requirements.txt。

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

  1. Vertex AI SDK 會建立 tar.gz 封存檔，其中包含 source_packages 中指定的路徑。
  2. 這個封存檔會經過編碼，並直接傳送至 Vertex AI API。
  3. Vertex AI Agent Engine 服務會接收封存檔、解壓縮、從 requirements_file 安裝依附元件 (如有提供)，並使用指定的 entrypoint_module 和 entrypoint_object 啟動代理應用程式。

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

remote_agent 物件對應於 AgentEngine 類別，其中包含下列屬性：

以下是從來源檔案部署代理程式的範例：

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

(選用) 取得服務專員資源 ID

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

remote_agent.api_resource.name

回應應如下列字串所示：

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

其中

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

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

  • RESOURCE_ID 是已部署代理程式的 ID，屬於 reasoningEngine 資源。

(選用) 列出支援的作業

每個已部署的代理程式都有支援的作業清單。您可以執行下列指令，取得已部署代理程式支援的作業清單：

remote_agent.operation_schemas()

每項作業的結構定義都是字典，其中記錄了可呼叫的代理程式方法資訊。支援的作業集取決於您用來開發代理程式的架構：

(選用) 授予已部署的代理程式權限

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

後續步驟