KOX AgentCore 是我参与构建的最复杂的多 Agent 系统——5 个角色（策划、脚本、视觉、剪辑、审核）组成的视频生产流水线，共注册 54 个工具，单日峰值产出 200+ 短视频。在这个过程中踩过的坑超过 101 个，每一个都记录在内部的 Pitfall Registry 里。这里分享最致命的三类。

第一类：编排器的状态管理。我们最初使用 AWS Multi-Agent Orchestrator（Swarm）来协调 Agent 间的通信。它在 demo 场景下表现完美，但在生产负载下暴露了严重的状态同步问题——当「脚本 Agent」和「视觉 Agent」同时请求修改同一个项目状态时，缺乏事务机制导致状态覆盖。最终我们自研了 StreamingOrchestrator，引入了乐观锁 + 事件溯源的状态管理模式。

第二类：工具定义的膨胀。54 个工具听起来很强大，但每个工具的 JSON Schema 定义会占用上下文窗口。当所有工具定义加起来超过 8K tokens 时，Agent 的工具选择准确率开始下降——它被太多选项淹没了。解决方案是动态工具注入：根据当前角色和任务阶段，只加载相关的工具子集（通常 8-12 个）。第三类：流水线的错误传播。一个 Agent 的幻觉输出会成为下一个 Agent 的事实输入。我们在每个交接点增加了结构化验证层，用 JSON Schema 校验 Agent 输出的结构完整性，用规则引擎检查业务逻辑一致性。这三类问题消耗了项目 60% 的调试时间。