咱们做开发的都知道单线程没问题的地方并发一上准出事。Agent 也一样。这两天万能 AI 盒里出了个 BUG排查过程挺有意思是一个教科书级的并发问题——只不过并发线程换成了并行的工具调用。把这个坑记下来给正在做 Agent 应用的老铁提个醒。现象一个工单三条记录用户提交了一条售后工单Agent 判断需要同时做三件事创建工单、给负责人发通知、写入日志。从 Agent 的视角看这是三个独立操作它并行发起了三个工具调用——这在技术上完全正确还能省时间。然后数据库里出现了三条一模一样的工单。用户收到了三次通知。排查五分钟定位但汗流浃背了第一反应是创建工单这个工具被调了三次看日志——不是三次调用参数完全相同。再想明白了Agent 的规划器把创建工单这个动作放了三次——一次在主任务里两次在两个子任务的上下文里。并行执行时谁也不知道谁的存在。这暴露了两个层面的坑坑一工具的无副作用声明是谎言我们的工具描述里写着创建售后工单。在 Agent 的理解里这跟查询工单列表没区别——都是操作。它不知道创建这个词意味着调三次就有三条。人类开发者看到 createOrder 和 listOrders 会本能地分化对待但模型只看描述文本。副作用信息不在描述里对 Agent 就不存在。坑二并行调用之间没有隔离机制传统服务里我们防这种事靠的是幂等键、分布式锁、唯一索引。但 Agent 的工具调用层如果只是裸包了一层 API这些防线一个都没带上去。解法三道锁一层都不能少第一道工具描述里写明副作用与幂等约定改前创建售后工单传入用户ID和问题描述改后创建售后工单⚠️写操作有副作用。同一请求上下文内只允许调用一次幂等键 idempotency_key 必传重复提交返回原工单号第二道服务端幂等键兜底工具对应的 API 加幂等逻辑相同 key 的请求 10 分钟内返回首次结果。这是老手艺了但做 Agent 工具封装时特别容易忘——因为包一层就行的心态。第三道规划器层加写操作互斥在 Agent 的任务规划器里加规则同一批次并行调用中写操作create/update/delete/submit 类最多出现一次需要多个写操作时改为串行确认。第三道是我们最后加的也是最有效的——前两道防的是重复的相同调用这道防的是重复的等价调用参数不同但语义重复。顺手整理的 Agent 工具设计检查单这轮踩坑后我把工具设计规范重新整理了一遍核心就四条1.写操作必须在描述里显式标注副作用——有副作用不可重入需幂等键字越少越要写2.所有写操作工具幂等键服务端强制校验——不依赖 Agent 自觉3.并行批次内写操作互斥——规划器层面控制别等数据库报错4.危险操作加确认步骤——删除、支付、对外发送类工具描述里写明执行前需用户确认让 Agent 学会先问再做结尾这个 BUG 表面上是Agent 不懂事本质是我们把给人用的 API直接丢给了 Agent而人有的常识创建类操作不能乱点Agent 没有。工具描述就是 Agent 的世界说明书。说明书里没写的规矩它真的不知道。上回聊了怎么让 Agent 选对工具写清边界这回补上了选对了也不能瞎调幂等与互斥。凑齐了工具治理的另一半拼图。下回咱们聊 Agent 的记忆设计——多轮对话里哪些该记住、哪些该扔这又是一个上下文预算的精细活。感兴趣的老铁蹲一下。