一、写在前面
Agent编排在Demo阶段看起来很简单：A节点做完做B节点，B节点做完做C节点。
但一旦进入生产环境，事情就变得复杂了——并发、超时、失败、重试、降级、可观测性……每一个环节都可能出问题。
这篇文章总结了Agent编排在生产环境中踩过的10个真实坑，以及对应的解决方案。
坑1：串行执行所有任务，效率极低
错误表现：
需要同时获取用户信息、订单记录、商品详情。开发者写成了：先查用户 → 拿到结果后再查订单 → 拿到结果后再查商品。三个任务是顺序执行的。
问题分析：
这三个任务之间没有依赖关系，完全可以并行执行。顺序执行的总耗时 = 任务1 + 任务2 + 任务3。
解决方案：
使用并行节点，将无依赖的任务同时执行。并行执行的总耗时 = max(任务1, 任务2, 任务3)。
坑2：没有设置超时，节点永远挂起
错误表现：
某个节点调用外部API，外部服务挂了，请求一直没有返回。整个工作流卡在这个节点上，直到超时（默认可能是几分钟甚至无限）。
问题分析：
外部服务不可靠。没有超时保护的节点，可能成为整个工作流的阻塞点。
解决方案：
- 每个节点设置合理的超时时间（如30秒、60秒）
- 超时后进入异常处理分支，而不是无限等待
- 超时阈值根据节点特性设置（调用LLM可设长一些，调用内部API设短一些）
坑3：忽略重试机制，瞬时错误直接失败
错误表现：
网络抖动、限流、服务瞬时不稳，这些本可以自动恢复的错误，因为没有重试机制直接导致节点失败，整个工作流中断。
问题分析：
生产环境中的失败很多是瞬时性的，自动重试可以解决大部分。
解决方案：
- 为节点配置自动重试策略（如最多3次，间隔1秒、2秒、4秒）
- 区分可重试错误（限流、超时、网络）和不可重试错误（参数错误、权限不足）
- 重试次数过多时触发告警
坑4：条件分支缺失默认兜底
错误表现：
分支条件写了：如果是A类问题走分支A，B类问题走分支B。结果来了一个C类问题，没有匹配到任何分支，工作流直接中断。
问题分析：
基于枚举值的分支，天然存在“枚举不全”的风险。业务变化后可能新增类型。
解决方案：
- 每个条件节点增加“默认/兜底”分支
- 兜底分支可以走人工处理或记录异常并降级
- 兜底触发时记录日志，便于发现枚举遗漏
坑5：上下文越传越大，Token爆炸
错误表现：
节点A的输出传给节点B，节点B把自己的输出也追加到上下文中，节点C再追加……处理10个节点后，上下文里塞了几万Token。
问题分析：
链式传递导致上下文不断膨胀。后续节点可能不需要前面的全部信息。
解决方案：
- 明确每个节点需要的上下文范围
- 设置上下文最大长度（如64K），超限时截断或摘要
- 关键信息提取后传给下游，而非原始数据
坑6：没有熔断，雪崩效应
错误表现：
下游模型服务开始变慢，请求积压。上游还在持续发起新请求，导致整个系统响应越来越慢，最终全部超时。
问题分析：
没有熔断机制时，一个服务的故障会级联放大，拖垮整个系统。
解决方案：
- 设置熔断阈值（如连续失败5次或错误率超50%）
- 熔断后快速失败，不再发请求到下游
- 熔断半开后逐步恢复，验证下游已正常
坑7：节点粒度太粗，难以复用
错误表现：
一个节点做了太多事情：调用LLM、解析结果、调用API、写数据库。功能耦合在一起，其他场景想复用其中一部分都做不到。
问题分析：
节点粒度是设计问题，不是技术问题。粗粒度节点灵活性和复用性都差。
解决方案：
- 每个节点只做一件事
- 节点按能力类型拆分：LLM调用节点、数据查询节点、结果解析节点、存储节点
- 细粒度节点可以组装成复杂工作流，也可以单独使用
坑8：并发资源不加控制，打爆服务
错误表现：
并行节点同时调用了20个LLM请求，每个请求消耗大量显存和GPU资源，导致模型服务OOM或响应极慢。
问题分析：
并行是好事，但并行度需要控制。资源是有限的。
解决方案：
- 设置并行节点的最大并发数（如最多5个同时执行）
- 使用队列缓冲超出并发限制的请求
- 对高成本节点（如LLM调用）单独设置限流
在具体实现上，有企业采用 ZGI 作为Agent编排平台，其内置的并发控制和资源管理能力覆盖了上述设计。
坑9：错误处理分支缺失，失败后无法恢复
错误表现：
正常流程写得很完整，但一旦某个节点失败，没有定义“失败了怎么办”。工作流直接中断，需要人工介入才能恢复。
问题分析：
生产环境的失败是必然的。没有错误处理的设计，是不完整的设计。
解决方案：
- 每个可能失败的节点都配置异常分支
- 异常处理动作：重试、降级、跳过、人工介入
- 关键节点失败时发送告警通知
坑10：没有可观测性，出问题无从查起
错误表现：
工作流执行失败了，只知道“失败了”。不知道哪个节点失败的、输入是什么、错误是什么、耗时多久。
问题分析：
Agent编排是一个多节点、多分支的复杂执行过程。没有可观测性，就像在黑盒里调试。
解决方案：
- 每个节点记录：开始时间、结束时间、输入、输出、错误信息
- 全链路追踪：一次工作流执行生成唯一Trace ID，贯穿所有节点
- 可视化执行日志，支持按Trace ID检索和回放
二、避坑总结
| 常见错误 | 解决方案 |
|---|---|
| 串行执行 | 无依赖任务改为并行 |
| 无超时 | 每个节点设置超时+异常分支 |
| 无视重试 | 配置自动重试策略 |
| 分支无兜底 | 增加默认分支 |
| 上下文膨胀 | 截断或摘要，控制长度 |
| 无熔断 | 配置熔断阈值和恢复策略 |
| 节点粒度过粗 | 按能力拆分为细粒度节点 |
| 并发无控制 | 设置最大并发数+队列 |
| 无错误处理 | 每个节点配置异常分支 |
| 无可观测性 | 全链路追踪+日志记录 |
本文基于Agent编排生产环境实践整理。
