Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

部署代理程式

將代理部署至 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 物件。如果代理的結構不含複雜、無法序列化的元件，這個方法最適合。

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

完成必要條件
選用：設定要部署的代理
建立 Gemini Enterprise Agent Platform 執行個體
選用：取得代理資源 ID
選用：列出支援的操作
選用：授予已部署代理程式權限

必要條件

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

選用：設定要部署的代理

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

定義套件需求

注意：如要從來源檔案部署，則不需使用 requirements 參數。請改為直接在原始碼套件中加入 requirements.txt 檔案。建立 Agent Platform 執行個體時，可以在 requirements_file 參數中指定這個檔案的路徑。

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

固定套件版本，以便重現建構作業。常見的追蹤套件包括：google-cloud-aiplatform、cloudpickle、langchain、langchain-core、langchain-google-vertexai 和 pydantic。
盡可能減少代理中的依附元件數量。這樣一來，更新依附元件和代理時，破壞性變更的數量就會減少。

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

requirements = None

如果代理使用特定框架的範本，請在開發代理時指定匯入的 SDK 版本 (例如 1.112.0)。

ADK

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

A2A

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "google-adk[a2a]",
    # 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.112.0",
  ]

新增其他套件和限制：

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

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

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

在檔案 (例如 path/to/requirements.txt) 中維護需求清單：
```
  requirements = "path/to/requirements.txt"
  
```
其中 path/to/requirements.txt 是遵循需求檔案格式的文字檔案。例如：
```
  google-cloud-aiplatform[agent_engines,adk]
  cloudpickle==3.0
  
```

定義其他套件

注意：只有從代理物件部署時，才需要使用 extra_packages 參數。

您可以加入本機檔案或目錄，其中包含本機必要的 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

如果將 Secret 做為環境變數，並搭配設為使用代理身分的代理，請將 secretmanager.versions.access 權限 (包含在 roles/secretmanager.secretAccessor 角色中) 授予 Agent Platform 服務代理，格式如下：

service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

系統會在執行階段使用您設定的代理身分，但在部署期間，會使用 Agent Platform 服務代理擷取 Secret。新增權限後，服務代理就能在部署程序中，從 Secret Manager 擷取密鑰值。

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

如要指定環境變數，可以選擇下列幾種做法：

字典

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Agent Platform
# 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 中的 Secret，並將其設為環境變數 (例如 CLOUD_SQL_CREDENTIALS_SECRET)，請先按照操作說明，在專案中建立 CLOUD_SQL_CREDENTIALS_SECRET 的 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：

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

您也需要按照「設定代理的身分和權限」中的操作說明，授予代理 Secret Manager Secret 存取者 (roles/secretmanager.secretAccessor) 權限。

定義自訂資源控制項

您可以為代理指定執行階段資源控制項，例如應用程式執行個體數量上下限、各容器的資源限制，以及各容器的並行數量。如要進一步瞭解部署作業參數，請參閱 ReasoningEngineSpec REST 參考資料。

min_instances：一律保持運作的應用程式執行個體數量下限，範圍為 [0, 75]。預設值為 1。

注意：這項功能目前為預先發布版，即使您設定較高的執行個體數量下限，系統也不會針對代理閒置時間收費。這項計費行為日後可能會有變動。
max_instances：可啟動的應用程式執行個體數量上限，用於處理增加的流量，範圍為 [1, 1000]。預設值為 100。如果啟用 VPC-SC 或 PSC-I，則每個 Agent Platform 資源的可接受範圍為 [1, 100]。
resource_limits：各容器的資源限制。僅支援 cpu 和 memory 鍵。預設值為 {"cpu": "4", "memory": "4Gi"}。
- cpu 僅支援 1、2、4、6 和 8。詳情請參閱「設定 CPU 分配」。
- memory 僅支援 1Gi、2Gi、... 32Gi。
- 如要瞭解不同記憶體值所需的 CPU，請參閱「設定記憶體限制」。
container_concurrency：各容器和代理伺服器的並行處理設定。建議值為 2 * cpu + 1。預設值為 9。

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

