先划线:哪些工具能写
把工具按副作用分三档:只读(查询、列目录)、可逆写(改草稿、加标签、建临时资源)、不可逆写(发消息、扣款、删数据、对外提交)。分档不是为了好看,而是决定后面要加几道闸:只读不需要审批,可逆写要审计,不可逆写必须审批加补偿。
分类要写进工具定义本身,别只写在文档里。工具注册时带一个 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 小时。
- 审计日志只追加,敏感字段脱敏后保留哈希。
- 每个不可逆操作配一个可单独重放的补偿脚本。