如需在 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 接口
Vertex AI Agent Engine 支持 Private Service Connect 接口和 DNS 对等互连，以实现私密安全的出站流量。
为何使用 Private Service Connect 接口？
您的代理部署在安全的 Google 管理的网络中，无法访问您的 Virtual Private Cloud (VPC) 网络。PSC 接口可为您的网络创建专用安全桥接，因此是与 VPC、本地和多云环境中私密托管的服务进行交互的推荐解决方案。
除了提供私密访问权限之外，在使用 VPC Service Controls 时，还需要此连接来启用互联网访问权限。请参阅访问公共互联网。
运作方式
配置 PSC 接口时，Agent Engine 会在 Google 拥有的租户项目中预配一个接口，您的代理会在该项目中运行。此接口直接连接到您项目中的网络连接。代理与 VPC 之间的所有流量都在 Google 的网络内安全传输，绝不会通过公共互联网传输。
访问公共互联网
代理能否访问公共互联网取决于项目的安全配置，特别是您是否在使用 VPC Service Controls。
默认行为（不使用 VPC Service Controls）
- 如果您仅使用 PSC 接口配置代理，则该代理会保留其默认互联网访问权限。此出站流量直接从代理运行的安全的 Google 管理环境中出站。
使用 VPC Service Controls
- 当您的项目属于 VPC Service Controls 边界时，该边界会阻止代理的默认互联网访问权限，以防止数据渗漏。如需在此场景中允许代理访问公共互联网，您必须明确配置一条安全的出站路径，以通过您的 VPC 路由流量。实现此目的的推荐方法是在 VPC 边界内设置代理服务器，并创建 Cloud NAT 网关以允许代理虚拟机访问互联网。
准备工作
如需使用 Private Service Connect 接口为已部署的代理启用专用连接，您需要在用户项目中设置 VPC 网络、子网和网络连接。
子网 IP 地址范围要求
Agent Engine 建议使用 /28 子网。
网络连接的子网支持 RFC 1918 和非 RFC 1918 地址，但子网 100.64.0.0/10 和 240.0.0.0/4 除外。代理引擎只能连接到可从指定网络路由的 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 接口。
与共享 VPC 搭配使用
您可以将 Private Service Connect 接口与共享 VPC 架构搭配使用，这样您就可以在服务项目中创建 Agent Engine，同时使用来自中央宿主项目的网络。
在共享 VPC 环境中设置 PSC-I 时，请在宿主项目中创建子网，然后在服务项目中创建网络连接。
如需让服务项目使用宿主项目的网络，您必须授予相应的 IAM 权限。服务项目中的 Vertex AI Service Agent 需要宿主项目中的 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 地址）连接到 VPC 网络中的服务。借助 DNS 对等互连，已部署的代理可以使用 VPC 中 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是托管 VPC 网络的项目。TARGET_NETWORK是 VPC 网络名称。
配置客户管理的加密密钥
您可以使用自定义密钥来加密代理的静态数据。如需了解详情，请参阅 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资源的形式表示。