1. 单 Agent 跑不动多 Agent 又乱成一锅粥问题出在哪先说一个我自己的翻车经历。去年我在一个内部工具里接了个需求给一批专利文献做辅助检索和摘要提炼。一开始想得挺简单——调一个大模型把文献喂进去让它边读边总结边分类。单 Agent 模式跑了两轮结果非常稳定地出现三个问题第一上下文一长就开始失忆读到第 20 篇文献时已经忘了第 1 篇的核心结论第二所有任务挤在一个上下文窗口里模型既要理解专利权利要求书又要做技术方案比对又要写摘要指令稍微长一点就开始角色混乱输出一会像审查员一会像销售文案第三只要某个中间环节一次调用超时或者格式解析失败整条流程全部重新跑成本和时间直接翻倍。后来我换了思路把任务拆开交给多个 Agent 协作完成。拆完之后效果立竿见影每个 Agent 只盯着一个职责上下文干净了角色不再漂移单点失败也能局部重试。但这又带来新的问题——Agent 一多谁先跑谁后跑、结果传给谁、出错了谁负责、怎么避免几个 Agent 互相说废话这些全成了配置层面的麻烦。那段时间我试过好几款编排框架最后在 HagiCode 上把整套流程稳定跑了下来。这篇博文不想跟你复述官方文档那个你自己看就行。我想说的是我在 HagiCode 上配置多 Agent 协作时实打实踩过的坑、验证过有效的配置思路、以及那些文档里不会写清楚的边界条件。适合谁看正在从单 Agent 往多 Agent 迁移、被协作流程搞到头大、以及想找一个能落地到生产环境的编排方案的开发者。如果你刚接触这个概念前两节帮你把基础拼图补上如果你已经在跑了第三节往后的排查和调优经验应该能直接救你于水火。2. 为什么 AI 冒险团需要分工而不是把活全塞给一个模型想理解 HagiCode 的多 Agent 配置先得搞清楚一个问题多 Agent 到底解决了什么单 Agent 解决不了的事2.1 单 Agent 的上下文瓶颈不是不够聪明而是一个人干三个人的活大模型的上下文窗口再大它也是一个线性的信息通道。你看小说可以反复翻回前面章节但模型在处理超长上下文时注意力会被稀释早期信息在生成后期内容时的权重会大幅下降。这不是提示词能完全弥补的是架构层面的物理限制。更现实的问题在于真实业务任务往往是混合型的。拿我那个专利文献辅助检索的需求举例完整链路是先判断这篇文献属于哪个技术领域然后提取关键技术特征再和现有专利权利要求做比对最后生成一份带风险提示的摘要。这里至少有四种不同类型的任务分类、抽取、比对、生成。让一个 Agent 全做它需要在系统提示词里同时装下四套指令、四套输出格式、四套判断标准。结果就是模型在切换任务时会产生角色残留——上一段还在做分类判断下一段特征提取时就会带上分类语境的口吻。2.2 多 Agent 协作的本质把上下文切成独立的工作间多 Agent 模型的好处不是用了很多模型所以更智能而是每个 Agent 拥有独立的上下文窗口各自维护一套干净的对话历史。负责技术特征提取的 Agent 不需要知道比对 Agent 中间经过了哪些推理步骤它只需要接收规范化的输入、输出规范化的结果。这就像一家公司不会让研发、法务、销售坐在同一张桌子上同时发言而是各干各的活通过固定格式的文档交接。HagiCode 里对这种交接的定义就是协作配置的核心。2.3 什么时候真正的需要多 Agent什么时候只是徒增复杂度我也见过不少人把简单任务硬拆成多 Agent结果延迟翻了几倍、token 消耗翻了几倍产出却没有变好。这里我给自己定了一个判断标准如果你的任务能用一个 500 字以内的系统提示词描述清楚且不需要多种完全不同类型的子任务那单 Agent 就是最优解。多 Agent 的收益要在满足下面任意一条时才会体现任务链路中存在多种截然不同的输出格式或判断逻辑单个 Agent 的上下文预算无法覆盖完整流程所需的历史信息流程中存在可以被并行处理、互不依赖的子任务某个环节失败时需要精准重试而不想重跑整个流程HagiCode 的价值在于它把上面这些判断变成了可视化的编排配置而不是靠你在代码里手动维护一堆 if-else 和消息队列。3. HagiCode 的多 Agent 协作模式三种拓扑结构怎么选HagiCode 的协作配置在我看来本质上是在回答三个问题Agent 之间以什么结构连接消息以什么格式流转任务由谁决策下一步围绕这三个问题我把它支持的模式归纳为三种拓扑实际项目里基本就是这三种的叠加。3.1 流水线模式上一棒跑完下一棒才接棒流水线模式最适合那种步骤前后依赖清晰、中间产物边界分明的任务。我搭的第一个 HagiCode 实验流程就是这种检索 Agent 查文献摘要 Agent 读文献比对 Agent 做差异分析报告 Agent 写总结。配置时的关键参数有三个参数作用我的推荐值context_passthrough是否把上游全部历史传给下游关闭只传结构化结果output_schema_validation是否校验上游输出字段开启严格模式retry_on_failure下游失败时的重试策略仅重试下游节点不回溯上游这里我强烈建议把context_passthrough关掉。很多人刚上手时会图省事让上游 Agent 把完整对话记录一股脑传给下游。这样做短期内跑得通但只要链路超过三个 Agenttoken 消耗会指数级上涨并且下游 Agent 会被大量无关上下文干扰。正确的做法是在上游 Agent 的输出配置里用output_schema严格声明一个结构化的 JSON 输出下游只接收这个 JSON。# 伪代码示意实际配置以 HagiCode 控制台 Schema 为准 output_schema: { type: object, properties: { doc_id: {type: string}, key_tech_features: {type: array, items: {type: string}}, risk_flags: {type: array, items: {type: string}} }, required: [doc_id, key_tech_features, risk_flags] }3.2 编排——路由模式一个调度者一群执行者当任务类型不固定需要根据内容动态决定走哪条分支时流水线模式就不够用了。比如我做 AI 短剧脚本生成工具时一个入口进来的用户需求可能是古风爱情也可能是科幻悬疑还有可能是都市喜剧。不同题材的剧本结构完全不同没有一个通用的流水线能覆盖所有情况。这种场景用 HagiCode 的编排模式更合适一个编排 Agent路由者负责读取用户输入判断题材类型然后把任务分发给对应的专业 Agent。专业 Agent 各自只维护一套系统提示词比如古风 Agent 只懂古风剧本的节奏和台词风格科幻 Agent 只懂世界观设定和硬科幻逻辑。配置编排模式时我最注意的是路由 Agent 的系统提示词。它不需要生成任何内容只需要做分类决策所以提示词里要明确写清楚你的职责是将用户请求分类并分发给正确的处理者不要尝试回答用户问题不要生成内容。只输出 JSON格式为 {task_type: ..., task_args: {...}}。这里的关键是反复强调只输出 JSON、不要生成内容否则路由 Agent 经常会好心地把任务自己回答了导致专业 Agent 接到一个空壳任务。3.3 群聊/协商模式多 Agent 共同解决一个复杂的开放问题第三种模式是我觉得 HagiCode 最有趣的地方——允许 Agent 在同一个共享会话里互相讨论。配置上很像拉一个群把多个 Agent 拉进同一个swarm_id它们能互相看到对方的消息可以在指定轮次内来回发言。这个模式我实际用得比较克制。它最适合的场景是问题没有唯一正确答案需要多个视角的碰撞来逼近一个更优解。比如我在做一个技术方案可行性评估流程时让架构 Agent、成本 Agent、安全 Agent 在同一会话里对某个技术选型发表意见互相质疑和补充。协商模式能明显提升结论的全面性但它也有三个很实际的坑token 消耗是按所有参与者的全部发言计算的几个 Agent 来回聊几轮一次任务的成本可能抵得上普通流水线的五到十倍需要约束发言轮次不限制的话会陷入无限讨论最后不了了之讨论结束时需要有一个总结 Agent 来收敛结论否则产出是一堆散乱的发言记录所以我在配置协商模式时一定会加一个max_rounds参数限制讨论轮数并且在参与者之外额外设置一个总结者 Agent它的系统提示词是你是一个总结者。阅读以上所有参与者的讨论输出一份包含一致观点、分歧点、最终建议的报告不要继续提出新观点。3.4 三种模式的选型对比评估维度流水线模式路由模式群聊/协商模式适用场景步骤明确、顺序固定的流程输入类型不固定、需要分支处理开放性问题、需多角度评估上下文管理难度低各节点边界清晰中需管理路由决策历史高所有参与者共享历史成本控制好较好差需要严控轮次失败重试粒度节点级分支级整体重试典型落地场景文档处理、数据提取分类客服、内容生成路由技术评审、方案选型4. 角色配置的灵魂系统提示词、结构化输出与失败降级很多人在 HagiCode 上配置 Agent 时把所有精力都放在拓扑结构上拓扑搭好了Agent 却表现得很蠢。这里我想说一个观点拓扑决定多 Agent 的骨架角色配置才是真正的灵魂。结构对了但角色定义模糊效果可能比单 Agent 更差。4.1 系统提示词的我是谁要写成可执行规范不要写成性格小传我看到很多人在配置 Agent 时写的系统提示词是这样的你是一位资深的专利分析师拥有丰富的知识产权经验能够准确分析专利文献。这种写法不是完全没用但它没有给模型明确的行为指令。你是资深专家然后呢你要怎么分析按什么步骤输出什么格式这些不说清楚模型就只能靠自由发挥。我自己的写法是把它拆成四个部分职责边界、处理步骤、输出格式、禁忌事项。以我配置的专利比对 Agent为例它的系统提示词核心部分是你是专利比对 Agent。职责将目标文献的技术特征与给定权利要求书进行逐项比对。 处理步骤 1. 读取 input.literature_context 中的技术特征 2. 读取 input.claims_context 中的权利要求 3. 逐项判断目标特征是否被权利要求覆盖输出覆盖、部分覆盖、未覆盖 输出格式严格 JSON{match_results:[{claim_id: ..., coverage: ..., evidence: ...}]} 禁忌不要输出任何 JSON 以外的解释文字不要自行扩大职责范围不要生成法律结论这里最重要的是处理步骤和输出格式。处理步骤把黑盒的模型推理拆成了可预期的子任务模型不容易遗漏环节输出格式则让结果可以被下游直接消费不需要再写一堆正则去猜它在说什么。我实际测试下来加了这两部分的 Agent输出可用率能从五成左右拉到九成以上。4.2 结构化输出HagiCode 配置中值回票价的字段output_schema是 HagiCode 里我觉得价值最高的字段。它相当于给 Agent 的输出装了一个格式约束器模型生成完内容后框架会按你定义的 JSON Schema 做校验不合法就触发一次修复重试。我在实际项目中的做法是所有 Agent 的输出都定义严格的 JSON Schema除了核心数据字段额外加一个error字段默认值为 null让 Agent 在遇到无法处理的情况时输出错误码而不是硬编一个结果required字段里只放绝对必要的字段不要把可选字段设为 required否则会因为一个小缺失反复触发重试、浪费 token注意output_schema配合 HagiCode 的strict_mode: true才能真正发挥威力。如果没开严格模式框架可能只是建议模型按格式输出模型偶尔还是会给你夹带一些 Markdown 代码块标记或者解释性文字。4.3 失败降级的兜底设计没有 panic只有 fallback多 Agent 协作里单点失败是常态而不是意外。HagiCode 配置里有两类失败需要分别处理一类是模型调用失败超时、限流另一类是业务层失败Agent 认为输入不合法、结果校验不通过。模型调用失败我的配置经验是设置重试三次、退避时间从 2 秒起指数增长超过三次就把该节点的输出标记为失败并触发降级路径。降级路径是什么不要让它直接轰炸用户日志而是让它把失败信息发送到一个兜底 Agent或一个固定格式的失败队列里。比如我在短剧工具里如果分镜 Agent失败了降级路径不是让整个流程挂掉而是触发一个简版分镜 Agent只做最简单的景别拆分优先保证后续流程能继续走。业务层失败的兜底也类似。我见过不少人的 Agent 在被问到一个超出职责范围的问题时会开始一本正经地胡说八道编一个结果出来。这是个风险很大的行为。所以我让每个 Agent 在遇到无法处理的情况时输出{error: OUT_OF_SCOPE, reason: ...}然后由编排层把该错误转给一个澄清 Agent让它礼貌地要求用户或上游补充信息。这套设计解决了一个很普遍的问题Agent 太爱面子不懂装懂。5. 上下文管理与记忆共享配置不好Agent 之间的消息传递会炸多 Agent 一旦跑起来最让人头疼的是上下文管理。每个 Agent 有独立的上下文是一回事怎么共享和传递信息又是另一回事。HagiCode 在这块提供了一些配置项但很多默认行为藏着坑。5.1 内存隔离还是共享不要图省事什么都传我在第 3 节里反复强调关掉context_passthrough但这不是说所有共享都不要了。实际场景里有些信息是必须全局共享的比如任务背景、用户原始需求、品牌约束。正确的配置思路是区分全局元信息和节点中间结果。我习惯在每个 Agent 的输入配置里留一个global_context字段放置所有节点都需要的基础信息比如目标受众、语气要求、使用场景。这部分信息量小但是通用可以传给每个节点。至于检索 Agent 搜到了哪些文献摘要 Agent 生成了什么摘要这类中间结果就必须走output_schema在上下游之间显式传递不要让下游 Agent 去看上游 Agent 的完整聊天记录去自己找重点。5.2 记忆机制短期窗口、摘要压缩、长期存储三层配置HagiCode 对会话历史的默认处理方式如果我没理解错是保留最近若干轮加一个摘要。这个机制在单 Agent 场景还好多 Agent 协作时很容易出现问题——某个子任务对话长了摘要压缩策略会把一些对下游重要的细节细节掉。我自己的做法是把 Agent 的交互拆得更碎不要让一个 Agent 在一个会话里做二十轮长对话而是设计成一次调用一个任务的工作模式每次任务完成后把关键结果写入一个可访问的存储比如 Redis 或数据库并清空短期窗口。以 检索 Agent 为例它收到一批关键词做一轮检索输出几条链接和摘要任务就结束了。整个会话的长度被限制得很短根本不需要复杂的记忆压缩。对于确实需要长期记忆的 Agent比如用户偏好 Agent要记住用户在多个项目中的风格偏好我的配置建议是启用 HagiCode 的长期存储把结构化偏好信息写进记录在每次任务开始时重新加载而不是靠模型的上下文去回忆。模型的上下文是流动的写进存储才是固定资产。这就像你记性再好也不如把会议纪要落在文档里靠谱。5.3 消息格式的一致性Agent 之间说的话要对齐多 Agent 协作容易忽略的细节是消息格式的一致性。上游 Agent 输出的字段叫doc_id下游 Agent 的输入 Schema 里写的却是document_id这种不一致会让下游校验直接失败。所以我在配置 HagiCode 时会维护一份共享的消息协议文档所有 Agent 的output_schema和input_schema都从这份协议里复制字段名绝不手写两遍。字段命名规范我推荐统一用snake_case字段语义要明确到不依赖上下文也能理解。比如content这种字段就过于模糊我倾向于用brief_summary、detailed_analysis、risk_flags这种自解释的名字。字段名模糊是配置阶段埋下的雷后面排查的时候会非常痛苦——你根本分不清某个 Agent 报错是因为上游没传值还是字段名不一致。6. 从 0 到 1 实战一个 HagiCode 多 Agent 协作配置的完整过程理论说了不少接下来我拆一个我搭建过的具体案例——AI 辅助专利检索与风险分析工作流从需求拆解到配置落地的完整链路。这个案例几乎涵盖了前面提到的所有知识点。6.1 需求拆解与角色分配需求是这样的输入一篇目标专利的摘要和权利要求系统自动去文献库检索相关在先技术然后做相似度分析判断目标专利的新颖性风险最后生成一份风险评估报告。我把这条需求拆成了五个 AgentAgent 名称职责输入输出特征提取 Agent从目标专利中提取关键技术特征专利摘要、权利要求结构化的技术特征列表检索 Agent根据技术特征构建检索式检索相关文献技术特征列表原始检索结果标题、摘要、链接文献筛选 Agent从检索结果中筛掉无关文献原始检索结果高相关文献列表技术比对 Agent对比高相关文献与目标专利的技术特征目标特征高相关文献覆盖度与差异分析报告生成 Agent汇总所有结果生成风险报告比对结果原始请求结构化风险报告角色划分的原则很简单每个 Agent 只做一个类型的事。特征提取是抽取型任务检索是工具调用型任务筛选是相关性判断型任务比对比对型任务报告生成是生成型任务。五种任务差异巨大拆开之后每个 Agent 的系统提示词都很短模型执行起来也准。6.2 流水线配置与参数设置这个案例用的是流水线模式。链路是单向的每个节点的输出恰好是下一个节点的输入。配置时我在 HagiCode 上依次定义了五个节点每个节点要填的核心参数如下键名为 I 见过的一个 HagiCode 版本里的字段但建议你在自己的版本里确认一遍特征提取 Agent: context_passthrough: false model: default-chat-model output_schema: type: object properties: tech_features: type: array items: type: object properties: feature_id: { type: string } description: { type: string } required: [tech_features] fallback: 返回错误码并终止流程这里有一个很关键的配置技巧检索 Agent 的输入是技术特征列表而不是原始需求。这是多 Agent 协作里最容易理解错的地方——下游的输入永远应该是上游的结构化输出而不是最开始的用户输入。很多人配置时手指一抖把用户输入一路传到底这样每个 Agent 都要重新理解一遍需求前面分工就白拆了。6.3 关键调试经历字段没对齐导致的连环报错这个流程第一次跑的时候我栽了一个特别蠢的跟头。特征提取 Agent 输出的字段叫tech_features检索 Agent 的输入 Schema 我没仔细看默认模板里写的是features。结果每次跑到检索 Agent 就报校验失败。HagiCode 的错误日志里不会直接告诉你字段不匹配它只会显示输入校验失败缺少 features 字段。这种问题排查起来并不难但如果节点多一个一个点开看很浪费时间。我的经验是在正式跑全部流程之前先用一组最小的测试数据逐节点单独调用。每个 Agent 单独喂模拟输入看输出是否合法、字段名是否正确全部验证通过后再串联跑。这个习惯帮我省了非常多排错时间。很多新手直接把所有 Agent 串起来跑一报错就不知道该排查哪个环节最后只能一个一个加日志效率极低。6.4 成本与延迟的实测体验这套五节点流水线我实测下来的单次运行成本大约是单 Agent 直接做完整任务的三倍左右延迟大约是单 Agent 的两倍。为什么要强调这个因为多 Agent 协作不是免费的它拿成本和延迟换了稳定性和可维护性。指标单 Agent 直接生成五节点多 Agent 流水线单次 token 消耗约 8k约 24k平均耗时约 20 秒约 42 秒输出格式合法率约 60%约 95%单环节重试率整体重跑仅失败节点重跑可维护性Low改一处全换High改单个节点即可这么看多 Agent 并不是所有场景的银弹。但如果你的业务对输出稳定性要求高——比如下游还有别的系统在消费 Agent 的结果——那多出来的这份成本是完全划算的。格式合法率从六成到九成五的意义在于你再也不需要写一堆后处理代码去猜模型输出的含义了。7. 并发、重试与可观测性生产环境绕不开的三个话题多 Agent 协作从实验到生产最明显的跨越就是偶尔跑通到稳定跑通。这背后离不开并发配置、重试策略、日志追踪这三件大事。7.1 并发配置小心限流也别把资源全打满HagiCode 默认的并发策略我没仔细研究过但从实际使用经验看各节点如果配置不当很容易触发模型服务提供方的限流。我的建议是区分 I/O 密集节点和推理密集节点。检索 Agent 大部分时间花在调用外部搜索 API 上并发可以调得高一些比如 10-20比对 Agent 和报告生成 Agent 是推理密集型的并发过高会导致单次请求变慢并增加限流概率我通常设在 3-5。这里并发上限是多少合适取决你用的模型服务端限流策略。我个人的经验是一开始保守一点从 1 并发跑起逐步往上试观察到响应延迟明显抬升或者出现 429 报错的临界值就回头降一档。不要盲目追求高并发——多 Agent 场景下单任务已经比单 Agent 慢并发打高只会更快撞上模型服务的性能天花板。7.2 重试机制的配置细节区分可重试和不可重试重试不是无脑重跑。我在 HagiCode 里配置重试时会区分两类错误可重试错误上游请求超时、限流、网络抖动。这类错误重试有效因为再次调用大概率能成功不可重试错误输入数据格式非法、Agent 判断任务超出边界。这类错误重试一万次也一样应该直接走降级或失败分支我建议给每个节点配置retryable_error_types和non_retryable_error_types两个列表。如果框架不支持这种区分至少可以在配置重试条件时把超时和限流类错误设为可重试把校验类错误设为不重试。重试次数我一般设 2 到 3 次超过就触发 fallback。太多重试只是在烧钱。7.3 链路追踪不要让失败信息烂在日志里多 Agent 一次任务会涉及多个节点的多次调用一旦出错你需要在几分钟内定位到是哪个节点、哪次调用出了问题。HagiCode 是否内置了链路追踪不同版本不一样。但不管它内置与否我强烈建议你在自己的代码接入层里给每个任务生成一个trace_id从入口开始把 trace_id 传给每个节点让节点在输出和日志里都带上这个 ID。实际操作中我还喜欢在每次 Agent 调用前后打印结构化日志包含 token 消耗、耗时、返回状态的摘要。这些数据看着不起眼但在你需要诊断为什么今天任务成功率从 95% 掉到 80%的时候是唯一可靠的依据。没有日志你只能靠猜。8. 一个需要反复校准的选项协商模式下如何让人工 Agent 真正协作而不互怼前面聊的主要是流水线和路由模式最后我想单独来说说协商模式因为这是 HagiCode 这类编排工具最吸引人、也最容易翻车的玩法。8.1 为什么协商模式容易变成礼貌的废话生成器我把几个 Agent 拉进同一个会话后第一个版本跑出来的结果简直没法看。架构 Agent 说考虑到系统的可扩展性我建议采用微服务架构成本 Agent 说微服务架构可能带来额外的运维成本我建议综合考虑安全 Agent 说无论采用什么架构安全性都应该放在首位考虑。三轮讨论结束除了三句正确的废话什么都没达成。问题出在角色配置上。协商模式下的每个 Agent 都太全面了它们都能看到别人的发言但它们的系统提示词里没有定义你要基于什么立场、代表什么利益说话。没有立场就没有碰撞没有碰撞就产生不了信息增量。8.2 如何给协商 Agent 增加立场约束我的改进思路是在协商模式的系统提示词里给每个 Agent 增加一个立场声明字段。架构 Agent 的立场是你是架构决策的主导者你的目标是选出一个可长期演进的架构方案。你可以承认其他维度的担忧但不要把决策权让渡给成本或安全维度。如果要调整方案你需要说明架构上的收益。成本 Agent 的立场则是你的唯一目标是控制成本。你需要对每个提议的成本影响做出量化估算如果提议方无法给出成本合理性说明你有权要求补充。这样调完之后互怼就变得有信息量了架构 Agent 会提出具体的微服务拆分方案成本 Agent 会算出基础设施开销和人力成本安全 Agent 会点出认证与数据隔离的具体风险。整个讨论从礼貌地各说各话变成了有立场的交锋。这才是协商模式应该有的样子。8.3 协商的收敛机制没有拍板人的会议永远开不完配置协商模式时一定要有会议主持人。这个人可以是编排层的代码逻辑也可以是一个专门的总结 Agent职责是在讨论到max_rounds时强制停止汇总发言输出最终结论。我通常把max_rounds设为 3 到 4 轮。轮数太少讨论不充分轮数太多边际收益很低大家开始车轱辘话来回说。我自己的体会是协商模式不要作为默认执行路径只把它用在没有标准答案、需要权衡多个维度的决策型任务上。如果一个问题已经有确定的执行流程走流水线就好速度和成本都友好得多。9. 配置清单照着抄就能避掉大部分坑最后我把这几轮实战中沉淀下来的配置清单列出来。这不是什么官方最佳实践纯粹是我自己踩坑踩出来的习惯但照着做至少能帮你少走一半弯路。除非确实需要全貌否则一律关闭context_passthrough让节点间通过结构化的output_schema传数据系统提示词按四个部分写职责边界、处理步骤、输出格式、禁忌事项别写成一个性格小传所有 Agent 的输入输出字段名统一定义维护一份消息协议文档不靠记忆模型调用失败区分可重试和不可重试可重试错误最多重试三次不可重试错误直接走降级每个 Agent 都要有一个无法处理时怎么办的兜底逻辑宁可输出错误码也不要编造结果跑完整流程之前先用最小测试数据逐节点单独验证再串起来跑并发数从低到高逐步试探找出稳定性与吞吐量的平衡点全局维护trace_id打印结构化日志否则生产环境出问题只能干瞪眼协商模式必须设定立场约束、轮数上限、总结者否则就是烧钱开会HagiCode 这套多 Agent 协作配置说到底玩的是边界感——Agent 与 Agent 之间的边界、上下文与上下文的边界、职责与职责的边界。边界划得越清楚整个系统越稳定。我曾经在单 Agent 模式下被各种上下文漂移和角色混乱折磨得够呛换到多 Agent 后只要配置规范了绝大多数情况下系统就像一条分工明确的流水线每个工种各司其职出了问题也能精准定位到工位上。如果你正在从单 Agent 向多 Agent 迁移希望这篇东西能帮你避开我踩过的那些坑早点跑通你自己的AI 冒险团。
多Agent协作不再乱：HagiCode配置实战与踩坑指南
1. 单 Agent 跑不动多 Agent 又乱成一锅粥问题出在哪先说一个我自己的翻车经历。去年我在一个内部工具里接了个需求给一批专利文献做辅助检索和摘要提炼。一开始想得挺简单——调一个大模型把文献喂进去让它边读边总结边分类。单 Agent 模式跑了两轮结果非常稳定地出现三个问题第一上下文一长就开始失忆读到第 20 篇文献时已经忘了第 1 篇的核心结论第二所有任务挤在一个上下文窗口里模型既要理解专利权利要求书又要做技术方案比对又要写摘要指令稍微长一点就开始角色混乱输出一会像审查员一会像销售文案第三只要某个中间环节一次调用超时或者格式解析失败整条流程全部重新跑成本和时间直接翻倍。后来我换了思路把任务拆开交给多个 Agent 协作完成。拆完之后效果立竿见影每个 Agent 只盯着一个职责上下文干净了角色不再漂移单点失败也能局部重试。但这又带来新的问题——Agent 一多谁先跑谁后跑、结果传给谁、出错了谁负责、怎么避免几个 Agent 互相说废话这些全成了配置层面的麻烦。那段时间我试过好几款编排框架最后在 HagiCode 上把整套流程稳定跑了下来。这篇博文不想跟你复述官方文档那个你自己看就行。我想说的是我在 HagiCode 上配置多 Agent 协作时实打实踩过的坑、验证过有效的配置思路、以及那些文档里不会写清楚的边界条件。适合谁看正在从单 Agent 往多 Agent 迁移、被协作流程搞到头大、以及想找一个能落地到生产环境的编排方案的开发者。如果你刚接触这个概念前两节帮你把基础拼图补上如果你已经在跑了第三节往后的排查和调优经验应该能直接救你于水火。2. 为什么 AI 冒险团需要分工而不是把活全塞给一个模型想理解 HagiCode 的多 Agent 配置先得搞清楚一个问题多 Agent 到底解决了什么单 Agent 解决不了的事2.1 单 Agent 的上下文瓶颈不是不够聪明而是一个人干三个人的活大模型的上下文窗口再大它也是一个线性的信息通道。你看小说可以反复翻回前面章节但模型在处理超长上下文时注意力会被稀释早期信息在生成后期内容时的权重会大幅下降。这不是提示词能完全弥补的是架构层面的物理限制。更现实的问题在于真实业务任务往往是混合型的。拿我那个专利文献辅助检索的需求举例完整链路是先判断这篇文献属于哪个技术领域然后提取关键技术特征再和现有专利权利要求做比对最后生成一份带风险提示的摘要。这里至少有四种不同类型的任务分类、抽取、比对、生成。让一个 Agent 全做它需要在系统提示词里同时装下四套指令、四套输出格式、四套判断标准。结果就是模型在切换任务时会产生角色残留——上一段还在做分类判断下一段特征提取时就会带上分类语境的口吻。2.2 多 Agent 协作的本质把上下文切成独立的工作间多 Agent 模型的好处不是用了很多模型所以更智能而是每个 Agent 拥有独立的上下文窗口各自维护一套干净的对话历史。负责技术特征提取的 Agent 不需要知道比对 Agent 中间经过了哪些推理步骤它只需要接收规范化的输入、输出规范化的结果。这就像一家公司不会让研发、法务、销售坐在同一张桌子上同时发言而是各干各的活通过固定格式的文档交接。HagiCode 里对这种交接的定义就是协作配置的核心。2.3 什么时候真正的需要多 Agent什么时候只是徒增复杂度我也见过不少人把简单任务硬拆成多 Agent结果延迟翻了几倍、token 消耗翻了几倍产出却没有变好。这里我给自己定了一个判断标准如果你的任务能用一个 500 字以内的系统提示词描述清楚且不需要多种完全不同类型的子任务那单 Agent 就是最优解。多 Agent 的收益要在满足下面任意一条时才会体现任务链路中存在多种截然不同的输出格式或判断逻辑单个 Agent 的上下文预算无法覆盖完整流程所需的历史信息流程中存在可以被并行处理、互不依赖的子任务某个环节失败时需要精准重试而不想重跑整个流程HagiCode 的价值在于它把上面这些判断变成了可视化的编排配置而不是靠你在代码里手动维护一堆 if-else 和消息队列。3. HagiCode 的多 Agent 协作模式三种拓扑结构怎么选HagiCode 的协作配置在我看来本质上是在回答三个问题Agent 之间以什么结构连接消息以什么格式流转任务由谁决策下一步围绕这三个问题我把它支持的模式归纳为三种拓扑实际项目里基本就是这三种的叠加。3.1 流水线模式上一棒跑完下一棒才接棒流水线模式最适合那种步骤前后依赖清晰、中间产物边界分明的任务。我搭的第一个 HagiCode 实验流程就是这种检索 Agent 查文献摘要 Agent 读文献比对 Agent 做差异分析报告 Agent 写总结。配置时的关键参数有三个参数作用我的推荐值context_passthrough是否把上游全部历史传给下游关闭只传结构化结果output_schema_validation是否校验上游输出字段开启严格模式retry_on_failure下游失败时的重试策略仅重试下游节点不回溯上游这里我强烈建议把context_passthrough关掉。很多人刚上手时会图省事让上游 Agent 把完整对话记录一股脑传给下游。这样做短期内跑得通但只要链路超过三个 Agenttoken 消耗会指数级上涨并且下游 Agent 会被大量无关上下文干扰。正确的做法是在上游 Agent 的输出配置里用output_schema严格声明一个结构化的 JSON 输出下游只接收这个 JSON。# 伪代码示意实际配置以 HagiCode 控制台 Schema 为准 output_schema: { type: object, properties: { doc_id: {type: string}, key_tech_features: {type: array, items: {type: string}}, risk_flags: {type: array, items: {type: string}} }, required: [doc_id, key_tech_features, risk_flags] }3.2 编排——路由模式一个调度者一群执行者当任务类型不固定需要根据内容动态决定走哪条分支时流水线模式就不够用了。比如我做 AI 短剧脚本生成工具时一个入口进来的用户需求可能是古风爱情也可能是科幻悬疑还有可能是都市喜剧。不同题材的剧本结构完全不同没有一个通用的流水线能覆盖所有情况。这种场景用 HagiCode 的编排模式更合适一个编排 Agent路由者负责读取用户输入判断题材类型然后把任务分发给对应的专业 Agent。专业 Agent 各自只维护一套系统提示词比如古风 Agent 只懂古风剧本的节奏和台词风格科幻 Agent 只懂世界观设定和硬科幻逻辑。配置编排模式时我最注意的是路由 Agent 的系统提示词。它不需要生成任何内容只需要做分类决策所以提示词里要明确写清楚你的职责是将用户请求分类并分发给正确的处理者不要尝试回答用户问题不要生成内容。只输出 JSON格式为 {task_type: ..., task_args: {...}}。这里的关键是反复强调只输出 JSON、不要生成内容否则路由 Agent 经常会好心地把任务自己回答了导致专业 Agent 接到一个空壳任务。3.3 群聊/协商模式多 Agent 共同解决一个复杂的开放问题第三种模式是我觉得 HagiCode 最有趣的地方——允许 Agent 在同一个共享会话里互相讨论。配置上很像拉一个群把多个 Agent 拉进同一个swarm_id它们能互相看到对方的消息可以在指定轮次内来回发言。这个模式我实际用得比较克制。它最适合的场景是问题没有唯一正确答案需要多个视角的碰撞来逼近一个更优解。比如我在做一个技术方案可行性评估流程时让架构 Agent、成本 Agent、安全 Agent 在同一会话里对某个技术选型发表意见互相质疑和补充。协商模式能明显提升结论的全面性但它也有三个很实际的坑token 消耗是按所有参与者的全部发言计算的几个 Agent 来回聊几轮一次任务的成本可能抵得上普通流水线的五到十倍需要约束发言轮次不限制的话会陷入无限讨论最后不了了之讨论结束时需要有一个总结 Agent 来收敛结论否则产出是一堆散乱的发言记录所以我在配置协商模式时一定会加一个max_rounds参数限制讨论轮数并且在参与者之外额外设置一个总结者 Agent它的系统提示词是你是一个总结者。阅读以上所有参与者的讨论输出一份包含一致观点、分歧点、最终建议的报告不要继续提出新观点。3.4 三种模式的选型对比评估维度流水线模式路由模式群聊/协商模式适用场景步骤明确、顺序固定的流程输入类型不固定、需要分支处理开放性问题、需多角度评估上下文管理难度低各节点边界清晰中需管理路由决策历史高所有参与者共享历史成本控制好较好差需要严控轮次失败重试粒度节点级分支级整体重试典型落地场景文档处理、数据提取分类客服、内容生成路由技术评审、方案选型4. 角色配置的灵魂系统提示词、结构化输出与失败降级很多人在 HagiCode 上配置 Agent 时把所有精力都放在拓扑结构上拓扑搭好了Agent 却表现得很蠢。这里我想说一个观点拓扑决定多 Agent 的骨架角色配置才是真正的灵魂。结构对了但角色定义模糊效果可能比单 Agent 更差。4.1 系统提示词的我是谁要写成可执行规范不要写成性格小传我看到很多人在配置 Agent 时写的系统提示词是这样的你是一位资深的专利分析师拥有丰富的知识产权经验能够准确分析专利文献。这种写法不是完全没用但它没有给模型明确的行为指令。你是资深专家然后呢你要怎么分析按什么步骤输出什么格式这些不说清楚模型就只能靠自由发挥。我自己的写法是把它拆成四个部分职责边界、处理步骤、输出格式、禁忌事项。以我配置的专利比对 Agent为例它的系统提示词核心部分是你是专利比对 Agent。职责将目标文献的技术特征与给定权利要求书进行逐项比对。 处理步骤 1. 读取 input.literature_context 中的技术特征 2. 读取 input.claims_context 中的权利要求 3. 逐项判断目标特征是否被权利要求覆盖输出覆盖、部分覆盖、未覆盖 输出格式严格 JSON{match_results:[{claim_id: ..., coverage: ..., evidence: ...}]} 禁忌不要输出任何 JSON 以外的解释文字不要自行扩大职责范围不要生成法律结论这里最重要的是处理步骤和输出格式。处理步骤把黑盒的模型推理拆成了可预期的子任务模型不容易遗漏环节输出格式则让结果可以被下游直接消费不需要再写一堆正则去猜它在说什么。我实际测试下来加了这两部分的 Agent输出可用率能从五成左右拉到九成以上。4.2 结构化输出HagiCode 配置中值回票价的字段output_schema是 HagiCode 里我觉得价值最高的字段。它相当于给 Agent 的输出装了一个格式约束器模型生成完内容后框架会按你定义的 JSON Schema 做校验不合法就触发一次修复重试。我在实际项目中的做法是所有 Agent 的输出都定义严格的 JSON Schema除了核心数据字段额外加一个error字段默认值为 null让 Agent 在遇到无法处理的情况时输出错误码而不是硬编一个结果required字段里只放绝对必要的字段不要把可选字段设为 required否则会因为一个小缺失反复触发重试、浪费 token注意output_schema配合 HagiCode 的strict_mode: true才能真正发挥威力。如果没开严格模式框架可能只是建议模型按格式输出模型偶尔还是会给你夹带一些 Markdown 代码块标记或者解释性文字。4.3 失败降级的兜底设计没有 panic只有 fallback多 Agent 协作里单点失败是常态而不是意外。HagiCode 配置里有两类失败需要分别处理一类是模型调用失败超时、限流另一类是业务层失败Agent 认为输入不合法、结果校验不通过。模型调用失败我的配置经验是设置重试三次、退避时间从 2 秒起指数增长超过三次就把该节点的输出标记为失败并触发降级路径。降级路径是什么不要让它直接轰炸用户日志而是让它把失败信息发送到一个兜底 Agent或一个固定格式的失败队列里。比如我在短剧工具里如果分镜 Agent失败了降级路径不是让整个流程挂掉而是触发一个简版分镜 Agent只做最简单的景别拆分优先保证后续流程能继续走。业务层失败的兜底也类似。我见过不少人的 Agent 在被问到一个超出职责范围的问题时会开始一本正经地胡说八道编一个结果出来。这是个风险很大的行为。所以我让每个 Agent 在遇到无法处理的情况时输出{error: OUT_OF_SCOPE, reason: ...}然后由编排层把该错误转给一个澄清 Agent让它礼貌地要求用户或上游补充信息。这套设计解决了一个很普遍的问题Agent 太爱面子不懂装懂。5. 上下文管理与记忆共享配置不好Agent 之间的消息传递会炸多 Agent 一旦跑起来最让人头疼的是上下文管理。每个 Agent 有独立的上下文是一回事怎么共享和传递信息又是另一回事。HagiCode 在这块提供了一些配置项但很多默认行为藏着坑。5.1 内存隔离还是共享不要图省事什么都传我在第 3 节里反复强调关掉context_passthrough但这不是说所有共享都不要了。实际场景里有些信息是必须全局共享的比如任务背景、用户原始需求、品牌约束。正确的配置思路是区分全局元信息和节点中间结果。我习惯在每个 Agent 的输入配置里留一个global_context字段放置所有节点都需要的基础信息比如目标受众、语气要求、使用场景。这部分信息量小但是通用可以传给每个节点。至于检索 Agent 搜到了哪些文献摘要 Agent 生成了什么摘要这类中间结果就必须走output_schema在上下游之间显式传递不要让下游 Agent 去看上游 Agent 的完整聊天记录去自己找重点。5.2 记忆机制短期窗口、摘要压缩、长期存储三层配置HagiCode 对会话历史的默认处理方式如果我没理解错是保留最近若干轮加一个摘要。这个机制在单 Agent 场景还好多 Agent 协作时很容易出现问题——某个子任务对话长了摘要压缩策略会把一些对下游重要的细节细节掉。我自己的做法是把 Agent 的交互拆得更碎不要让一个 Agent 在一个会话里做二十轮长对话而是设计成一次调用一个任务的工作模式每次任务完成后把关键结果写入一个可访问的存储比如 Redis 或数据库并清空短期窗口。以 检索 Agent 为例它收到一批关键词做一轮检索输出几条链接和摘要任务就结束了。整个会话的长度被限制得很短根本不需要复杂的记忆压缩。对于确实需要长期记忆的 Agent比如用户偏好 Agent要记住用户在多个项目中的风格偏好我的配置建议是启用 HagiCode 的长期存储把结构化偏好信息写进记录在每次任务开始时重新加载而不是靠模型的上下文去回忆。模型的上下文是流动的写进存储才是固定资产。这就像你记性再好也不如把会议纪要落在文档里靠谱。5.3 消息格式的一致性Agent 之间说的话要对齐多 Agent 协作容易忽略的细节是消息格式的一致性。上游 Agent 输出的字段叫doc_id下游 Agent 的输入 Schema 里写的却是document_id这种不一致会让下游校验直接失败。所以我在配置 HagiCode 时会维护一份共享的消息协议文档所有 Agent 的output_schema和input_schema都从这份协议里复制字段名绝不手写两遍。字段命名规范我推荐统一用snake_case字段语义要明确到不依赖上下文也能理解。比如content这种字段就过于模糊我倾向于用brief_summary、detailed_analysis、risk_flags这种自解释的名字。字段名模糊是配置阶段埋下的雷后面排查的时候会非常痛苦——你根本分不清某个 Agent 报错是因为上游没传值还是字段名不一致。6. 从 0 到 1 实战一个 HagiCode 多 Agent 协作配置的完整过程理论说了不少接下来我拆一个我搭建过的具体案例——AI 辅助专利检索与风险分析工作流从需求拆解到配置落地的完整链路。这个案例几乎涵盖了前面提到的所有知识点。6.1 需求拆解与角色分配需求是这样的输入一篇目标专利的摘要和权利要求系统自动去文献库检索相关在先技术然后做相似度分析判断目标专利的新颖性风险最后生成一份风险评估报告。我把这条需求拆成了五个 AgentAgent 名称职责输入输出特征提取 Agent从目标专利中提取关键技术特征专利摘要、权利要求结构化的技术特征列表检索 Agent根据技术特征构建检索式检索相关文献技术特征列表原始检索结果标题、摘要、链接文献筛选 Agent从检索结果中筛掉无关文献原始检索结果高相关文献列表技术比对 Agent对比高相关文献与目标专利的技术特征目标特征高相关文献覆盖度与差异分析报告生成 Agent汇总所有结果生成风险报告比对结果原始请求结构化风险报告角色划分的原则很简单每个 Agent 只做一个类型的事。特征提取是抽取型任务检索是工具调用型任务筛选是相关性判断型任务比对比对型任务报告生成是生成型任务。五种任务差异巨大拆开之后每个 Agent 的系统提示词都很短模型执行起来也准。6.2 流水线配置与参数设置这个案例用的是流水线模式。链路是单向的每个节点的输出恰好是下一个节点的输入。配置时我在 HagiCode 上依次定义了五个节点每个节点要填的核心参数如下键名为 I 见过的一个 HagiCode 版本里的字段但建议你在自己的版本里确认一遍特征提取 Agent: context_passthrough: false model: default-chat-model output_schema: type: object properties: tech_features: type: array items: type: object properties: feature_id: { type: string } description: { type: string } required: [tech_features] fallback: 返回错误码并终止流程这里有一个很关键的配置技巧检索 Agent 的输入是技术特征列表而不是原始需求。这是多 Agent 协作里最容易理解错的地方——下游的输入永远应该是上游的结构化输出而不是最开始的用户输入。很多人配置时手指一抖把用户输入一路传到底这样每个 Agent 都要重新理解一遍需求前面分工就白拆了。6.3 关键调试经历字段没对齐导致的连环报错这个流程第一次跑的时候我栽了一个特别蠢的跟头。特征提取 Agent 输出的字段叫tech_features检索 Agent 的输入 Schema 我没仔细看默认模板里写的是features。结果每次跑到检索 Agent 就报校验失败。HagiCode 的错误日志里不会直接告诉你字段不匹配它只会显示输入校验失败缺少 features 字段。这种问题排查起来并不难但如果节点多一个一个点开看很浪费时间。我的经验是在正式跑全部流程之前先用一组最小的测试数据逐节点单独调用。每个 Agent 单独喂模拟输入看输出是否合法、字段名是否正确全部验证通过后再串联跑。这个习惯帮我省了非常多排错时间。很多新手直接把所有 Agent 串起来跑一报错就不知道该排查哪个环节最后只能一个一个加日志效率极低。6.4 成本与延迟的实测体验这套五节点流水线我实测下来的单次运行成本大约是单 Agent 直接做完整任务的三倍左右延迟大约是单 Agent 的两倍。为什么要强调这个因为多 Agent 协作不是免费的它拿成本和延迟换了稳定性和可维护性。指标单 Agent 直接生成五节点多 Agent 流水线单次 token 消耗约 8k约 24k平均耗时约 20 秒约 42 秒输出格式合法率约 60%约 95%单环节重试率整体重跑仅失败节点重跑可维护性Low改一处全换High改单个节点即可这么看多 Agent 并不是所有场景的银弹。但如果你的业务对输出稳定性要求高——比如下游还有别的系统在消费 Agent 的结果——那多出来的这份成本是完全划算的。格式合法率从六成到九成五的意义在于你再也不需要写一堆后处理代码去猜模型输出的含义了。7. 并发、重试与可观测性生产环境绕不开的三个话题多 Agent 协作从实验到生产最明显的跨越就是偶尔跑通到稳定跑通。这背后离不开并发配置、重试策略、日志追踪这三件大事。7.1 并发配置小心限流也别把资源全打满HagiCode 默认的并发策略我没仔细研究过但从实际使用经验看各节点如果配置不当很容易触发模型服务提供方的限流。我的建议是区分 I/O 密集节点和推理密集节点。检索 Agent 大部分时间花在调用外部搜索 API 上并发可以调得高一些比如 10-20比对 Agent 和报告生成 Agent 是推理密集型的并发过高会导致单次请求变慢并增加限流概率我通常设在 3-5。这里并发上限是多少合适取决你用的模型服务端限流策略。我个人的经验是一开始保守一点从 1 并发跑起逐步往上试观察到响应延迟明显抬升或者出现 429 报错的临界值就回头降一档。不要盲目追求高并发——多 Agent 场景下单任务已经比单 Agent 慢并发打高只会更快撞上模型服务的性能天花板。7.2 重试机制的配置细节区分可重试和不可重试重试不是无脑重跑。我在 HagiCode 里配置重试时会区分两类错误可重试错误上游请求超时、限流、网络抖动。这类错误重试有效因为再次调用大概率能成功不可重试错误输入数据格式非法、Agent 判断任务超出边界。这类错误重试一万次也一样应该直接走降级或失败分支我建议给每个节点配置retryable_error_types和non_retryable_error_types两个列表。如果框架不支持这种区分至少可以在配置重试条件时把超时和限流类错误设为可重试把校验类错误设为不重试。重试次数我一般设 2 到 3 次超过就触发 fallback。太多重试只是在烧钱。7.3 链路追踪不要让失败信息烂在日志里多 Agent 一次任务会涉及多个节点的多次调用一旦出错你需要在几分钟内定位到是哪个节点、哪次调用出了问题。HagiCode 是否内置了链路追踪不同版本不一样。但不管它内置与否我强烈建议你在自己的代码接入层里给每个任务生成一个trace_id从入口开始把 trace_id 传给每个节点让节点在输出和日志里都带上这个 ID。实际操作中我还喜欢在每次 Agent 调用前后打印结构化日志包含 token 消耗、耗时、返回状态的摘要。这些数据看着不起眼但在你需要诊断为什么今天任务成功率从 95% 掉到 80%的时候是唯一可靠的依据。没有日志你只能靠猜。8. 一个需要反复校准的选项协商模式下如何让人工 Agent 真正协作而不互怼前面聊的主要是流水线和路由模式最后我想单独来说说协商模式因为这是 HagiCode 这类编排工具最吸引人、也最容易翻车的玩法。8.1 为什么协商模式容易变成礼貌的废话生成器我把几个 Agent 拉进同一个会话后第一个版本跑出来的结果简直没法看。架构 Agent 说考虑到系统的可扩展性我建议采用微服务架构成本 Agent 说微服务架构可能带来额外的运维成本我建议综合考虑安全 Agent 说无论采用什么架构安全性都应该放在首位考虑。三轮讨论结束除了三句正确的废话什么都没达成。问题出在角色配置上。协商模式下的每个 Agent 都太全面了它们都能看到别人的发言但它们的系统提示词里没有定义你要基于什么立场、代表什么利益说话。没有立场就没有碰撞没有碰撞就产生不了信息增量。8.2 如何给协商 Agent 增加立场约束我的改进思路是在协商模式的系统提示词里给每个 Agent 增加一个立场声明字段。架构 Agent 的立场是你是架构决策的主导者你的目标是选出一个可长期演进的架构方案。你可以承认其他维度的担忧但不要把决策权让渡给成本或安全维度。如果要调整方案你需要说明架构上的收益。成本 Agent 的立场则是你的唯一目标是控制成本。你需要对每个提议的成本影响做出量化估算如果提议方无法给出成本合理性说明你有权要求补充。这样调完之后互怼就变得有信息量了架构 Agent 会提出具体的微服务拆分方案成本 Agent 会算出基础设施开销和人力成本安全 Agent 会点出认证与数据隔离的具体风险。整个讨论从礼貌地各说各话变成了有立场的交锋。这才是协商模式应该有的样子。8.3 协商的收敛机制没有拍板人的会议永远开不完配置协商模式时一定要有会议主持人。这个人可以是编排层的代码逻辑也可以是一个专门的总结 Agent职责是在讨论到max_rounds时强制停止汇总发言输出最终结论。我通常把max_rounds设为 3 到 4 轮。轮数太少讨论不充分轮数太多边际收益很低大家开始车轱辘话来回说。我自己的体会是协商模式不要作为默认执行路径只把它用在没有标准答案、需要权衡多个维度的决策型任务上。如果一个问题已经有确定的执行流程走流水线就好速度和成本都友好得多。9. 配置清单照着抄就能避掉大部分坑最后我把这几轮实战中沉淀下来的配置清单列出来。这不是什么官方最佳实践纯粹是我自己踩坑踩出来的习惯但照着做至少能帮你少走一半弯路。除非确实需要全貌否则一律关闭context_passthrough让节点间通过结构化的output_schema传数据系统提示词按四个部分写职责边界、处理步骤、输出格式、禁忌事项别写成一个性格小传所有 Agent 的输入输出字段名统一定义维护一份消息协议文档不靠记忆模型调用失败区分可重试和不可重试可重试错误最多重试三次不可重试错误直接走降级每个 Agent 都要有一个无法处理时怎么办的兜底逻辑宁可输出错误码也不要编造结果跑完整流程之前先用最小测试数据逐节点单独验证再串起来跑并发数从低到高逐步试探找出稳定性与吞吐量的平衡点全局维护trace_id打印结构化日志否则生产环境出问题只能干瞪眼协商模式必须设定立场约束、轮数上限、总结者否则就是烧钱开会HagiCode 这套多 Agent 协作配置说到底玩的是边界感——Agent 与 Agent 之间的边界、上下文与上下文的边界、职责与职责的边界。边界划得越清楚整个系统越稳定。我曾经在单 Agent 模式下被各种上下文漂移和角色混乱折磨得够呛换到多 Agent 后只要配置规范了绝大多数情况下系统就像一条分工明确的流水线每个工种各司其职出了问题也能精准定位到工位上。如果你正在从单 Agent 向多 Agent 迁移希望这篇东西能帮你避开我踩过的那些坑早点跑通你自己的AI 冒险团。