Skip to content

动作审批与降级 ​

适用范围:当前托管生产使用组织工作区。个人工作区及其所有者自审需等待控制面升级;自部署实例请按实际版本与身份配置判断。

策略格式 v2 为「不该直接放行、也不该直接拒绝」的调用加了两种规则效果:

  • require_approval(需审批):调用先停住,等具名审核员批准,然后可以执行一次,参数必须和批准时完全一样。
  • degrade(降级):原工具不执行,改为执行你们注册的、范围更窄的替代工具。

两者都只在强制执行模式下生效。只观察和建议模式下,它们记为「放行并告警」。无论哪种,原工具都不会在没有判定的情况下执行。

适用范围

动作审批只覆盖经过 SDK 和 MCP 代理的工具调用。这两条路径以外的 shell 命令、文件和网络访问,由你们的隔离层放行或阻断,审批票据打不开它们。

开始之前 ​

  • 策略是格式 v2(schema_version: guard.policy.v2),并且是强制执行模式。
  • 所有活跃的执行器都支持格式 v2。向导安装的 SDK 都支持。
  • 需审批规则可能命中的每次调用都带可信主体,即这次调用是替哪个最终用户做的:guard_run(subject_id=...) 或适配器的 resolve。没有可信主体的调用直接拒绝(APPROVAL_SUBJECT_REQUIRED),不会进入审批队列。
  • 已经指定了审核员。所有者在「成员」页分配审核员角色和每个审核员的可信主体。

审批的过程 ​

  1. Agent 提出一次命中需审批规则的调用。SDK 向控制面申请一张票据,工具不执行。票据绑定项目、Agent、可信主体、工具、这次动作的 SHA-256 摘要、规则和策略版本,只带一段简短的脱敏预览,不带原始参数。有效期一小时。
  2. 你们的代码拿到票据 ID。用框架适配器时,模型也会看到它。
  3. 审核员在控制台打开「审批」,核对预览和绑定信息,点「批准一次执行」或「拒绝」。
  4. 你们的应用恢复执行。SDK 消费这张票据(只能消费一次),按批准时的参数执行工具。

控制面会强制检查:

  • 审核员不能批准可信主体是自己的动作。
  • 所有者不能代替审核员批准动作。审核员和管理员可以。
  • 后续个人工作区版本允许所有者审批 Agent 的动作,可信主体是所有者本人的动作仍拒绝;当前托管生产未启用这个例外。
  • 参数改了、策略变了、重复使用已用过的票据、票据过期,都会被拒绝(APPROVAL_NOT_CONSUMABLE)。申请票据时策略刚好更新了,原因是 POLICY_CHANGED,SDK 随即刷新策略。
  • 决定之前同一个动作再次提出,拿到的是同一张票据,不会重开。

在 Python 里恢复执行 ​

自己包装的函数加上 pending=True,SDK 会在本地私下保存一份参数快照,之后(包括进程重启后)可以恢复执行:

python
from preworld_guard import GuardApprovalRequired, guard_run

@guard.tool('finance.submit', pending=True)
def submit(payload):
    return trusted_business_api.submit(payload)

with guard_run(subject_id=trusted_employee_id):
    try:
        submit({'amount': 4200})
    except GuardApprovalRequired as pending:
        ticket_id = pending.ticket_id

# 在审核员批准后由应用显式恢复;不要让模型修改原参数。
if guard.pending.status(ticket_id)['status'] == 'approved':
    result = guard.pending.resume(ticket_id)

快照存在策略缓存旁边的 pending.sqlite3 里,只有进程所属用户可读,只保存标了 pending=True 的工具的参数。这个目录要放在受保护或加密的存储上。

其他恢复方式:

方式什么时候用
with guard_approval(ticket_id):你们自己再调一次受保护的入口。第一次匹配的调用消费票据,之后再用都会失败
with guard_resume(ticket_id):让框架里的 Agent 再跑一遍。模型再次提出同一个调用时,适配器消费一次票据;作用域里的其他调用照常判定
auto_resume_approved=TrueOpenAI Agents、Claude Agent SDK、Microsoft Agent Framework、LlamaIndex、Agno、DSPy、CrewAI 的适配器:已批准的票据不用 guard_resume 也会被消费
Pydantic AI 自带的延后机制Pydantic AI 的默认方式,见框架适配器

guard.approval_status(ticket_id) 返回 pending、approved、rejected、consumed、canceled、expired 或 policy_changed。guard.cancel_approval(ticket_id) 撤回一张票据。

执行到一半出了问题 ​

SDK 在消费票据之前,先把「准备执行」持久记下来。之后如果进程崩溃、连接断开或任务被取消,快照停在 executing 或 uncertain,不会自动重放。你们要自己核对业务结果,需要的话重新申请审批。对外部系统,Guard 无法保证恰好执行一次:给写操作的工具加幂等键,并做对账。

经过 MCP 代理的审批 ​

代理把待审批作为错误结果返回(isError: true),文本里有 status: approval_required、票据、有效期和策略版本,结果的 _meta["com.preworld.guard/approval-id"] 里也有同一张票据。批准之后,客户端用同样的工具名和参数重试,并在请求的 _meta 里带上票据:

python
result = await session.call_tool("finance__transfer", {"account_id": "demo-42", "amount": 1})
ticket = result.meta["com.preworld.guard/approval-id"]
# 等待独立审批员批准后,保留原始工具名与参数:
result = await session.call_tool("finance__transfer", {"account_id": "demo-42", "amount": 1},
                                 meta={"com.preworld.guard/approval-id": ticket})

启动代理时加 --subject-id agent-service-1(或设 PREWORLD_GUARD_SUBJECT_ID),把它的请求绑定到一个可信的服务主体。这是整个进程共用的服务身份,不代表最终用户。多人共用一个下游令牌的代理分不出是谁。没设主体时,需要审批的调用一律拒绝。重试时传不了 _meta 的 MCP 客户端,只会一直看到待审批的错误。

降级 ​

降级规则指定一个替代工具:

yaml
schema_version: guard.policy.v2
policy_id: support-v2
mode: enforce
default_effect: deny
rules:
  - rule_id: crm-read
    effect: allow
    risk: normal
    match: {resource: crm.read}
  - rule_id: crm-delete
    effect: deny
    match: {resource: crm.delete}
  - rule_id: transfer-approval
    effect: require_approval
    match: {resource: payments.transfer}
  - rule_id: export-degrade
    effect: degrade
    fallback_resource: report.export_summary
    match: {resource: report.export_full}
  - rule_id: export-summary
    effect: allow
    risk: normal
    match: {resource: report.export_summary}
  • 在 Agent 进程里注册替代工具:guard.register_fallback(resource, function, map_arguments=...)。map_arguments 把原参数转换成替代工具的参数。
  • 替代工具单独判定一次,必须被策略明确放行(上面的 export-summary 规则),否则拒绝(FALLBACK_NOT_ALLOWED)。
  • 没注册替代工具,或者它在当前路径上跑不了(比如同步工具配了异步的替代函数),这次调用拒绝(FALLBACK_UNAVAILABLE)。
  • Claude Agent SDK 的钩子不能替换工具的输出,所以那里的降级是拒绝这次调用,并在 fallback_resource 里写出替代工具,让模型改调它。
  • 经过 MCP 代理时,降级只在多上游注册表配置里可用,由配置把原工具映射到审查过的替代工具。单上游代理遇到降级直接拒绝。

只注册你们团队审查过、确认安全的替代工具,最好没有副作用。