如要瞭解如何最佳化執行階段資源，請參閱「最佳化及擴充 Agent Runtime」一文。

定義建構選項

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

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

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

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

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

您可以使用下列其中一種常見的安裝指令碼：

install_npx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

install_uvx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

install_gcloud_cli.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

定義代理框架

您可以指定代理使用的代理架構：

agent_framework = "google-adk"

支援的值如下：

如果未指定 agent_framework，且您從代理物件部署，系統會自動偵測值。如果您要從來源檔案部署，agent_framework 預設為 `custom`。

定義 Cloud Storage 資料夾

注意：只有從代理物件部署時，才需要使用 gcs_dir_name 參數。

如果暫存構件與 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)"

定義說明

您可以設定 ReasoningEngine 資源的說明：

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

定義標籤

您可以將 ReasoningEngine 資源的標籤設為鍵/值字串組合的字典。範例如下：

labels = {"author": "username", "version": "latest"}

設定預設代理身分

建立代理時，您可以為部署至 Agent Platform 的代理佈建專屬身分。這個身分會繫結至 Agent Platform 的代理資源 ID，且與您用來開發代理的代理架構無關：

identity_type=AGENT_IDENTITY

詳情請參閱「建立具有代理身分的代理」。

設定自訂服務帳戶

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

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

# Create a new instance
client.runtimes.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.runtimes.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

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

設定 Private Service Connect 介面

如果您已設定 Private Service Connect 介面和私人 DNS 區域，可以在部署代理時指定網路連結，並建立私人 DNS 對接：

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },
    },
)

其中

NETWORK_ATTACHMENT 是網路連結的名稱或完整路徑。如果網路連結是在與 Agent Platform 不同的專案 (例如 Shared VPC 主專案) 中建立，則須傳遞網路連結的完整路徑。
DOMAIN_SUFFIX 是私人 Cloud DNS 區域的 DNS 名稱。
TARGET_PROJECT 是託管虛擬私有雲網路的專案。可以與網路連結專案不同。
TARGET_NETWORK 是 `TARGET_PROJECT` 中建立 DNS 對接的虛擬私有雲網路名稱。

您可以設定多個代理程式，使用單一共用網路連結，或專屬的網路連結。如要使用共用網路連結，請在 psc_interface_config 中為建立的每個代理提供相同的網路連結。

設定客戶自行管理的加密金鑰

您可以使用自訂金鑰，加密代理的靜態資料。詳情請參閱 Agent Engine 的「客戶自行管理的加密金鑰 (CMEK)」一文。

如要為代理設定自訂金鑰 (CMEK)，請在建立代理平台執行個體時，將金鑰資源名稱提供給 encryption_spec 參數。

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

設定 Developer Connect Git 存放區連結

如要透過 Developer Connect 從 Git 存放區部署，請按照 Developer Connect 說明文件建立連線，並連結至特定存放區。連結的資源名稱會在部署期間做為 git_repository_link，格式如下：projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID。

建立 Agent Platform 執行個體

本節說明如何建立 Agent Platform 執行個體，以便部署代理。您可以選擇下列其中一種方法：

Developer Connect

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

這個部署方法僅適用於 Python。

remote_agent = client.runtimes.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。

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

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

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

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

remote_agent.api_resource 其中包含已部署代理程式的相關資訊。您也可以呼叫 remote_agent.operation_schemas()，傳回 remote_agent 支援的作業清單。詳情請參閱「支援的操作」。
remote_agent.api_client 可進行同步服務互動
remote_agent.async_api_client 可進行非同步服務互動

來源檔案

如要從 Agent Platform 上的來源檔案部署，請使用 client.runtimes.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.runtimes.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)：選用。pip 需求檔案的路徑，位於 source_packages 指定的路徑中。預設為封裝來源根目錄中的 requirements.txt。

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

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

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

