部署代理

如需在 Vertex AI Agent Engine 上部署代理，请按以下步骤操作：

1. 配置代理以进行部署。
2. 创建 AgentEngine 实例。
3. 授予已部署的代理权限。
4. 获取代理资源 ID。

您还可以使用 Agent Starter Pack 模板进行部署。

准备工作

在部署代理之前，请确保您已完成以下任务：

1. 设置您的环境。
2. 开发代理。

配置代理以进行部署

您可以进行以下可选配置：

• 软件包要求
• 其他套餐
• 环境变量
• build 选项
• Cloud Storage 文件夹
• 资源元数据

定义软件包要求

提供代理部署所需的软件包集。软件包集可以是 pip 要安装的项的列表，也可以是遵循需求文件格式的文件的路径。请遵循以下最佳实践：

1. 固定软件包版本，以实现可重现的 build。需要跟踪的常见软件包包括：google-cloud-aiplatform、cloudpickle、langchain、langchain-core、langchain-google-vertexai 和 pydantic。

2. 尽可能减少代理中的依赖项数量。这可以减少更新依赖项和代理时发生的破坏性更改的数量。

如果代理没有任何依赖项，您可以将 requirements 设置为 None：

requirements = None

如果代理使用特定于框架的模板，您应在开发代理时指定导入的 SDK 版本（例如 1.77.0）。

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

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

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

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

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

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": "SECRET_ID", "version": "SECRET_VERSION_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"],
#   }

定义 build 选项

您可以为代理指定 build 选项，例如在构建代理的容器映像时要运行的安装脚本。这对于安装系统依赖项（例如 gcloud cli、npx）或其他自定义设置非常有用。

如需使用安装脚本，请创建一个名为 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"]}

定义 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 参考文档。

创建 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.
)

部署需要几分钟时间，在此期间，系统会在后台执行以下步骤：

1. 系统会在本地生成以下工件的软件包：

   • *.pkl 与 local_agent 对应的 pickle 文件。
   • requirements.txt 一个包含软件包要求的文本文件。
   • dependencies.tar.gz 包含任何额外软件包的 tar 文件。

2. 该软件包会上传到 Cloud Storage（位于相应的文件夹下），以暂存工件。

3. 相应制品的 Cloud Storage URI 在 PackageSpec 中指定。

4. 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 资源的形式表示。

后续步骤

• 使用代理。
• 管理已部署的代理。
• 排查代理部署问题。
• 获取支持。