部署代理

如需在 Vertex AI Agent Engine 上部署智能体，请选择以下方法之一：

  • 从代理对象进行部署：非常适合在 Colab 等环境中进行交互式开发，可用于部署内存中的 local_agent 对象。此方法最适合结构不包含复杂、不可序列化组件的代理。
  • 从源文件进行部署：此方法非常适合自动化工作流，例如 CI/CD 流水线和 Terraform 等基础设施即代码工具，可实现完全声明式和自动化的部署。它直接从本地源代码部署代理，不需要 Cloud Storage 存储桶。
  • 从 Dockerfile 进行部署：此方法与从源文件进行部署的方法类似。您可以直接从本地源代码部署代理。您无需使用 Cloud Storage 存储桶。如果您需要定义并控制所部署的 API 服务器，则此方法非常适合。
  • 从容器映像进行部署：此方法与从 Dockerfile 进行部署的方法类似。您部署的是托管在 Artifact Registry 中的容器映像。如果您需要控制容器映像的构建流程并降低部署延迟时间，请使用此方法。
  • 通过 Developer Connect 进行部署：建议用于通过 Developer Connect 关联的 Git 代码库中管理的项目。此方法可直接从源代码简化代理部署，并原生支持版本控制、团队协作和 CI/CD 流水线。 在使用此方法之前，请按照设置 Developer Connect Git 代码库链接中的说明设置 Git 代码库链接。

如需开始使用，请按以下步骤操作：

  1. 完成前提条件。
  2. （可选）配置智能体以进行部署。
  3. 创建 AgentEngine 实例。
  4. （可选）获取智能体资源 ID。
  5. （可选）列出支持的操作。
  6. （可选）为所部署的智能体授予权限。

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

前提条件

在部署智能体之前，请确保您已完成以下任务：

  1. 设置您的环境。
  2. 开发智能体。

（可选）配置智能体以进行部署

您可以为智能体进行以下可选配置：

创建 AgentEngine 实例

本部分介绍如何创建 AgentEngine 实例以部署代理。

如需在 Vertex AI Agent Engine 上部署智能体，您可以选择以下方法：

  • 从代理对象部署以进行交互式开发。
  • 通过 Developer Connect 部署，以实现基于 Git 的工作流。
  • 从源代码文件或 Dockerfile 部署，以用于基于文件的工作流。

  • 从容器映像部署，以实现基于映像的工作流。

Python 对象

如需在 Vertex AI 上部署智能体，请使用 client.agent_engines.create 传入 local_agent 对象以及任何可选配置：

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

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

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

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

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

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

  4. Vertex AI Agent Engine 服务会接收请求，并在后端构建容器并启动 HTTP 服务器。

Developer Connect

如需从 Vertex AI 上的 Developer Connect 进行部署，请在配置字典中提供 developer_connect_source、entrypoint_module 和 entrypoint_object，并使用 client.agent_engines.create，同时还可以提供其他可选配置。此方法可让您直接从关联的 Git 代码库部署代码。

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Developer Connect 部署的参数如下：

  • developer_connect_source（必需，dict）：用于提取源代码的配置。如需了解详情，请参阅设置 Developer Connect Git 代码库链接。
    • git_repository_link（必需，str）：Developer Connect Git 代码库链接资源名称。
    • revision（必需，str）：要提取的修订版本（分支、标记或提交 SHA）。
    • dir（必需，str）：代码库中代理代码的根目录。
  • entrypoint_module（必需，str）：包含代理入口点的 Python 模块名称，相对于 developer_connect_source.dir 中指定的目录。
  • entrypoint_object（必需，str）：entrypoint_module 中表示代理应用的可调用对象的名称（例如 root_agent）。
  • requirements_file（可选，str）：相对于来源根目录的 pip 要求文件的路径。默认值为 requirements.txt。

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

  1. Vertex AI Agent Engine 服务从指定的 Git 代码库修订版本中提取源代码。
  2. 服务会安装来自 requirements_file 的依赖项（如果已提供）。
  3. 服务使用指定的 entrypoint_module 和 entrypoint_object 启动代理应用。

源文件

如需从 Vertex AI 上的源文件进行部署，请使用 client.agent_engines.create，并在配置字典中提供 source_packages、entrypoint_module、entrypoint_object 和 class_methods，以及其他可选配置。使用此方法时，您无需传递代理对象或 Cloud Storage 存储桶。

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

内嵌来源部署的参数如下：

  • source_packages（必需，list[str]）：要纳入部署中的本地文件或目录路径的列表。source_packages 中文件和目录的总大小不应超过 8MB。
  • entrypoint_module（必需，str）：包含代理入口点的完全限定 Python 模块名称（例如 agent_dir.agent）。
  • entrypoint_object（必需，str）：entrypoint_module 中表示代理应用的可调用对象的名称（例如 root_agent）。

  • class_methods（必需，list[dict]）：一个字典列表，用于定义代理的公开方法。每个字典都包含 name（必需）、api_mode（必需）和 parameters 字段。如需详细了解自定义代理的方法，请参阅列出支持的操作。

    例如：

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • requirements_file（可选，str）：source_packages 中指定的路径内某个 pip 要求文件的路径。默认为打包源代码根目录中的 requirements.txt。

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

  1. Vertex AI SDK 会创建 source_packages 中指定路径的 tar.gz 归档。
  2. 此归档文件经过编码，并直接发送到 Vertex AI API。
  3. Vertex AI Agent Engine 服务会接收归档文件，对其进行解压缩，从 requirements_file（如果已提供）安装依赖项，并使用指定的 entrypoint_module 和 entrypoint_object 启动代理应用。

以下示例展示了如何从源文件部署代理：

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

Dockerfile

如需在 Vertex AI 上从 Dockerfile 进行部署，请采用与从源文件进行部署类似的方法。部署时唯一需要更改的地方是将配置中的 entrypoint_module、entrypoint_object 和（可选）requirements_file 替换为 image_spec。

以下是使用 Dockerfile 部署代理的示例：

from google.cloud.aiplatform import vertexai

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells AgentEngine to use the Dockerfile
        # Other optional configs
    }
)

容器映像

如需从容器映像进行部署，请先按照自带容器的设置说明操作，确保安装满足 >=1.144 的 google-cloud-aiplatform 版本。接下来，运行以下代码：

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
    },
)

其中，CONTAINER_IMAGE_URI 对应于 Artifact Registry 中容器映像的 URI（例如 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag）。

部署延迟时间取决于安装所需软件包花费的总时间。部署后，remote_agent 对应于在 Vertex AI 上运行的 local_agent 的实例，您可以查询或删除该实例。

remote_agent 对象对应于包含以下内容的 AgentEngine 类：

（可选）获取智能体资源 ID

每个已部署的智能体都有一个唯一标识符。您可以运行以下命令来获取所部署智能体的资源名称：

remote_agent.api_resource.name

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

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

其中

  • PROJECT_ID 是所部署智能体运行的 Google Cloud 项目 ID。

  • LOCATION 是所部署智能体运行所在的区域。

  • RESOURCE_ID 是所部署智能体的 ID，以 reasoningEngine 资源的形式表示。

（可选）列出支持的操作

每个已部署的智能体都有一份支持的操作列表。您可以使用 AgentEngine.operation_schemas 获取已部署的智能体支持的操作列表：

remote_agent.operation_schemas()

每个操作的架构都是一个字典，用于记录您可以调用的代理方法的相关信息。支持的操作集取决于您用于开发智能体的框架：

（可选）为所部署的智能体授予权限

如果需要向所部署的智能体授予任何其他权限，请按照为智能体设置身份和权限中的说明操作。

后续步骤