商品原价 39 元。店长让 Agent 改成 29 元,看到审批通过后关掉了页面。过了一会儿,他重新打开对话,问了一句:“刚才那笔改好了没有?”
如果客户端为了回答这句话,调用的是“恢复执行”,那笔改价可能就在这次刷新时首次提交。店长以为自己在看进度,客户端却推进了一笔业务操作。
再换一个时序。改价请求已经发出,客户端等到超时。业务有可能已经改成了 29 元,只是响应没有回来。此时重新创建一笔改价,除了可能再次写入,还可能重复触发改价通知、审计记录或后续流程。
这两个场景使用的是同一个合成商品,但系统面对的问题不同。前一个要确认批准后是否派发,后一个要核对派发后的业务结果。客户端超时只能说明它没有及时拿到响应。HTTP 语义也对自动重试非幂等请求设了明确条件,包括已知请求实际具备幂等语义,或能够确定原请求从未应用。 RFC 9110 §9.2.2
打开进度页时,只读取原记录
百灵中枢 v0.10.1 把这两项操作做成了不同入口。接入时先用当前 Agent Session 请求 GET /agent-api/v1/tool-invocations/inspection-capabilities。确认支持回执契约后,用原调用标识读取。
GET /agent-api/v1/tool-invocations/<原调用ID>/receipt
Authorization: Bearer <原Agent会话访问令牌>
原调用 ID 是 64 位小写十六进制字符串。查询只接受这个 ID,业务参数保留在原调用中。若部署版本未提供该能力,页面应显示无法查询或引导通过受授权的渠道核对原记录。旧版兼容时,尤其要避免把 resume 塞进定时轮询。 原调用回执契约
如果改价已批准但尚未派发,返回的几个字段可以长这样。这里摘取用于界面展示的字段:
{
"read_only": true,
"business_operation_performed": false,
"result": {
"state": "awaiting_approval" },
"approval": {
"status": "approved", "approval_id": 1 },
"dispatch_state": "not_dispatched",
"journal_state": "absent",
"result_source": "job"
}
result.state 来自原调用此前保存的结果,approval.status 则反映当前审批记录。两者出现在同一份响应里,界面可以显示“已批准,尚未发送”。若只拿一个状态画进度条,要么会把历史的“等待审批”显示给已经批准的店长,要么把“批准”误显示成“改价完成”。
business_operation_performed: false 只描述本次查询。即使原操作已经完成,查回执仍可以返回这个值。判断原调用走到哪里,要合看审批、派发、执行日志和结果。 回执字段说明
能看历史记录,和能继续执行,是两次权限判断
进度页应当能回答原任务发生过什么。回执实现会验证原会话、客户端、业务主体及调用关联,也会检查当前是否仍有访问对应路由和工具的权限。如果只是能力声明版本发生了变化,而访问条件仍满足,原来的执行记录可以继续读取。
用户明确点“继续执行”时,客户端才发出另一条请求。
POST /agent-api/v1/tool-invocations/<原调用ID>/resume
Authorization: Bearer <原Agent会话访问令牌>
Content-Type: application/json
{}
恢复入口会找回原调用,核对会话、客户端和当前路由,再根据已保存的结果决定返回历史结果还是进入后续执行。需要实际恢复时,会重新检查工具的执行条件,沿用原参数与调用关联。已批准而尚未发送的动作,在条件满足时可以从这里首次派发。若调用已完成并有稳定结果,恢复可以直接返回该结果。
这也是为什么不应在 “GET 失败就 POST” 的通用兜底里恢复任务。用户切了账号、原授权撤销、当前工具配置不再允许时,应用应保留原任务并显示明确状态。若用户确实希望另一个账号办理,需要按新的授权关系,由业务确认原操作结果后再决定后续动作。 回执实现 · 恢复实现
页面能从回执知道什么
| 看到的组合 | 页面可以怎样解释 | 下一步 |
|---|---|---|
已批准,not_dispatched |
观察时已有批准记录,现有证据表明原调用尚未派发 | 保持只读展示,由明确的继续动作触发恢复,并接受服务端再次判定 |
attempted,结果为 reconciliation_required |
有派发尝试或相应记录,业务结果尚不能确认 | 保留原 ID,核对业务方的操作记录,暂停自动重放 |
completed 日志有可验证的结果 |
中枢记录了原调用的已完成结果 | 展示原结果。若需核实当前价格,另查业务系统 |
| 原记录找不到或当前无权查看 | 本次查询没有取得可用的原记录 | 保留标识,提示核对原任务或权限 |
特别要留意 attempted。中枢可能在请求出站前先持久化尝试标记。因此,看到它可以知道“不能再按尚未发送来处理”,仍需从目标系统判断请求是否到达、是否落库。反过来,看到 not_dispatched 也只是当时的观察。下一秒,另一位操作者可能已经继续了任务。
当前价格和原操作回执也回答不同的问题。某次成功回执写着 29 元,后来店长又调到 35 元,两份记录都可能正确。核对原操作应优先按业务操作编号或业务流水查询,仅比较商品此刻的价格容易把其他人的改动算进来。 回执观察边界
用公开测试看执行次数
我从 v0.10.1 的固定提交导出源码,按锁文件安装依赖,在源码根目录重跑工具调用和 HTTP 路由两个公开测试文件。含子测试共 58 项,全部通过。应用层有 8 组专门的回执测试,另有 1 组 HTTP 回执测试。
node --import tsx --test src/app/agent-tool-invocations.test.ts src/routes/agent-api.test.ts
| 公开测试场景 | 断言 |
|---|---|
| 已批准的原调用连续检查两次 | 两次均显示尚未派发,审批未消耗,原调用证据保持不变 |
| 原调用按允许的条件继续执行 | 审批前调用计数为 0,合法恢复后为 1,再恢复已完成调用仍为 1 |
| 日志仍未确认结果 | 回执显示待核对,保持原记录,不新增派发 |
| 中枢暂停执行时从 HTTP 读取回执 | 原会话仍可读取,返回 Cache-Control: no-store,原调用记录保持不变 |
这些测试用本地测试替身观测派发和记录,能验证两个接口在给定条件下的行为。要验证真实门店改价是否落库,仍需检查业务系统的数据与流水。测试代码可直接对照。 调用与回执测试 · HTTP 边界测试
回到一次受委托的业务行动
在 A2B 的场景里,店长提出目标、同意具体改价、中枢派发调用、业务系统写入价格,这几步都可能分别成功或失败。记录把它们分开,店长回来时才能知道该看进度、继续原操作,还是先核对业务结果。
ACC 可以描述改价能力的主体、审批和执行要求。百灵中枢根据声明和运行时权限约束调用,保留原调用的审批与执行证据。订单、价格或库存最终是否改变,由对应业务系统的持久化结果说明。 ACC 规范
落实到界面,只需从一个明确的交互开始。重新打开对话时给出“查看结果”,在结果可恢复且授权条件满足时提供“继续原操作”。超时信息可以同时显示原调用 ID 和可核对的业务记录入口,让店长知道下一次点击会发生什么。