如要在 Vertex AI Agent Engine 部署代理程式，請按照下列步驟操作：
您也可以使用 Agent Starter Pack 範本進行部署。
事前準備
部署代理程式前，請務必完成下列工作：
設定要部署的代理程式
您可以進行下列選用設定：
定義套件需求
提供代理程式部署作業所需的一組套件。這組套件可以是 pip 要安裝的項目清單，也可以是符合需求檔案格式的檔案路徑。請遵循下列最佳做法：
固定套件版本，確保建構可重現。常見的追蹤包裹包括：
google-cloud-aiplatform、cloudpickle、langchain、langchain-core、langchain-google-vertexai和pydantic。盡可能減少代理程式中的依附元件數量。這樣一來，更新依附元件和代理程式時，重大變更的數量就會減少。
如果代理程式沒有任何依附元件，您可以將 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
如要指定環境變數，有幾種不同的做法：
字典
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)
清單
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"],
# }
定義自訂資源控管
您可以為代理程式指定執行階段資源控制項，例如應用程式執行個體的數量下限和上限、每個容器的資源限制，以及每個容器的並行數。
min_instances：隨時保持執行的應用程式執行個體數量下限，範圍為[0, 10]。預設值為 1。max_instances：可啟動的應用程式執行個體數量上限，用來處理增加的流量，範圍為[1, 1000]。預設值為 100。 如果啟用 VPC-SC 或 PSC-I，可接受的範圍為[1, 100]。resource_limits：每個容器的資源限制。系統僅支援cpu和memory鍵。預設值為{"cpu": "4", "memory": "4Gi"}。container_concurrency：每個容器和代理程式伺服器的並行數。 建議值為 2 *cpu+ 1。預設值為9。
remote_agent = agent_engines.create(
local_agent,
# ... other configs
min_instances=1,
max_instances=10,
resource_limits={"cpu": "4", "memory": "8Gi"},
container_concurrency=9,
)
定義建構選項
您可以為代理程式指定建構選項，例如建構代理程式容器映像檔時要執行的安裝指令碼。這項功能可用於安裝系統依附元件 (例如 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"]}
您可以使用下列常見的安裝指令碼：
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
定義 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="my-custom-service-account@my-project.iam.gserviceaccount.com",
...
)
# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
resource_name,
service_account="my-new-custom-service-account@my-project.iam.gserviceaccount.com",
...
)
設定 Private Service Connect 介面
Vertex AI Agent Engine 支援 Private Service Connect 介面和 DNS 對等互連，可確保輸出流量的隱私權和安全性。
為什麼要使用 Private Service Connect 介面？
代理程式會部署在 Google 管理的安全網路中，無法存取您的虛擬私有雲 (VPC) 網路。PSC 介面會建立安全無虞的私人橋接器，連往您的網路，因此建議您使用這項解決方案，與虛擬私有雲、內部部署和多雲環境中以私密方式代管的服務互動。
除了提供私人存取權之外，使用 VPC Service Controls 時，也必須透過這個連線啟用網際網路存取權。請參閱「存取公用網際網路」。
運作方式
設定 PSC 介面時，Agent Engine 會在 Google 擁有的租戶專案中佈建介面，您的代理程式會在該專案中執行。這個介面會直接連線至專案中的網路連結。代理程式與 VPC 之間的所有流量都會在 Google 網路中安全傳輸，絕不會經過公開網際網路。
存取公用網際網路
代理程式能否存取公用網際網路，取決於專案的安全設定，特別是您是否使用 VPC Service Controls。
預設行為 (不使用 VPC Service Controls)
- 如果您只使用 PSC 介面設定代理程式，代理程式會保留預設的網際網路存取權。這類輸出流量會直接從安全無虞的 Google 管理環境輸出，也就是執行代理程式的環境。
使用 VPC Service Controls
- 如果專案屬於 VPC Service Controls 範圍，範圍會封鎖代理程式的預設網際網路存取權，防止資料外洩。如要允許代理程式在此情境中存取公開網際網路，您必須明確設定安全輸出路徑，透過虛擬私有雲傳送流量。建議您在虛擬私有雲周邊設定 Proxy 伺服器，並建立 Cloud NAT 閘道，允許 Proxy VM 存取網際網路。
事前準備
如要使用 Private Service Connect 介面，為已部署的代理程式啟用私人連線，您需要在使用者專案中設定虛擬私有雲網路、子網路和網路連結。
子網路 IP 範圍規定
Agent Engine 會建議使用 /28 子網路。
網路附件的子網路支援 RFC 1918 和非 RFC 1918 位址，但 100.64.0.0/10 和 240.0.0.0/4 子網路除外。Agent Engine 只能連線至可從指定網路路由傳輸的 RFC 1918 IP 位址範圍。Agent Engine 無法連線至私用公開 IP 位址，或下列非 RFC 1918 範圍：
100.64.0.0/10192.0.0.0/24192.0.2.0/24198.18.0.0/15198.51.100.0/24203.0.113.0/24240.0.0.0/4
如要進一步瞭解設定程序，請參閱「設定 Private Service Connect 介面」。
搭配共用虛擬私有雲使用
您可以在共用虛擬私有雲架構中使用 Private Service Connect 介面，在服務專案中建立 Agent Engine，同時使用中央主專案的網路。
在共用虛擬私有雲環境中設定 PSC-I 時，請在主專案中建立子網路，然後在服務專案中建立網路附件。
如要讓服務專案使用主專案的網路，您必須授予適當的 IAM 權限。服務專案的 Vertex AI 服務代理程式需要主專案的 Compute Network User (roles/compute.networkUser) 角色。
使用 Private Service Connect 介面部署代理程式
設定網路附件後，您可以在建立 AgentEngine 執行個體時指定該附件。
remote_agent = agent_engines.create(
agent_engine=local_agent,
psc_interface_config={
"network_attachment": "NETWORK_ATTACHMENT",
},
)
其中
NETWORK_ATTACHMENT是您建立的網路附件名稱或完整路徑。
搭配多個代理程式使用網路附件
您可以彈性決定客服專員如何共用網路資源。 您可以設定多個代理程式，使用單一共用網路附件，或專屬的獨立網路附件。
如要使用共用網路連結，請在您建立的每個代理程式中，提供相同的網路連結。psc_interface_config
DNS 對等互連
Private Service Connect 介面提供安全的網路路徑，DNS 對等互連則提供服務探索機制。使用 PSC-I 時，您仍需知道 VPC 網路中服務的特定 IP 位址。雖然您可以使用服務的內部 IP 位址連線，但我們不建議在 IP 位址可能會變更的實際工作環境系統中這麼做。透過 DNS 對等互連，已部署的代理程式可以使用穩定且使用者能理解的 DNS 名稱 (而非 IP 位址)，連線至虛擬私有雲網路中的服務。DNS 對等互連功能可讓已部署的代理程式，使用虛擬私有雲中 Cloud DNS 私人區域的記錄解析 DNS 名稱。請參閱設定私人 DNS 對等互連。
設定私人 DNS 對等互連後，您可以在建立 AgentEngine 執行個體時指定該互連。
remote_agent = agent_engines.create(
agent_engine=local_agent,
psc_interface_config={
"network_attachment": "NETWORK_ATTACHMENT",
"dns_peering_configs": [
{
"domain": "DOMAIN_SUFFIX",
"target_project": "TARGET_PROJECT",
"target_network": "TARGET_NETWORK",
}
],
},
)
其中
NETWORK_ATTACHMENT是您建立的網路附件名稱或完整路徑。DOMAIN_SUFFIX是您在設定私人 DNS 對等互連時建立的私人 Cloud DNS 區域 DNS 名稱。TARGET_PROJECT是代管虛擬私有雲網路的專案。TARGET_NETWORK是虛擬私有雲網路名稱。
設定客戶自行管理的加密金鑰
您可以使用自訂金鑰加密代理程式的靜態資料。詳情請參閱 Agent Engine 的客戶自行管理加密金鑰 (CMEK)。
如要為代理程式設定自訂金鑰 (CMEK)，請在建立 Agent Engine 執行個體時，將金鑰資源名稱提供給 encryption_spec 參數。
# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
remote_agent = agent_engines.create(
local_agent,
# ... other parameters
encryption_spec={"kms_key_name": kms_key_name},
)
建立 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.
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.
)
部署作業需要幾分鐘，期間系統會在背景執行下列步驟：
系統會在本地產生下列成果套件：
套件會上傳至 Cloud Storage (位於對應的資料夾)，用於暫存構件。
各個構件的 Cloud Storage URI 會在 PackageSpec 中指定。
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資源的形式呈現。