管理已部署的代理

借助 Agent Runtime,您可以管理已部署到平台的智能体。您可以使用控制台、SDK 或 REST API 列出、获取、更新和删除已部署的代理。

本文档介绍了如何在 Agent Platform 上管理已部署的代理。 如果您想部署新代理,请参阅部署代理。

列出已部署的代理

列出给定项目和位置的所有已部署代理:

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

属于所选项目的已部署代理会显示在列表中(没有已部署运行时的独立记忆库实例会显示在记忆库页面上)。您可以使用过滤条件字段按指定列过滤列表。

Agent Platform SDK

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

for agent in client.runtimes.list():
    print(agent)

如需按 display_name 过滤列表,请执行以下操作:

for agent in client.runtimes.list(
    config={
        "filter": 'display_name="DISPLAY_NAME"',
    },
):
    print(agent)

REST

调用 reasoningEngines.list 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 GCP 项目 ID
  • LOCATION:支持的区域

HTTP 方法和网址:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

如需发送您的请求,请展开以下选项之一:

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

获取已部署的代理

每个已部署的代理都有一个唯一的 RESOURCE_ID 标识符。如需了解详情,请参阅部署代理。

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

    属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件字段,按指定列过滤列表。

  2. 点击指定代理的名称。系统会打开该代理的指标页面。

  3. 可选:如需查看代理的部署详情,请点击部署详情。Deployment 详情窗格随即打开。如需关闭该窗格,请点击完成。

  4. 可选:如需查看代理的 query 和 streamQuery 网址,请点击 API 网址。API 网址窗格随即会打开。如需关闭该窗格,请点击完成。

Agent Platform SDK

通过以下代码,您可以获取特定的已部署代理:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

remote_agent = client.runtimes.get(
    name="projects/PROJECT_ID_OR_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

REST

调用 reasoningEngines.get 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 GCP 项目 ID
  • LOCATION:支持的区域
  • RESOURCE_ID:已部署代理的资源 ID

HTTP 方法和网址:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

如需发送您的请求,请展开以下选项之一:

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

更新已部署的代理

您可以同时更新已部署代理的一个或多个字段,但必须至少指定一个要更新的字段。

您可以更新已部署代理的非版本化或版本化字段。如果您更新受版本控制的字段,则会创建新的修订版本。如需详细了解版本化字段和管理修订版本,请参阅管理修订版本和流量。

更新已部署的代理所需的时间取决于所执行的更新,但通常需要几秒到几分钟。

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

  2. 对于您指定的代理,点击更多操作菜单 ()。

  3. 点击修改。系统会打开该代理的修改窗格。

  4. 修改智能体的显示名称或说明。

  5. 点击保存。

Agent Platform SDK

如需将已部署的代理(对应于 RESOURCE_NAME)更新为更新后的代理(对应于 UPDATED_AGENT),请执行以下操作:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.update(
    name=RESOURCE_NAME,                    # Required.
    agent=UPDATED_AGENT,                   # Optional.
    config={                                                # Optional.
        "requirements": REQUIREMENTS,      # Optional.
        "display_name": "DISPLAY_NAME",    # Optional.
        "description": "DESCRIPTION",      # Optional.
        "extra_packages": EXTRA_PACKAGES,  # Optional.
    },
)

这些参数与部署代理时使用的参数相同。

REST

调用 reasoningEngines.patch 方法并提供 update_mask 以指定要更新的字段。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 GCP 项目 ID
  • LOCATION:支持的区域
  • RESOURCE_ID:已部署代理的资源 ID
  • update_mask:要更新的以逗号分隔的字段列表

HTTP 方法和网址:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"

请求 JSON 正文:

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION"
}

如需发送您的请求,请展开以下选项之一:

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

为已部署的代理配置遥测

如果您在代理开发期间启用了跟踪记录,则可以使用 Google Cloud 控制台为已部署的代理配置遥测。

