本文档介绍了如何在 Agent Platform 上管理已部署的代理。 如果您想部署新代理,请参阅部署代理。
列出已部署的代理
列出给定项目和位置的所有已部署代理:
控制台
- 在 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 项目 IDLOCATION:支持的区域
HTTP 方法和网址:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines
如需发送您的请求,请展开以下选项之一:
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
获取已部署的代理
每个已部署的代理都有一个唯一的 RESOURCE_ID 标识符。如需了解详情,请参阅部署代理。
控制台
- 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。
属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件字段,按指定列过滤列表。
点击指定代理的名称。系统会打开该代理的指标页面。
可选:如需查看代理的部署详情,请点击部署详情。Deployment 详情窗格随即打开。如需关闭该窗格,请点击完成。
可选:如需查看代理的
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 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 ID
HTTP 方法和网址:
GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
如需发送您的请求,请展开以下选项之一:
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
更新已部署的代理
您可以同时更新已部署代理的一个或多个字段,但必须至少指定一个要更新的字段。
您可以更新已部署代理的非版本化或版本化字段。如果您更新受版本控制的字段,则会创建新的修订版本。如需详细了解版本化字段和管理修订版本,请参阅管理修订版本和流量。
更新已部署的代理所需的时间取决于所执行的更新,但通常需要几秒到几分钟。
控制台
- 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。
对于您指定的代理,点击更多操作菜单 ()。
点击修改。系统会打开该代理的修改窗格。
修改智能体的显示名称或说明。
点击保存。
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 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 IDupdate_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 控制台为已部署的代理配置遥测。
为已部署且启用了遥测功能的代理配置遥测:
- 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。
属于所选项目的 Agent Platform 实例会显示在列表中。您可以使用过滤条件字段按指定列过滤列表。
找到 Agent Platform 实例所在的行。在遥测配置列下,点击配置。服务配置面板随即打开。
您可以进行以下配置:
可观测性:您可以配置以下内容:
启用 OpenTelemetry 跟踪记录和日志的插桩:如需填充代理可观测性信息中心和跟踪记录页面,请点击切换开关,将其切换到开启位置。
启用提示输入和回答输出的日志记录:如需收集和存储用户提示和回答的完整内容,请点击切换开关,将其切换到开启位置。
如果您的代理停用了遥测收集功能,您需要重新部署代理,并将 Vertex AI SDK 版本更新为
>= 1.126.1,才能查看可观测性的配置选项。容器:为已部署的智能体配置容器设置:
扩缩:输入实例数下限和实例数上限。
资源:为每个容器选择内存和 CPU 限制。
容器并发数:输入实例数下限,以设置每个容器和代理服务器的并发数。建议值为 (2 * CPU + 1),默认值为 9。
访问权限和权限:点击在 IAM 中管理权限,以管理关联服务账号的代理权限。
部署详细信息:查看智能体的部署详细信息,包括资源名称和显示名称。
记忆库:查看和修改智能体的记忆库生成、检索和保留设置。修改需要
aiplatform.reasoningEngines.update权限;如果没有此权限,这些设置将处于只读状态。
点击更新或关闭。
查看已部署智能体的指标
对于已部署的代理,您可以使用控制台查看代理的指标:
- 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。
属于所选项目的已部署代理会显示在列表中。您可以使用过滤条件字段,按指定列过滤列表。
点击您的代理的名称。系统会显示所选代理的信息中心。
选择以下信息中心标签页之一:
概览:查看智能体指标的摘要信息中心,包括智能体延迟时间、智能体请求数和智能体错误率。
模型:查看智能体模型的指标信息中心,包括模型调用次数、模型错误率和模型 token 使用情况。
工具:查看智能体工具的指标信息中心,包括工具调用次数、工具错误率和工具延迟时间。
用量:查看智能体用量指标的信息中心,包括输入和输出的 token 用量、容器 CPU 分配和容器内存分配。
日志:如果您为代理启用了 Cloud Logging,则可以查看代理的日志。

