部署代理

将智能体部署到 Agent Runtime 后，它就可以远程处理请求。本文档介绍了如何根据开发工作流部署智能体：从执行对象、本地源代码文件、Dockerfile、Artifact Registry 中托管的容器映像，或直接通过连接的 Git 代码库。

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

Developer Connect

建议用于在 Git 代码库中管理并通过 Developer Connect 关联的项目。此方法可直接从源代码简化智能体部署，并原生支持版本控制、团队协作和 CI/CD 流水线。在使用此方法之前，请按照设置 Developer Connect Git 代码库链接中的说明设置 Git 代码库链接。

此部署方法仅适用于 Python。

源文件

非常适合自动化工作流（例如 CI/CD 流水线）和基础设施即代码工具（例如 Terraform），可实现完全声明式和自动化的部署。它会直接从本地源代码部署智能体，不需要 Cloud Storage 存储桶。

此部署方法仅适用于 Python。

Dockerfile

与从源文件部署类似。您可以直接从本地源代码部署智能体，而无需使用 Cloud Storage 存储桶。如果您需要定义和控制已部署的 API 服务器，则此方法非常合适。部署的容器必须遵循运行时协定。

您可以将此部署方法与任何语言搭配使用。本页面中的示例使用 Python。

容器映像

与从 Dockerfile 部署类似。您部署托管在 Artifact Registry 中的容器映像。如果您需要控制容器映像的构建过程并缩短部署延迟时间，请使用此方法。容器映像必须遵循运行时协定。

您可以将此部署方法与任何语言搭配使用。本页面中的示例使用 Python。

Agent Platform SDK

非常适合在 Colab 等环境中进行交互式开发，支持部署内存中的 local_agent 对象。此方法最适合结构不包含复杂、不可序列化组件的智能体。

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

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

前提条件

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

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

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

您可以为智能体进行可选配置。本部分中的示例使用 Python。

创建 Agent Platform 实例

本部分介绍如何创建用于部署代理的代理平台实例。您可以从以下方法中进行选择：

Developer Connect

如需在 Agent Platform 上通过 Developer Connect 进行部署，请使用 client.runtimes.create，并在配置字典中提供 developer_connect_source、entrypoint_module 和 entrypoint_object，以及其他可选配置。通过此方法，您可以直接从关联的 Git 代码库部署代码。

此部署方法仅适用于 Python。 

remote_agent = client.runtimes.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 文件的路径。默认值为 requirements.txt。

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

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

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

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

源文件

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

此部署方法仅适用于 Python。 

# 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.runtimes.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": "",  # Options: "", "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. Agent Platform SDK 会为 source_packages 中指定的路径创建 tar.gz 归档。
  2. 此归档文件会经过编码，并直接发送到 Agent Platform API。
  3. Agent Runtime 服务接收归档文件，将其解压缩，从 requirements_file（如果提供）安装依赖项，并使用指定的 entrypoint_module 和 entrypoint_object 启动智能体应用。

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

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

Dockerfile

在代理平台上从 Dockerfile 部署与从源文件部署类似，只是您在配置中使用 image_spec，而不是 entrypoint_module、entrypoint_object 和 requirements_file。通过 Dockerfile 构建的容器必须遵循运行时协定。

您可以将此部署方法与任何语言搭配使用。本部分中的示例使用 Python。

以下是使用 Dockerfile 部署智能体的示例：

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

remote_agent = client.runtimes.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",
    }
)

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

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

容器映像

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

您可以将此部署方法与任何语言搭配使用。本部分中的示例使用 Python。

以下是使用容器映像部署智能体的示例：

remote_agent = client.runtimes.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 对象对应于包含以下内容的 AgentRuntime 类：

Agent Platform SDK

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

remote_agent = client.runtimes.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 服务器。

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

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

可选：获取智能体资源 ID

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

remote_agent.api_resource.name

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

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

其中

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

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

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

可选：列出支持的操作

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

remote_agent.operation_schemas()

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

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

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

可选：使用企业基础架构部署代理

如需使用包含安全和治理层的完整环境部署智能体，请复制并自定义以下应用设计中心模板：

后续步骤

指南

了解如何管理已部署到 Agent Platform 托管式运行时的智能体。

指南

将智能体与 Agent Platform Runtime 搭配使用。