部署代理

在 Agent Runtime 上部署智能体后，该智能体即可远程处理请求。本文档介绍了根据您的开发工作流部署代理的各种方式：从执行对象、本地源文件、Dockerfile、托管在 Artifact Registry 中的容器映像，或直接通过关联的 Git 代码库进行部署。

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

  • 从代理对象进行部署：非常适合在 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. 创建 Agent Platform 实例
  4. 可选：获取智能体资源 ID
  5. 可选：列出支持的操作
  6. 可选：为所部署的智能体授予权限

您还可以使用 Agents CLI 进行部署。

前提条件

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

  1. 设置环境
  2. 创建代理

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

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

创建 Agent Platform 实例

本部分介绍如何创建 Agent Platform 实例以部署智能体。

如需在 Agent Platform 上部署代理，您可以选择以下方法之一：

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

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

Python 对象

如需在 Agent Platform 上部署智能体，请使用 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. Agent Runtime 服务会接收请求，并在后端构建容器并启动 HTTP 服务器。

Developer Connect

如需从 Agent Platform 上的 Developer Connect 进行部署，请使用 client.agent_engines.create，并在配置字典中提供 developer_connect_source、entrypoint_module 和 entrypoint_object，以及其他可选配置。此方法可让您直接从关联的 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. Agent Runtime 服务从指定的 Git 代码库修订版本中提取源代码。
  2. 服务会安装来自 requirements_file（如果提供）的依赖项。
  3. 服务使用指定的 entrypoint_module 和 entrypoint_object 启动代理应用。

源文件

如需从 Agent Platform 上的源文件进行部署，请使用 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 文件的路径。默认为打包源代码根目录中的 requirements.txt。

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

  1. Agent Platform SDK 会创建 source_packages 中指定路径的 tar.gz 归档。
  2. 此归档文件经过编码，并直接发送到 Agent Platform API。
  3. Agent Runtime 服务接收归档文件，提取该文件，从 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

如需从 Agent Platform 上的 Dockerfile 进行部署，请采用与从源文件进行部署类似的方法。部署时唯一需要更改的地方是将配置中的 entrypoint_module、entrypoint_object 和（可选）requirements_file 替换为 image_spec。根据 Dockerfile 构建的容器必须遵守运行时合同。

以下是使用 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 Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

容器映像

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

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

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

部署延迟时间取决于安装所需软件包花费的总时间。部署后，remote_agent 对应于在 Agent Platform 上运行的 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()

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

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

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

可选：使用企业基础架构部署智能体

如需部署具有完整环境（包括安全层和治理层）的代理，请复制并自定义以下 App Design Center 模板：

后续步骤

指南

了解如何管理已部署到 Agent Platform 托管运行时的代理。

指南

使用 Agent Platform Runtime 中的代理。