部署代理程式

將代理部署至 Agent Runtime 後，代理就能遠端處理要求。本文說明如何根據開發工作流程部署代理程式：從執行物件、本機來源檔案、Dockerfile、Artifact Registry 中代管的容器映像檔，或直接透過已連線的 Git 存放區。

如要在 Agent Runtime 上部署代理，請選擇下列其中一種方法：

Developer Connect

建議用於透過 Developer Connect 連結的 Git 存放區中管理的專案。這個方法可直接從原始碼簡化代理程式部署作業，並原生支援版本控管、團隊協作和 CI/CD 管道。使用這個方法前，請先按照「設定 Developer Connect Git 存放區連結」一文中的操作說明，設定 Git 存放區連結。

您只能搭配 Python 使用這個部署方法。

來源檔案

非常適合自動化工作流程，例如 CI/CD 管道和基礎架構即程式碼工具 (如 Terraform)，可實現全宣告式自動化部署。直接從本機原始碼部署代理程式，不需要 Cloud Storage bucket。

您只能搭配 Python 使用這個部署方法。

Dockerfile

與從來源檔案部署類似。您可以直接從本機原始碼部署代理程式，不需要 Cloud Storage bucket。如果您需要定義及控管部署的 API 伺服器，這個方法就非常適合。部署的容器必須遵守執行階段合約。

您可以使用任何語言搭配這種部署方法。本頁的範例使用 Python。

容器映像檔

與從 Dockerfile 部署類似。您要部署託管在 Artifact Registry 中的容器映像檔。如果您需要控管容器映像檔的建構程序，並縮短部署延遲時間，請使用這個方法。容器映像檔必須遵守執行階段合約。

您可以使用任何語言搭配這種部署方法。本頁的範例使用 Python。

Agent Platform SDK

適合在 Colab 等環境中進行互動式開發，可部署記憶體內 local_agent 物件。這個方法最適合結構不含複雜、無法序列化元件的代理程式。

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

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

必要條件

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

  1. 設定環境
  2. 建立代理

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

您可以為代理程式設定選用設定。本節中的範例使用 Python。

建立 Agent Platform 執行個體

本節說明如何建立 Agent Platform 執行個體，以部署代理程式。你可以選擇下列任一方法：

Developer Connect

如要從 Agent Platform 上的 Developer Connect 部署，請使用 client.agent_engines.create，並在設定字典中提供 developer_connect_source、entrypoint_module 和 entrypoint_object，以及其他選用設定。這個方法可讓您直接從已連結的 Git 存放區部署程式碼。

您只能搭配 Python 使用這個部署方法。 

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Developer Connect 部署作業的參數如下：

  • developer_connect_source (dict)：用於擷取原始碼的設定。詳情請參閱「設定 Developer Connect Git 存放區連結」。
    • git_repository_link (str)：Developer Connect Git 存放區連結資源名稱。
    • revision (str)：要擷取的修訂版本 (分支版本、標記或提交 SHA)。
    • dir (str)：存放區中代理程式碼的根目錄。
  • entrypoint_module (str)：包含代理程式進入點的 Python 模組名稱，相對於 developer_connect_source.dir 中指定的目錄。
  • entrypoint_object (str)：entrypoint_module 中可呼叫物件的名稱，代表代理程式應用程式 (例如 root_agent)。
  • requirements_file (str)：選用：相對於來源根目錄的 pip 需求檔案路徑。預設值為 requirements.txt。

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

  1. Agent Runtime 服務會從指定的 Git 存放區修訂版本擷取原始碼。
  2. 服務會從 requirements_file 安裝依附元件 (如有提供)。
  3. 服務會使用指定的 entrypoint_module 和 entrypoint_object 啟動代理程式應用程式。

部署延遲時間取決於安裝必要套件所花費的總時間。部署後，remote_agent 對應於在 Agent Platform 上執行的 local_agent 執行個體，可供查詢或刪除。

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

來源檔案

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

您只能搭配 Python 使用這個部署方法。 

# 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={
        "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": "",  # Options: "", "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. Agent Platform SDK 會建立 source_packages 中指定路徑的 tar.gz 封存檔。
  2. 這個封存檔會經過編碼，並直接傳送至 Agent Platform API。
  3. Agent Runtime 服務會接收封存檔、解壓縮、從 requirements_file 安裝依附元件 (如有提供)，並使用指定的 entrypoint_module 和 entrypoint_object 啟動代理程式應用程式。

部署延遲時間取決於安裝必要套件所花費的總時間。部署後，remote_agent 對應於在 Agent Platform 上執行的 local_agent 執行個體，可供查詢或刪除。

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

Dockerfile

從 Agent Platform 上的 Dockerfile 部署，與從來源檔案部署的方法類似，但您要在設定中使用 image_spec，而不是 entrypoint_module、entrypoint_object 和 requirements_file。從 Dockerfile 建構的容器必須遵守執行階段合約。

您可以使用任何語言搭配這種部署方法。本節的範例使用 Python。

以下是使用 Dockerfile 部署代理程式的範例：

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

部署延遲時間取決於安裝必要套件所花費的總時間。部署後，remote_agent 對應於在 Agent Platform 上執行的 local_agent 執行個體，可供查詢或刪除。

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

容器映像檔

如要從容器映像檔部署，請先按照「自備容器」的設定說明操作，並確保安裝的 google-cloud-aiplatform 版本符合 >=1.144。容器映像檔必須遵守執行階段合約。

您可以使用任何語言搭配這種部署方法。本節的範例使用 Python。

以下是使用容器映像檔部署代理程式的範例：

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

其中 CONTAINER_IMAGE_URI 對應於 Artifact Registry 中容器映像檔的 URI (例如 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag)。

部署延遲時間取決於安裝必要套件所花費的總時間。部署後，remote_agent 對應於在 Agent Platform 上執行的 local_agent 執行個體，可供查詢或刪除。

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

Agent Platform SDK

如要在 Agent Platform 上部署代理程式，請使用 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. Agent Runtime 服務會接收要求、建構容器，並在後端啟動 HTTP 伺服器。

部署延遲時間取決於安裝必要套件的總時間。部署後，remote_agent 對應於在 Agent Platform 上執行的 local_agent 執行個體，可供查詢或刪除。

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

選用：取得代理程式資源 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 資源。

選用：列出支援的作業

每個已部署的代理程式都有支援的作業清單。您可以使用 AgentEngine.operation_schemas 取得已部署代理程式支援的作業清單：

remote_agent.operation_schemas()

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

選用：授予已部署的代理權限

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

選用：使用企業基礎架構部署代理

如要部署代理程式，並使用包含安全性和管理層的完整環境，請複製並自訂下列 App Design Center 範本：

後續步驟

指南

瞭解如何管理已部署至 Agent Platform 受管理執行階段的代理程式。

指南

使用 Agent Platform Runtime 執行代理程式。