紧急停止和撤销访问权限
当已部署的智能体出现异常行为、异常工具使用或涉及安全事件时,您可以通过终止或重新路由运行时实例,或通过 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 分钟或更长时间(请参阅访问权限更改传播)。 |
执行紧急停止
如需立即停止遭到入侵或行为异常的智能体,并防止其执行进一步的下游操作,请完成以下步骤:
- 停止活跃的运行时执行或隔离流量:
- 完全终止(终止开关):如需立即停止所有正在运行的容器并使智能体的 SPIFFE 身份失效,请使用 Google Cloud 控制台、Agent Platform SDK 中的
client.runtimes.delete(name="RESOURCE_NAME", force=True)或reasoningEngines.deleteREST 方法删除已部署的智能体。 - 在不删除代理的情况下回滚流量:如需在停止向故障修订版本发送流量的同时保留代理资源及其身份,请使用
trafficSplitManual更新代理,以将 100% 的根流量路由到已知良好的修订版本,或更新spec.deployment_spec.agent_gateway_config以归档预先存在的修订版本。如果调用方直接调用修订版本资源路径,请删除或归档该特定修订版本。如需查看相关说明,请参阅管理修订版本和流量。
- 完全终止(终止开关):如需立即停止所有正在运行的容器并使智能体的 SPIFFE 身份失效,请使用 Google Cloud 控制台、Agent Platform SDK 中的
- 撤销下游工具和资源访问权限:
- 如需通过 Agent Gateway 屏蔽出站工具和 MCP 服务器调用,请向绑定到网关的 UAP 添加一条针对智能体的
principal://或principalSet://标识符的DENY规则,并验证iamEnforcementMode是否设置为"ENFORCE"。如需查看相关说明,请参阅配置 IAM 政策以管理代理访问权限。 - 如需阻止直接 Google Cloud API 调用,请撤消授予代理身份或其自定义服务账号的 IAM 角色,或附加 IAM 拒绝政策或主账号访问边界政策。
- 如需通过 Agent Gateway 屏蔽出站工具和 MCP 服务器调用,请向绑定到网关的 UAP 添加一条针对智能体的
- 考虑传播窗口并验证控制效果:
- 当智能体正在执行非预期的工具调用时,请勿仅依赖 IAM 或 UAP 政策更新。政策更改需要 2 到 7 分钟(
principalSet更新需要更长时间)才能在全球范围内传播。请始终将政策撤消与运行时删除或修订版本流量重新路由搭配使用,以实现立即停止。 - 通过在 Cloud Logging 中查询
is_agentic=true和networkservices.googleapis.com/gateway_requests拒绝,确认代理活动已停止。如需详细了解日志注入和安全发现结果延迟时间,请参阅审核智能体操作和通过 Agent Gateway 监控流量。
- 当智能体正在执行非预期的工具调用时,请勿仅依赖 IAM 或 UAP 政策更新。政策更改需要 2 到 7 分钟(
删除已部署的代理
从 Agent Runtime 托管式运行时中删除已部署的智能体。删除 Agent Runtime 会使其 Agent Identity 失效。任何向该主体授予权限的 IAM Unified Access Policy (UAP) 都会在其规则中保留已失效的主体。此外,政策绑定仍处于有效状态。如需移除已失效的主账号,请更新 UAP,以从其规则中移除该主账号。如果政策不再包含任何有效主账号,请删除政策绑定。
控制台
- 在 Google Cloud 控制台中,前往 Agent Platform 部署页面。
对于您指定的代理,点击更多操作菜单 ()。
点击删除。
点击删除代理。
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 项目 IDLOCATION:支持的区域RESOURCE_ID:已部署代理的资源 ID
HTTP 方法和网址:
DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID
如需发送您的请求,请展开以下选项之一:
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。