如需在 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 中的某个 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是相应 Secret 版本的 ID。SECRET_ID是相应 Secret 的 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"],
# }
定义自定义资源控制
您可以为代理指定运行时资源控制，例如应用实例的最小和最大数量、每个容器的资源限制以及每个容器的并发。
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 存储桶中的现有文件夹相对应，则会被覆盖。如有必要，您可以为暂存制品指定 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 接口
如果您已设置 Private Service Connect 接口和 DNS 对等互连，则可以在部署代理时指定网络连接和专用 DNS 对等互连：
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是托管 VPC 网络的项目。TARGET_NETWORK是 VPC 网络名称。
您可以配置多个代理，以使用单个共享网络连接或唯一的专用网络连接。如需使用共享网络连接，请在您创建的每个代理的 psc_interface_config 中提供相同的网络连接。
配置客户管理的加密密钥
您可以使用自定义密钥来加密代理的静态数据。如需了解详情，请参阅 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（位于相应的文件夹下），用来暂存制品。
PackageSpec 中指定了相应制品的 Cloud Storage URI。
Vertex AI Agent Engine 服务会接收请求，并在后端构建容器并启动 HTTP 服务器。
部署延迟时间取决于安装所需软件包花费的总时间。部署后，remote_agent 对应于在 Vertex AI 上运行的 local_agent 的实例，您可以查询或删除该实例。该实例独立于智能体的本地实例。
为所部署的智能体授予权限
如果需要向所部署的代理授予任何其他权限，请按照为代理设置身份和权限中的说明操作。
如果您将 Secret 定义为环境变量，则需要授予以下权限：
- Secret Manager Secret Accessor (
roles/secretmanager.secretAccessor)
获取智能体资源 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资源的形式表示。