为已部署且启用了遥测功能的代理配置遥测:

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

    属于所选项目的 Agent Platform 实例会显示在列表中。您可以使用过滤条件字段按指定列过滤列表。

  2. 找到 Agent Platform 实例所在的行。在遥测配置列下,点击配置。服务配置面板随即打开。

  3. 您可以进行以下配置:

    • 可观测性:您可以配置以下内容:

      • 启用 OpenTelemetry 跟踪记录和日志的插桩:如需填充代理可观测性信息中心和跟踪记录页面,请点击切换开关,将其切换到开启位置。

      • 启用提示输入和回答输出的日志记录:如需收集和存储用户提示和回答的完整内容,请点击切换开关,将其切换到开启位置。

      如果您的代理停用了遥测收集功能,您需要重新部署代理,并将 Vertex AI SDK 版本更新为 >= 1.126.1,才能查看可观测性的配置选项。

    • 容器:为已部署的智能体配置容器设置:

      • 扩缩:输入实例数下限和实例数上限。

      • 资源:为每个容器选择内存和 CPU 限制。

      • 容器并发数:输入实例数下限,以设置每个容器和代理服务器的并发数。建议值为 (2 * CPU + 1),默认值为 9。

    • 访问权限和权限:点击在 IAM 中管理权限,以管理关联服务账号的代理权限。

    • 部署详细信息:查看智能体的部署详细信息,包括资源名称和显示名称。

    • 记忆库:查看和修改智能体的记忆库生成、检索和保留设置。修改需要 aiplatform.reasoningEngines.update 权限;如果没有此权限,这些设置将处于只读状态。

  4. 点击更新或关闭。

查看已部署智能体的指标

对于已部署的代理,您可以使用控制台查看代理的指标:

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

    属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件字段,按指定列过滤列表。

  2. 点击您的代理的名称。系统会显示所选代理的信息中心。

  3. 选择以下信息中心标签页之一:

    • 概览:查看智能体指标的摘要信息中心,包括智能体延迟时间、智能体请求数和智能体错误率。

    • 模型:查看智能体模型的指标信息中心,包括模型调用次数、模型错误率和模型 token 使用情况。

    • 工具:查看智能体工具的指标信息中心,包括工具调用次数、工具错误率和工具延迟时间。

    • 用量:查看智能体用量指标的信息中心,包括输入和输出的 token 用量、容器 CPU 分配和容器内存分配。

    • 日志:如果您为代理启用了 Cloud Logging,则可以查看代理的日志。

Gemini Enterprise Agent Platform 信息中心

紧急停止和撤销访问权限

当已部署的智能体出现异常行为、异常工具使用或涉及安全事件时,您可以通过终止或重新路由运行时实例,或通过 Agent Gateway 和 Identity and Access Management (IAM) 中的政策控制撤消其下游访问权限,来停止其活动。

由于运行时操作和政策更新具有不同的强制执行模型和传播窗口,因此请选择符合突发事件响应时间要求的控制措施。

紧急停止机制和传播时间

下表比较了用于停止代理或撤消其访问权限的可用机制、这些机制对活跃流量的影响以及其预期传播时间:

机制 对活跃流量和会话的影响 一般传播时间
删除已部署的代理(runtimes.delete 或 reasoningEngines.delete) 终止所有运行时容器实例,停止活跃的调用和流式传输会话 (streamQuery),并永久使代理的 SPIFFE 身份 (principal://...) 失效。 删除操作一完成(通常需要几秒钟到几分钟),就会立即生效。
重新路由修订版本流量或归档修订版本(trafficSplitManual 或 agent_gateway_config) 将发送到根 Agent Endpoint 的 100% 流量转移到已知良好的活跃修订版本,或在更新 spec.deployment_spec.agent_gateway_config 时归档现有修订版本。直接发送到特定活跃修订版本资源路径的请求会继续,直到该修订版本被归档或删除。 更新操作需要几秒钟到几分钟才能完成。
在 Agent Gateway 的 Unified Access Policies (UAP) 中应用拒绝规则 (iamEnforcementMode: "ENFORCE") 阻止通过 Agent Gateway 路由的出站工具调用、Model Context Protocol (MCP) 请求和智能体间调用,同时保持运行时容器处于活动状态以供检查。在新的授权检查中进行评估;除非重新授权,否则不会强制终止打开的流式连接。 最终一致:通常会在 2 分钟内生效,但可能需要 7 分钟或更长时间才能在全球范围内传播。群组或 principalSet 成员资格更新可能需要几分钟到几小时才能完成同步。
应用 IAM 拒绝政策、撤销 IAM 角色或绑定 Principal Access Boundary (Principal Access Boundary) 政策 阻止代理身份或关联的服务账号调用 Google Cloud API 和资源。在每个 API 请求中进行评估;不会终止运行时容器本身。 最终一致:通常会在 2 分钟内生效,最长可能需要 7 分钟或更长时间(请参阅访问权限更改传播)。

执行紧急停止

如需立即停止遭到入侵或行为异常的智能体,并防止其执行进一步的下游操作,请完成以下步骤:

  1. 停止活跃的运行时执行或隔离流量:
    • 完全终止(终止开关):如需立即停止所有正在运行的容器并使智能体的 SPIFFE 身份失效,请使用 Google Cloud 控制台、Agent Platform SDK 中的 client.runtimes.delete(name="RESOURCE_NAME", force=True) 或 reasoningEngines.delete REST 方法删除已部署的智能体。
    • 在不删除代理的情况下回滚流量:如需在停止向故障修订版本发送流量的同时保留代理资源及其身份,请使用 trafficSplitManual 更新代理,以将 100% 的根流量路由到已知良好的修订版本,或更新 spec.deployment_spec.agent_gateway_config 以归档预先存在的修订版本。如果调用方直接调用修订版本资源路径,请删除或归档该特定修订版本。如需查看相关说明,请参阅管理修订版本和流量。
  2. 撤销下游工具和资源访问权限:
    • 如需通过 Agent Gateway 屏蔽出站工具和 MCP 服务器调用,请向绑定到网关的 UAP 添加一条针对智能体的 principal:// 或 principalSet:// 标识符的 DENY 规则,并验证 iamEnforcementMode 是否设置为 "ENFORCE"。如需查看相关说明,请参阅配置 IAM 政策以管理代理访问权限。
    • 如需阻止直接 Google Cloud API 调用,请撤消授予代理身份或其自定义服务账号的 IAM 角色,或附加 IAM 拒绝政策或主账号访问边界政策。
  3. 考虑传播窗口并验证控制效果:
    • 当智能体正在执行非预期的工具调用时,请勿仅依赖 IAM 或 UAP 政策更新。政策更改需要 2 到 7 分钟(principalSet 更新需要更长时间)才能在全球范围内传播。请始终将政策撤消与运行时删除或修订版本流量重新路由搭配使用,以实现立即停止。
    • 通过在 Cloud Logging 中查询 is_agentic=true 和 networkservices.googleapis.com/gateway_requests 拒绝,确认代理活动已停止。如需详细了解日志注入和安全发现结果延迟时间,请参阅审核智能体操作和通过 Agent Gateway 监控流量。

删除已部署的代理

从 Agent Runtime 托管式运行时中删除已部署的智能体。删除 Agent Runtime 会使其 Agent Identity 失效。任何向该主体授予权限的 IAM Unified Access Policy (UAP) 都会在其规则中保留已失效的主体。此外,政策绑定仍处于有效状态。如需移除已失效的主账号,请更新 UAP,以从其规则中移除该主账号。如果政策不再包含任何有效主账号,请删除政策绑定。

控制台

  1. 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。

    前往“部署”页面

  2. 对于您指定的代理,点击更多操作菜单 ()。

  3. 点击删除。

  4. 点击删除代理。

Agent Platform SDK

如果您已有所部署代理的实例(作为 remote_agent),则可以运行以下命令:

remote_agent.delete(
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

或者,您也可以通过以下方式调用 runtimes.delete() 来删除与 RESOURCE_NAME 对应的已部署代理:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.delete(
    name=RESOURCE_NAME,
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

REST

调用 reasoningEngines.delete 方法。

在使用任何请求数据之前,请先进行以下替换:

  • PROJECT_ID:您的 GCP 项目 ID
  • LOCATION:支持的区域
  • RESOURCE_ID:已部署代理的资源 ID

HTTP 方法和网址:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

如需发送您的请求,请展开以下选项之一:

您应该会收到一个成功的状态代码 (2xx) 和一个空响应。

后续步骤

指南

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