部署代理

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

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

您还可以使用客服助理入门套件模板进行部署。

准备工作

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

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

（可选）定义软件包要求

提供代理部署所需的一组软件包。这组软件包可以是 pip 要安装的项的列表，也可以是遵循需求文件格式的文件的路径。

如果代理没有任何依赖项，您可以将 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
]

（可选）版本限制

如需对给定软件包（例如 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 上无法获得。

如果代理不需要任何额外的软件包，您可以将其设置为 None：

extra_packages = None

（可选）定义文件和目录

如需添加单个文件（例如 agents/agent.py），请将其添加到 extra_packages 列表中：

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

（可选）定义 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())

（可选）配置资源元数据

您可以在 Vertex AI 中创建的 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 并将对象作为参数传入：

remote_agent = agent_engines.create(
    local_agent,                    # Required.
    requirements=requirements,      # Optional.
    extra_packages=extra_packages,  # Optional.
    gcs_dir_name=gcs_dir_name,      # Optional.
    display_name=display_name,      # Optional.
    description=description,        # 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 的实例，您可以查询或删除它们。它独立于代理的本地实例。

（可选）向部署的代理授予权限

如果需要向已部署的代理授予任何其他权限，您可以按照设置服务代理权限中的说明操作。

ADK

部署的 ADK 代理需要获得以下权限才能使用受管理的会话：

  • Vertex AI User (roles/aiplatform.user)

获取代理资源 ID

每个已部署的代理都有一个唯一标识符。您可以运行以下命令以获取已部署的代理的 resource_name 标识符：

remote_agent.resource_name

响应应如下所示的字符串：

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

其中

  • PROJECT_ID 是部署的代理运行所在的 Google Cloud 项目 ID。

  • LOCATION 是部署的代理运行的区域。

  • RESOURCE_ID 是已部署代理作为 reasoningEngine 资源的 ID。

使用代理 Starter Pack 在生产环境中部署

客服助手入门套件是一组专为 Vertex AI Agent Engine 构建的、可投入生产环境的生成式 AI 客服助手模板。它通过提供以下功能来加快部署速度：

  • 预构建的代理模板：ReAct、RAG、多智能体等。
  • Interactive Playground：测试和与您的代理互动。
  • 自动化基础架构：使用 Terraform 简化资源管理。
  • CI/CD 流水线：利用 Cloud Build 的自动部署工作流。
  • 可观测性：内置对 Cloud Trace 和 Cloud Logging 的支持。

开始：快速入门

部署最佳实践

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

  2. 尽可能减少代理中的依赖项数量。这可以减少更新依赖项时发生的破坏性更改的数量，并让您可以更轻松地随着时间的推移更新代理以获取新功能。

后续步骤