先划线:哪些工具能写

把工具按副作用分三档:只读(查询、列目录)、可逆写(改草稿、加标签、建临时资源)、不可逆写(发消息、扣款、删数据、对外提交)。分档不是为了好看,而是决定后面要加几道闸:只读不需要审批,可逆写要审计,不可逆写必须审批加补偿。

分类要写进工具定义本身,别只写在文档里。工具注册时带一个 sideEffect 字段,网关按这个字段决定是否走审批,避免新增工具时忘了配置。

审批:把「谁点的头」记下来

审批不是弹一个「是否继续」。要记四样东西:谁发起的、哪个 agent 会话、完整参数、这次调用对应哪条业务单据。人工确认后生成一张短期有效的批准票据,票据绑定参数哈希——参数改一个字,票据作废,必须重新批。

{
  "tool": "crm.update_contact",
  "argsHash": "sha256:9f2c...",
  "approvedBy": "user:alice",
  "sessionId": "sess_7f31",
  "expiresAt": "2026-11-09T06:30:00Z"
}

票据有效期给短一点,几分钟足够。审批通过后仍然要在服务端再校验一次权限与参数,不能因为「人批过了」就跳过业务校验。

幂等:重试不该产生第二笔

agent 遇到超时会重试,网络抖动也会重试。写接口要接受客户端传入的幂等键,服务端把「键 → 首次执行结果」存一段时间,重复请求直接返回第一次的结果,而不是再执行一遍。键由调用方生成,不要用时间戳或自增 ID。

def create_refund(idem_key, order_id, amount):
    hit = store.get(idem_key)
    if hit:
        return hit
    result = payments.refund(order_id, amount)
    store.put(idem_key, result, ttl=86400)
    return result

幂等键的写入要和业务操作在同一个事务边界里,或者先占位再执行。否则两个并发请求会同时查不到记录,各退一次。

审计与回滚:留证据,也留退路

审计日志至少包含:时间、调用方、工具名、参数、结果、幂等键、审批票据 ID。参数里的敏感字段做脱敏,但要保留可关联的哈希。日志写进只追加的存储,别让它跟业务数据一起被改。

不可逆操作要准备补偿动作:发出去的消息撤回、创建的资源标记删除、对外提交走人工复核。补偿脚本本身也要幂等,并且能按审计日志里的一条记录单独重放。

  • 写操作默认关闭,按工具白名单逐个开。
  • 审批票据绑定参数哈希,参数变更即失效。
  • 幂等键由调用方生成,服务端保留至少 24 小时。
  • 审计日志只追加,敏感字段脱敏后保留哈希。
  • 每个不可逆操作配一个可单独重放的补偿脚本。