remote_agent.api_resource 其中包含已部署代理程式的相關資訊。您也可以呼叫 remote_agent.operation_schemas()，傳回 remote_agent 支援的作業清單。詳情請參閱「支援的操作」。
remote_agent.api_client 可進行同步服務互動
remote_agent.async_api_client 可進行非同步服務互動

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.runtimes.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 物件對應至 AgentRuntime 類別，其中包含下列項目：

remote_agent.api_resource 其中包含已部署代理程式的相關資訊。您也可以呼叫 remote_agent.operation_schemas()，傳回 remote_agent 支援的作業清單。詳情請參閱「支援的操作」。
remote_agent.api_client 可進行同步服務互動
remote_agent.async_api_client 可進行非同步服務互動

容器映像檔

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

這種部署方法適用於任何語言。本節中的範例使用 Python。

以下範例說明如何使用容器映像檔部署代理程式：

remote_agent = client.runtimes.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 物件對應至 AgentRuntime 類別，其中包含下列項目：

remote_agent.api_resource 其中包含已部署代理程式的相關資訊。您也可以呼叫 remote_agent.operation_schemas()，傳回 remote_agent 支援的作業清單。詳情請參閱「支援的操作」。
remote_agent.api_client 可進行同步服務互動
remote_agent.async_api_client 可進行非同步服務互動

Agent Platform SDK

如要在 Agent Platform 部署代理，請使用 client.runtimes.create 傳入 local_agent 物件和任何選用設定：

remote_agent = client.runtimes.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.
    },
)

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

系統會在本機產生一組構件，當中含有：
- *.pkl：對應 local_agent 的 pickle 檔案。
- requirements.txt：包含套件需求的文字檔。
- dependencies.tar.gz：包含額外套件的 tar 檔案。
為了暫存構件，這個檔案包會上傳至 Cloud Storage (位於對應的資料夾)。
各個構件的 Cloud Storage URI 會在 PackageSpec 中指定。
Agent Runtime 服務會接收要求、建構容器，並在後端啟動 HTTP 伺服器。

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

remote_agent.api_resource 其中包含已部署代理程式的相關資訊。您也可以呼叫 remote_agent.operation_schemas()，傳回 remote_agent 支援的作業清單。詳情請參閱「支援的操作」。
remote_agent.api_client 可進行同步服務互動
remote_agent.async_api_client 可進行非同步服務互動

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

選用：列出支援的操作

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

remote_agent.operation_schemas()

每項作業的結構定義都是字典，記錄可呼叫的代理方法資訊。支援的操作組合取決於您開發代理時使用的架構：

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

如果需要授予已部署代理任何額外權限，請按照「設定代理的身分和權限」中的操作說明進行。

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

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

後續步驟

指南

管理已部署的代理

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

指南

使用代理

透過 Agent Platform Runtime 使用代理。

部署代理程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Developer Connect

來源檔案

Dockerfile

容器映像檔

Agent Platform SDK

必要條件

選用：設定要部署的代理

定義套件需求

ADK

A2A

LangChain

LangGraph

AG2

LlamaIndex

定義其他套件

定義環境變數

字典

清單

定義自訂資源控制項

定義建構選項

install_npx.sh

install_uvx.sh

install_gcloud_cli.sh

定義代理框架

定義 Cloud Storage 資料夾

定義顯示名稱

定義說明

定義標籤

設定預設代理身分

設定自訂服務帳戶

設定 Private Service Connect 介面

設定客戶自行管理的加密金鑰

設定 Developer Connect Git 存放區連結

建立 Agent Platform 執行個體

Developer Connect

來源檔案

Dockerfile

容器映像檔

Agent Platform SDK

選用：取得代理資源 ID

選用：列出支援的操作

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

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

後續步驟

管理已部署的代理

使用代理

部署代理程式