1. 内容整体设计与思路拆解1.1 核心需求解析先搞清楚你要解决的到底是什么问题接手任何一个多智能体项目我习惯做的第一件事不是选框架也不是画架构图而是把需求原文翻来覆去读上三遍搞清楚一件事这到底是个单智能体能搞定的事还是必须上多智能体这个判断特别重要。我见过太多项目需求其实很简单比如“把用户提问归类并转给对应客服”结果硬是设计了五个智能体在那里互相传话。最后搞出来的系统不仅慢而且每次调用都要烧掉大量token出了问题还特别难排查。多智能体不是装饰品它适合解决的是那些天然带有分工属性的复杂任务——比如一个任务需要多角色协作、需要不同领域的知识、需要串行推理加并行处理的混合流程。这次的模拟项目X就是一个典型场景需要从大量非结构化文档中提取关键信息按照业务规则做分类再生成结构化报告最后还要对结果做多轮质检。单智能体做这件事不是不行但会把所有逻辑塞进一个超大的对话链路里提示词膨胀到几千行改一处动全身调试一次要等半天。拆成多智能体之后每个智能体只干一件事职责清晰提示词可控出问题也能精准定位到是哪个环节出了岔子。搞清楚“为什么需要多智能体”之后还要再往下深挖一层这个任务的核心流程是什么数据从哪来中间产物是什么最终交付物是什么这一步本质是在做“可拆性分析”——判断任务能不能被切分成边界清晰的子任务以及这些子任务之间是串行、并行还是条件跳转的关系。以模拟项目X为例我当时的拆解结果是这样的信息抽取可以并行跑多个文档每个文档由一个抽取智能体负责分类必须等抽取完成之后才能做因为要用到抽取结果作为输入报告生成又依赖分类结果质检则要对最终产物做一轮独立校验。这个依赖关系直接决定了后面的编排方案也决定了每个智能体的输入输出接口应该怎么设计。1.2 方案选型思考为什么是“编排式”而不是“群聊式”现在市面上的多智能体框架本质上就两大类路子。一类是“群聊式”让一堆智能体围在一张桌子上自由发言你来我往直到讨论出一个结论。另一类是“编排式”由一个控制中枢主导按照预设的流程依次调用各个智能体每一步都有明确的输入输出。模拟项目X我选了编排式。原因说起来很直白群聊式的不可控性太强了。你让四五个大模型在那儿对话它们可能会跑题可能会陷入无限循环可能会为了一个无关紧要的细节争论半天。而且这种讨论过程几乎无法复现同一个问题跑两次中间对话轨迹完全不一样这给测试和回归带来巨大麻烦。编排式就不一样了。它的核心思路是“流程是确定的能力是可替换的”。我用一套工作流把这些智能体串起来每一步的输入输出都是结构化数据就像工厂里的流水线——第一个工位负责清洗第二个工位负责打磨第三个工位负责组装。任何一个工位出了问题整条线停下来你一眼就能看到是哪个环节卡住的。再说灵活性的问题。有人觉得编排式太死板不够智能。我的观点是工程化场景里确定性比灵活性金贵得多。你可以用一个叫“条件分支”的机制来弥补编排式的死板——用户提问触发哪条流程由前置路由智能体来判断。这样既保证了主流程的稳定又留出了按需分流的弹性。还有一个细节容易被忽略编排式方案的调试成本远低于群聊式。因为每一步的输入输出都是显式的你可以把中间结果落盘、打印、回放。群聊式想看中间状态得把那堆来回穿插的对话记录翻出来自己捋费时费力。2. 核心细节解析与实操要点2.1 智能体职责划分的边界感宁可切细不要揉在一起职责划分是多智能体项目里最见功夫的环节。我的原则很朴素一个智能体最好只承担一种“不能被拆分的原子能力”。如果某个智能体既要抽取信息又要做分类判断那它就该被拆成两个。为什么这么强调边界感因为边界越清晰提示词越好写模型表现越稳定。你把“抽取文档中的客户名称、合同编号、金额”这件事单独拎出来提示词可以写得非常精确还能顺便定义输出为JSON结构。但你要是让它“抽取信息并且判断这个合同属于哪类业务”模型就要在两类任务之间反复切换既影响速度又容易两边都不讨好。模拟项目X我划分了五个智能体角色文档解析智能体、信息抽取智能体、业务分类智能体、报告生成智能体、质检智能体。每个角色只认自己的那点职责。比如文档解析智能体只负责把PDF转成干净的纯文本至于怎么从文本里找关键信息那不是它操心的事。这里有个实操技巧值得分享定义智能体职责的时候把“不在它职责范围内的事情”也写进系统提示词里。比如信息抽取智能体的系统提示词最后一行一定要写明“你只负责抽取字段不进行任何业务判断”。别小看这句类似免责声明的话它能明显减少模型越权操作的概率。大模型有时候会自作聪明给它一个任务它会顺手把后续步骤也给干了提前打预防针能省很多麻烦。2.2 人话与结构化指令结合提示词里最值钱的三句话关于智能体的提示词设计我总结了一个“三句话方法论”。每类智能体的系统提示词里必须包含三句关键的话第一句告诉它“你是谁”第二句告诉它“你要做什么”第三句告诉它“你必须怎么输出”。“你是谁”解决角色带入的问题。别只写“你是一个信息抽取助手”要写具体场景。比如“你是一名法务文档审核助理擅长从各类商务合同中提取关键结构化信息”。模型在大规模语料里见过大量类似角色表述越具体的角色设定越能激活它对应领域的知识分布。“你要做什么”要写清楚任务边界和输入接口。这里有个容易犯的错把任务描述混在角色描述里一段话写下来既是角色又是任务。我建议明确分开而且要吃准输入格式。如果上游传进来的是一段JSON系统提示词里就标明“输入为JSON对象包含document字段字段值为纯文本内容”。“你必须怎么输出”是最容易偷懒但最不能偷懒的部分。光说“输出抽取结果”是不够的要给出精确的JSON模板、字段类型定义、甚至是枚举值范围。比如业务分类智能体的输出必须包含category字段可选值为“采购合同/销售合同/服务合同/其他”。模型看到这个约束输出格式就基本不会跑偏。还有一个小细节关于few-shot的用法。提示词里加几个例子不是随便加的要选那种“边界情况”的例子。比如信息抽取那里给一个“客户名缺失”的样例输入和对应的抽取结果模型就会学会输出空值而不是胡编一个。这比在提示词里强调一万遍“不要编造”都管用。2.3 结构化输出的强制手段不只是“请以JSON输出”那么简单多智能体系统的最大坑就是智能体之间传话传不明白。A智能体输出一坨自然语言文本B智能体拿过去解析翻遍整个系统改了三天正则。解决这个问题的关键就是要在每个智能体的输出层做强制结构化约束。我知道有人会说“让模型输出JSON用JSON mode不就行了”现实没那么简单。JSON mode只能保证输出是合法JSON不能保证输出字段符合你的预期。比如你要一个金额字段模型可能给你输出一个字符串“约一百二十万元”而不是数字类型。这种问题在单智能体场景里好办人工看一眼就改过来了但在多智能体流水线里这种脏数据会一路传到下游最后生成的报告全是错的。我的做法是双保险。第一层在提示词里给死格式字段类型、示例值、枚举范围全写在提示词里。第二层在代码里做运行时校验用JSON Schema验证每个智能体的输出结构。不符合Schema的直接重试一次重试还不行就抛异常走人工兜底。这套机制听着简单但能拦住绝大多数格式脏数据。还有一个我踩过的坑别让智能体自己给自己定义输出结构。有人为了方便偷懒跟智能体说“输出你任意结构的JSON”然后指望下游程序能自适应。这可能吗下游代码一接一个报错。正确做法是每个智能体的输出Schema在设计阶段就定死像接口文档一样谁也不能改。流水线代码是强类型的Schema是硬约束模型只是在帮你填值而已。3. 实操过程与核心环节实现3.1 从零搭建工程骨架目录结构比代码更先定型动手写第一行业务代码之前先把工程骨架搭好。我目前比较顺手的一套目录组织方式是按“控制层-执行层-支撑层”来划分模块。控制层放着编排引擎和流程定义执行层放着每个智能体的具体实现支撑层放提示词模板、数据结构定义、工具函数、配置管理这些通用能力。分享一个模拟项目X里实际用到的目录结构草稿src/ ├── orchestrator/ # 编排引擎流程定义 │ ├── workflow.py # 主流程编排 │ └── router.py # 条件分支与路由逻辑 ├── agents/ # 智能体定义 │ ├── base.py # 智能体基类封装公共逻辑 │ ├── extractor.py # 信息抽取智能体 │ ├── classifier.py # 业务分类智能体 │ ├── reporter.py # 报告生成智能体 │ └── auditor.py # 质检智能体 ├── schemas/ # 数据结构定义JSON Schema │ ├── extract_output.json │ ├── classify_output.json │ └── report_output.json ├── prompts/ # 提示词模板按角色分文件 │ ├── extractor_system.txt │ ├── classifier_system.txt │ └── ... ├── core/ # 支撑层模型调用、重试、缓存 │ ├── llm_client.py │ ├── validator.py │ └── config.py └── utils/ # 通用工具这套结构的核心价值在于把变化的部分和不变的部分彻底切开。提示词模板可以频繁改数据结构定义不轻易动编排引擎更是要稳定。哪个环节出了问题直接去找对应模块就行不用在几百个文件里大海捞针。3.2 编排引擎的设计要点状态传递与中断恢复编排引擎是一个多智能体系统的中枢神经。我的设计思路是流程定义和数据流分离。流程定义描述“先做什么、再做什么、哪些步骤可以并行”数据流则描述“每一步输入什么、输出什么、State里存了什么”。模拟项目X的主流程是这样一个DAG结构文档解析 → 信息抽取可并行→ 业务分类 → 报告生成 → 质检。其中“信息抽取”可以按文档维度并行这个并行度可以在配置里控制。实现上我用的是一个极简的“步骤表”加“调度器”的方案。步骤表的每一行定义一个智能体任务包含任务ID、依赖的上游任务ID、对应智能体类型、输入字段映射、输出字段映射。调度器拿着这张表先找出所有没有依赖的任务去执行执行完把结果写入全局状态再去解锁依赖它的下游任务。这套方案不需要引入重量级的任务调度框架几十行代码就能跑通而且每一步的执行状态都可以落盘某个环节挂了能从断点恢复。代码上最关键的一步是状态管理。我建议把所有中间结果统一存在一个字典类型的state对象里key是任务IDvalue是结构化输出。智能体之间不直接通信只读写state。这样解耦的好处非常明显你可以任意调整任务顺序只要保证依赖正确也可以随时把某个中间结果打印出来检查甚至可以在流程跑完之后把整个state序列化存档对后面做链路分析和费用核算都有用。3.3 智能体基类封装每一个智能体都是标准零件为了让五个智能体在工程上表现一致我封装了一个智能体基类。基类干的事包括但不限于模型调用自动重试、输出结构校验、调用日志记录、Token使用量统计。每个具体智能体只需要继承基类实现两个方法build_messages构造给模型的消息序列和parse_response解析模型返回结果。这种方式对后续扩展特别友好。新加一个智能体就是新建一个子类写好提示词搞定。既不影响现有流程也不需要改动调度器代码。这也是我把“约定优于配置”落到实处的方式之一。模型调用的重试逻辑里有一个细节值得说不要只做简单重试。模型接口偶尔报错、偶尔超时、偶尔返回格式非法每种情况的处理策略不同。超时需要增加等待时间再试格式非法需要把错误信息反馈给模型让它重新生成——这其实就是一次轻量的自我修正。我在基类的重试逻辑里内置了几种不同的退避策略重试两到三次后如果还是失败就抛异常让编排引擎走兜底逻辑。日志这块也不能马虎。每个智能体的每次调用我至少记录任务ID、输入内容摘要、输出内容完整值、Token用量、耗时、重试次数。这些日志是后面定位问题和优化成本的核心依据。没有日志的多智能体系统出了问题就是抓瞎。3.4 工具调用的正确姿势让智能体“会动手”而不是“只会说”多智能体系统里“工具调用”这件事值得单拎出来说。所谓工具调用就是让智能体在推理过程中主动去调用外部函数比如查数据库、发HTTP请求、拉取文件、执行计算等。这是让智能体从“嘴炮”变成“实干家”的关键一步。模拟项目X里我设计了一个很实用的场景信息抽取智能体遇到某些需要验证的数据时可以调用一个“编号校验工具”去确认编号格式是否合法。传统写法是把所有数据都让模型自己判断但如果业务上已经有现成的校验脚本为什么不直接让它调实现工具调用的方式很简单在提示词中告诉智能体它有哪些工具可用、每个工具的参数是什么、什么时候使用。然后在代码里把工具注册到模型调用的tools参数里。模型会在适当的时候发出一个工具调用请求程序执行这个工具并把返回结果再喂回给模型。整个过程对上层流程完全透明编排引擎根本不用关心某个智能体到底调没调工具。但这个机制有个隐患工具返回的结果可能非常长塞进上下文里容易把窗口撑爆。我的经验是工具返回前先做裁剪只保留最核心的字段。比如“编号校验工具”其实只需要返回一个布尔值“合法/不合法”那就不应该把整个编号库的匹配详情返回给模型。4. 常见问题与排查技巧实录4.1 中间产物格式错乱跑通流程第一件事先固化接口第一次把整条流水线跑通时我几乎一定会遇到一个问题上游智能体输出的字段下游智能体解析不了。具体表现是信息抽取智能体输出的amount字段是字符串“12,000元”而业务分类智能体在提示词里要求输入的amount是一个纯数字类型结果模型拿到“12,000元”后直接懵了分类结果也变得不稳定。这个问题根子就在接口设计。谁的输出对接谁的输入必须在编码之前就用JSON Schema定死。一旦Schema确定还要在代码中加入校验环节。我在调度器里嵌了一个全局校验模块每个任务执行完成后先过一遍Schema校验不通过就重试。另一个很隐蔽的坑是字段命名不一致。分类智能体输出的字段叫“contract_type”报告生成智能体期望接收的字段叫“category”。两边对不上每次跑流程都要花半小时查数据流到底是在哪一步断的。解决方式很笨但很有效所有跨智能体传递的字段统一维护在一张字段映射表里谁的输出要对接谁的输入一目了然。4.2 循环与死锁怎么避免智能体陷入“来回拉扯”编排式流程里出现循环的概率比想象中高。最常见的场景是在条件分支逻辑里A任务的结果不满足要求流程判断要重新执行B任务B任务执行完之后没有更新应有的状态于是又触发了那条不满足条件的分支结果再次回到B——活生生一个死循环。排查死循环最有效的手段是链路追踪。给每一次流程执行分配一个唯一ID每执行一个任务就在日志里打印一条链路记录。循环一旦出现看日志就能发现同一任务ID反复出现直接定位循环入口。我习惯在编排引擎里加一个硬性防呆机制每个任务记录执行次数超过阈值直接熔断并触发人工通知。同时配置一个全局超时时间整个流程跑超过某个时长就自动终止。寒了心也要承认多智能体的死循环不是“可能不会发生”而是“迟早会发生”所以熔断机制必须在一开始就就位。4.3 Token成本失控把每步开销做成可观测指标多智能体系统跑起来之后你可以会收到一笔惊人的账单。原因很好理解一次完整流程要多次调用大模型每次调用都有输入Token和输出Token加上工具返回的内容塞进上下文Token消耗是单次对话的好几倍。控制Token成本的第一招是做预算限制。在配置中心里给每个智能体设置max_tokens和单次流程总Token预算。预算将用完时后续步骤直接降级为规则引擎处理——比如不再调用报告生成智能体而是用模板生成基础报告。这套降级机制在成本敏感的线上环境里非常重要。第二招是做好上下文裁剪。每步调用前提示词构建时只保留当前任务必要的信息不要为了省事把全量历史数据一股脑塞进去。大模型的Token计费是输入输出都花钱输入做精简直接省下的就是真金白银。模拟项目X里我用了一个字段级裁剪策略传参时只传下游智能体需要的那几个字段而不是把上游输出整包丢进去。第三招是利用缓存。对于信息抽取这类步骤同一份文档如果已经抽过一次结果直接命中缓存不需要重复调用模型。实际项目中一个文档被二次处理大概是常事这个缓存往往能节约百分之二三十的Token消耗。4.4 质量回归与效果评测别只看单点效果要盯全流程多智能体系统的效果评测比单智能体复杂得多。单智能体你可以对着标准答案跑几个测试用例算准确率多智能体牵涉到中间步骤的传递误差一步错就会层层放大。我的做法是分层评测。第一层测单点智能体的效果给每个智能体单独准备测试集校验它的输出是否准确。第二层测全流程的端到端效果准备一组标准输入跑完整条流水线比对最终产物是否达标。第三层测链路的健壮性故意注入一些边角数据看系统能不能扛住不乱报错。这里要提醒一个容易犯的错误中间步骤的效果往往和最终效果不完全正相关。比如信息抽取智能体的准确率是95%看起来挺高但等到报告生成那一步发现有几份关键信息缺失整份报告就废了。所以评测多智能体系统必须用“端到端口径”说话——最终交付物合格才算合格中间指标只能作为参考。5. 部署落地与进阶扩展5.1 按服务形态部署编排层、执行层、模型层分开跑多智能体系统的部署我强烈建议按三层分开编排层控制流、执行层业务逻辑、模型层大模型调用。这三层的资源需求完全不同混在一起部署会导致容量规划困难。模型层消耗的是外部API费用或内部GPU资源执行层是CPU密集跑的是普通的Python服务编排层则更吃内存和调度能力。我用的是一个轻量级Docker Compose方案三个服务分别打包成镜像用环境变量控制各自配置。编排层服务对外提供HTTP接口业务方调用一个入口由编排引擎去拆分任务、调度智能体。执行层服务负责跑那些不依赖大模型的纯逻辑操作比如文档解析、JSON校验、字段映射。模型层则是纯粹的API封装服务把不同厂商的模型接口统一成一个标准接口。部署时最需要留神的是超时时间的配置。模型调用动辄几十秒HTTP网关层的超时设置如果默认是30秒跑大任务时极容易超时。我在网关层把读写超时都调大到10分钟同时用异步任务的方式把重活放到后台执行前端只负责轮询状态。5.2 上线前的压测与容灾一条实际使用的检查清单上线前的测试不能只是功能验证。多智能体系统有两个特有的风险点我会在压测时重点关照一个是并发压力下模型调用频率会不会触发API限流另一个是长耗时流程中途失败后能不能自动恢复。压测方法很简单用JMeter或WRK对编排服务入口发起并发请求逐步加大压力观察模型调用的错误率和响应延迟。如果错误率飙升说明当前并发数已经逼近API限流阈值这时有两个调整方向一是加本地缓存减少重复调用二是在执行层加队列把并发请求排队控制模型调用的瞬间并发量。容灾方面我加了一个失败转移机制某个智能体调用连续失败三次后自动把下游任务切换到备用逻辑上。比如报告生成智能体挂了就切到模板填充模式先保证业务结果出来等模型服务恢复后再重跑生成精确报告。这套机制听着简陋但对线上稳定性的帮助极大。5.3 后续演进方向从固定流程到动态路由编排式方案稳定可靠但代价是流程写死之后不能灵活应变。模拟项目X跑通上线之后我观察到一个很明显的需求不同类型的文档其实走的子流程应该不同。比如一份采购合同和一份服务协议抽取字段不同合规校验项也不同硬塞进同一条流水线既浪费算力又容易误报。下一步的优化方向就是动态路由。用一个大模型做路由控制器根据输入文档的类型动态生成对应的流程实例。把步骤表从“静态定义”改成“动态生成”——路由控制器先判断类型再从流程片段库里组装合适的DAG。这种方式能兼顾编排式的稳定和群聊式的灵活是我目前比较看好的演进方向。但方向归方向落地的时候还得保持克制。动态路由做得太激进又会回到不可控的老路。我的建议是先用有限的几类模板覆盖主流场景路由只在这个模板库里面做选择不要指望模型可以凭空生成一个全新的流程。先把不确定性关在笼子里再谈扩展可能性。踩过几次坑之后我个人的体会是多智能体项目真正的难点不在“会调用大模型”而在“怎么把一个大任务拆成一个可靠的工程系统”。框架和模型能力都在快速迭代但任务拆解、接口设计、状态管理、成本控制这套工程方法论不会过时。希望这篇实战记录能帮你少走几步弯路把这套方案真正落到自己的项目里。 
长河君 · 2026/10/19 8:31:58 · 阅读 1.2k 多智能体系统编排实战：从任务拆解到工程落地方法论
1. 内容整体设计与思路拆解1.1 核心需求解析先搞清楚你要解决的到底是什么问题接手任何一个多智能体项目我习惯做的第一件事不是选框架也不是画架构图而是把需求原文翻来覆去读上三遍搞清楚一件事这到底是个单智能体能搞定的事还是必须上多智能体这个判断特别重要。我见过太多项目需求其实很简单比如“把用户提问归类并转给对应客服”结果硬是设计了五个智能体在那里互相传话。最后搞出来的系统不仅慢而且每次调用都要烧掉大量token出了问题还特别难排查。多智能体不是装饰品它适合解决的是那些天然带有分工属性的复杂任务——比如一个任务需要多角色协作、需要不同领域的知识、需要串行推理加并行处理的混合流程。这次的模拟项目X就是一个典型场景需要从大量非结构化文档中提取关键信息按照业务规则做分类再生成结构化报告最后还要对结果做多轮质检。单智能体做这件事不是不行但会把所有逻辑塞进一个超大的对话链路里提示词膨胀到几千行改一处动全身调试一次要等半天。拆成多智能体之后每个智能体只干一件事职责清晰提示词可控出问题也能精准定位到是哪个环节出了岔子。搞清楚“为什么需要多智能体”之后还要再往下深挖一层这个任务的核心流程是什么数据从哪来中间产物是什么最终交付物是什么这一步本质是在做“可拆性分析”——判断任务能不能被切分成边界清晰的子任务以及这些子任务之间是串行、并行还是条件跳转的关系。以模拟项目X为例我当时的拆解结果是这样的信息抽取可以并行跑多个文档每个文档由一个抽取智能体负责分类必须等抽取完成之后才能做因为要用到抽取结果作为输入报告生成又依赖分类结果质检则要对最终产物做一轮独立校验。这个依赖关系直接决定了后面的编排方案也决定了每个智能体的输入输出接口应该怎么设计。1.2 方案选型思考为什么是“编排式”而不是“群聊式”现在市面上的多智能体框架本质上就两大类路子。一类是“群聊式”让一堆智能体围在一张桌子上自由发言你来我往直到讨论出一个结论。另一类是“编排式”由一个控制中枢主导按照预设的流程依次调用各个智能体每一步都有明确的输入输出。模拟项目X我选了编排式。原因说起来很直白群聊式的不可控性太强了。你让四五个大模型在那儿对话它们可能会跑题可能会陷入无限循环可能会为了一个无关紧要的细节争论半天。而且这种讨论过程几乎无法复现同一个问题跑两次中间对话轨迹完全不一样这给测试和回归带来巨大麻烦。编排式就不一样了。它的核心思路是“流程是确定的能力是可替换的”。我用一套工作流把这些智能体串起来每一步的输入输出都是结构化数据就像工厂里的流水线——第一个工位负责清洗第二个工位负责打磨第三个工位负责组装。任何一个工位出了问题整条线停下来你一眼就能看到是哪个环节卡住的。再说灵活性的问题。有人觉得编排式太死板不够智能。我的观点是工程化场景里确定性比灵活性金贵得多。你可以用一个叫“条件分支”的机制来弥补编排式的死板——用户提问触发哪条流程由前置路由智能体来判断。这样既保证了主流程的稳定又留出了按需分流的弹性。还有一个细节容易被忽略编排式方案的调试成本远低于群聊式。因为每一步的输入输出都是显式的你可以把中间结果落盘、打印、回放。群聊式想看中间状态得把那堆来回穿插的对话记录翻出来自己捋费时费力。2. 核心细节解析与实操要点2.1 智能体职责划分的边界感宁可切细不要揉在一起职责划分是多智能体项目里最见功夫的环节。我的原则很朴素一个智能体最好只承担一种“不能被拆分的原子能力”。如果某个智能体既要抽取信息又要做分类判断那它就该被拆成两个。为什么这么强调边界感因为边界越清晰提示词越好写模型表现越稳定。你把“抽取文档中的客户名称、合同编号、金额”这件事单独拎出来提示词可以写得非常精确还能顺便定义输出为JSON结构。但你要是让它“抽取信息并且判断这个合同属于哪类业务”模型就要在两类任务之间反复切换既影响速度又容易两边都不讨好。模拟项目X我划分了五个智能体角色文档解析智能体、信息抽取智能体、业务分类智能体、报告生成智能体、质检智能体。每个角色只认自己的那点职责。比如文档解析智能体只负责把PDF转成干净的纯文本至于怎么从文本里找关键信息那不是它操心的事。这里有个实操技巧值得分享定义智能体职责的时候把“不在它职责范围内的事情”也写进系统提示词里。比如信息抽取智能体的系统提示词最后一行一定要写明“你只负责抽取字段不进行任何业务判断”。别小看这句类似免责声明的话它能明显减少模型越权操作的概率。大模型有时候会自作聪明给它一个任务它会顺手把后续步骤也给干了提前打预防针能省很多麻烦。2.2 人话与结构化指令结合提示词里最值钱的三句话关于智能体的提示词设计我总结了一个“三句话方法论”。每类智能体的系统提示词里必须包含三句关键的话第一句告诉它“你是谁”第二句告诉它“你要做什么”第三句告诉它“你必须怎么输出”。“你是谁”解决角色带入的问题。别只写“你是一个信息抽取助手”要写具体场景。比如“你是一名法务文档审核助理擅长从各类商务合同中提取关键结构化信息”。模型在大规模语料里见过大量类似角色表述越具体的角色设定越能激活它对应领域的知识分布。“你要做什么”要写清楚任务边界和输入接口。这里有个容易犯的错把任务描述混在角色描述里一段话写下来既是角色又是任务。我建议明确分开而且要吃准输入格式。如果上游传进来的是一段JSON系统提示词里就标明“输入为JSON对象包含document字段字段值为纯文本内容”。“你必须怎么输出”是最容易偷懒但最不能偷懒的部分。光说“输出抽取结果”是不够的要给出精确的JSON模板、字段类型定义、甚至是枚举值范围。比如业务分类智能体的输出必须包含category字段可选值为“采购合同/销售合同/服务合同/其他”。模型看到这个约束输出格式就基本不会跑偏。还有一个小细节关于few-shot的用法。提示词里加几个例子不是随便加的要选那种“边界情况”的例子。比如信息抽取那里给一个“客户名缺失”的样例输入和对应的抽取结果模型就会学会输出空值而不是胡编一个。这比在提示词里强调一万遍“不要编造”都管用。2.3 结构化输出的强制手段不只是“请以JSON输出”那么简单多智能体系统的最大坑就是智能体之间传话传不明白。A智能体输出一坨自然语言文本B智能体拿过去解析翻遍整个系统改了三天正则。解决这个问题的关键就是要在每个智能体的输出层做强制结构化约束。我知道有人会说“让模型输出JSON用JSON mode不就行了”现实没那么简单。JSON mode只能保证输出是合法JSON不能保证输出字段符合你的预期。比如你要一个金额字段模型可能给你输出一个字符串“约一百二十万元”而不是数字类型。这种问题在单智能体场景里好办人工看一眼就改过来了但在多智能体流水线里这种脏数据会一路传到下游最后生成的报告全是错的。我的做法是双保险。第一层在提示词里给死格式字段类型、示例值、枚举范围全写在提示词里。第二层在代码里做运行时校验用JSON Schema验证每个智能体的输出结构。不符合Schema的直接重试一次重试还不行就抛异常走人工兜底。这套机制听着简单但能拦住绝大多数格式脏数据。还有一个我踩过的坑别让智能体自己给自己定义输出结构。有人为了方便偷懒跟智能体说“输出你任意结构的JSON”然后指望下游程序能自适应。这可能吗下游代码一接一个报错。正确做法是每个智能体的输出Schema在设计阶段就定死像接口文档一样谁也不能改。流水线代码是强类型的Schema是硬约束模型只是在帮你填值而已。3. 实操过程与核心环节实现3.1 从零搭建工程骨架目录结构比代码更先定型动手写第一行业务代码之前先把工程骨架搭好。我目前比较顺手的一套目录组织方式是按“控制层-执行层-支撑层”来划分模块。控制层放着编排引擎和流程定义执行层放着每个智能体的具体实现支撑层放提示词模板、数据结构定义、工具函数、配置管理这些通用能力。分享一个模拟项目X里实际用到的目录结构草稿src/ ├── orchestrator/ # 编排引擎流程定义 │ ├── workflow.py # 主流程编排 │ └── router.py # 条件分支与路由逻辑 ├── agents/ # 智能体定义 │ ├── base.py # 智能体基类封装公共逻辑 │ ├── extractor.py # 信息抽取智能体 │ ├── classifier.py # 业务分类智能体 │ ├── reporter.py # 报告生成智能体 │ └── auditor.py # 质检智能体 ├── schemas/ # 数据结构定义JSON Schema │ ├── extract_output.json │ ├── classify_output.json │ └── report_output.json ├── prompts/ # 提示词模板按角色分文件 │ ├── extractor_system.txt │ ├── classifier_system.txt │ └── ... ├── core/ # 支撑层模型调用、重试、缓存 │ ├── llm_client.py │ ├── validator.py │ └── config.py └── utils/ # 通用工具这套结构的核心价值在于把变化的部分和不变的部分彻底切开。提示词模板可以频繁改数据结构定义不轻易动编排引擎更是要稳定。哪个环节出了问题直接去找对应模块就行不用在几百个文件里大海捞针。3.2 编排引擎的设计要点状态传递与中断恢复编排引擎是一个多智能体系统的中枢神经。我的设计思路是流程定义和数据流分离。流程定义描述“先做什么、再做什么、哪些步骤可以并行”数据流则描述“每一步输入什么、输出什么、State里存了什么”。模拟项目X的主流程是这样一个DAG结构文档解析 → 信息抽取可并行→ 业务分类 → 报告生成 → 质检。其中“信息抽取”可以按文档维度并行这个并行度可以在配置里控制。实现上我用的是一个极简的“步骤表”加“调度器”的方案。步骤表的每一行定义一个智能体任务包含任务ID、依赖的上游任务ID、对应智能体类型、输入字段映射、输出字段映射。调度器拿着这张表先找出所有没有依赖的任务去执行执行完把结果写入全局状态再去解锁依赖它的下游任务。这套方案不需要引入重量级的任务调度框架几十行代码就能跑通而且每一步的执行状态都可以落盘某个环节挂了能从断点恢复。代码上最关键的一步是状态管理。我建议把所有中间结果统一存在一个字典类型的state对象里key是任务IDvalue是结构化输出。智能体之间不直接通信只读写state。这样解耦的好处非常明显你可以任意调整任务顺序只要保证依赖正确也可以随时把某个中间结果打印出来检查甚至可以在流程跑完之后把整个state序列化存档对后面做链路分析和费用核算都有用。3.3 智能体基类封装每一个智能体都是标准零件为了让五个智能体在工程上表现一致我封装了一个智能体基类。基类干的事包括但不限于模型调用自动重试、输出结构校验、调用日志记录、Token使用量统计。每个具体智能体只需要继承基类实现两个方法build_messages构造给模型的消息序列和parse_response解析模型返回结果。这种方式对后续扩展特别友好。新加一个智能体就是新建一个子类写好提示词搞定。既不影响现有流程也不需要改动调度器代码。这也是我把“约定优于配置”落到实处的方式之一。模型调用的重试逻辑里有一个细节值得说不要只做简单重试。模型接口偶尔报错、偶尔超时、偶尔返回格式非法每种情况的处理策略不同。超时需要增加等待时间再试格式非法需要把错误信息反馈给模型让它重新生成——这其实就是一次轻量的自我修正。我在基类的重试逻辑里内置了几种不同的退避策略重试两到三次后如果还是失败就抛异常让编排引擎走兜底逻辑。日志这块也不能马虎。每个智能体的每次调用我至少记录任务ID、输入内容摘要、输出内容完整值、Token用量、耗时、重试次数。这些日志是后面定位问题和优化成本的核心依据。没有日志的多智能体系统出了问题就是抓瞎。3.4 工具调用的正确姿势让智能体“会动手”而不是“只会说”多智能体系统里“工具调用”这件事值得单拎出来说。所谓工具调用就是让智能体在推理过程中主动去调用外部函数比如查数据库、发HTTP请求、拉取文件、执行计算等。这是让智能体从“嘴炮”变成“实干家”的关键一步。模拟项目X里我设计了一个很实用的场景信息抽取智能体遇到某些需要验证的数据时可以调用一个“编号校验工具”去确认编号格式是否合法。传统写法是把所有数据都让模型自己判断但如果业务上已经有现成的校验脚本为什么不直接让它调实现工具调用的方式很简单在提示词中告诉智能体它有哪些工具可用、每个工具的参数是什么、什么时候使用。然后在代码里把工具注册到模型调用的tools参数里。模型会在适当的时候发出一个工具调用请求程序执行这个工具并把返回结果再喂回给模型。整个过程对上层流程完全透明编排引擎根本不用关心某个智能体到底调没调工具。但这个机制有个隐患工具返回的结果可能非常长塞进上下文里容易把窗口撑爆。我的经验是工具返回前先做裁剪只保留最核心的字段。比如“编号校验工具”其实只需要返回一个布尔值“合法/不合法”那就不应该把整个编号库的匹配详情返回给模型。4. 常见问题与排查技巧实录4.1 中间产物格式错乱跑通流程第一件事先固化接口第一次把整条流水线跑通时我几乎一定会遇到一个问题上游智能体输出的字段下游智能体解析不了。具体表现是信息抽取智能体输出的amount字段是字符串“12,000元”而业务分类智能体在提示词里要求输入的amount是一个纯数字类型结果模型拿到“12,000元”后直接懵了分类结果也变得不稳定。这个问题根子就在接口设计。谁的输出对接谁的输入必须在编码之前就用JSON Schema定死。一旦Schema确定还要在代码中加入校验环节。我在调度器里嵌了一个全局校验模块每个任务执行完成后先过一遍Schema校验不通过就重试。另一个很隐蔽的坑是字段命名不一致。分类智能体输出的字段叫“contract_type”报告生成智能体期望接收的字段叫“category”。两边对不上每次跑流程都要花半小时查数据流到底是在哪一步断的。解决方式很笨但很有效所有跨智能体传递的字段统一维护在一张字段映射表里谁的输出要对接谁的输入一目了然。4.2 循环与死锁怎么避免智能体陷入“来回拉扯”编排式流程里出现循环的概率比想象中高。最常见的场景是在条件分支逻辑里A任务的结果不满足要求流程判断要重新执行B任务B任务执行完之后没有更新应有的状态于是又触发了那条不满足条件的分支结果再次回到B——活生生一个死循环。排查死循环最有效的手段是链路追踪。给每一次流程执行分配一个唯一ID每执行一个任务就在日志里打印一条链路记录。循环一旦出现看日志就能发现同一任务ID反复出现直接定位循环入口。我习惯在编排引擎里加一个硬性防呆机制每个任务记录执行次数超过阈值直接熔断并触发人工通知。同时配置一个全局超时时间整个流程跑超过某个时长就自动终止。寒了心也要承认多智能体的死循环不是“可能不会发生”而是“迟早会发生”所以熔断机制必须在一开始就就位。4.3 Token成本失控把每步开销做成可观测指标多智能体系统跑起来之后你可以会收到一笔惊人的账单。原因很好理解一次完整流程要多次调用大模型每次调用都有输入Token和输出Token加上工具返回的内容塞进上下文Token消耗是单次对话的好几倍。控制Token成本的第一招是做预算限制。在配置中心里给每个智能体设置max_tokens和单次流程总Token预算。预算将用完时后续步骤直接降级为规则引擎处理——比如不再调用报告生成智能体而是用模板生成基础报告。这套降级机制在成本敏感的线上环境里非常重要。第二招是做好上下文裁剪。每步调用前提示词构建时只保留当前任务必要的信息不要为了省事把全量历史数据一股脑塞进去。大模型的Token计费是输入输出都花钱输入做精简直接省下的就是真金白银。模拟项目X里我用了一个字段级裁剪策略传参时只传下游智能体需要的那几个字段而不是把上游输出整包丢进去。第三招是利用缓存。对于信息抽取这类步骤同一份文档如果已经抽过一次结果直接命中缓存不需要重复调用模型。实际项目中一个文档被二次处理大概是常事这个缓存往往能节约百分之二三十的Token消耗。4.4 质量回归与效果评测别只看单点效果要盯全流程多智能体系统的效果评测比单智能体复杂得多。单智能体你可以对着标准答案跑几个测试用例算准确率多智能体牵涉到中间步骤的传递误差一步错就会层层放大。我的做法是分层评测。第一层测单点智能体的效果给每个智能体单独准备测试集校验它的输出是否准确。第二层测全流程的端到端效果准备一组标准输入跑完整条流水线比对最终产物是否达标。第三层测链路的健壮性故意注入一些边角数据看系统能不能扛住不乱报错。这里要提醒一个容易犯的错误中间步骤的效果往往和最终效果不完全正相关。比如信息抽取智能体的准确率是95%看起来挺高但等到报告生成那一步发现有几份关键信息缺失整份报告就废了。所以评测多智能体系统必须用“端到端口径”说话——最终交付物合格才算合格中间指标只能作为参考。5. 部署落地与进阶扩展5.1 按服务形态部署编排层、执行层、模型层分开跑多智能体系统的部署我强烈建议按三层分开编排层控制流、执行层业务逻辑、模型层大模型调用。这三层的资源需求完全不同混在一起部署会导致容量规划困难。模型层消耗的是外部API费用或内部GPU资源执行层是CPU密集跑的是普通的Python服务编排层则更吃内存和调度能力。我用的是一个轻量级Docker Compose方案三个服务分别打包成镜像用环境变量控制各自配置。编排层服务对外提供HTTP接口业务方调用一个入口由编排引擎去拆分任务、调度智能体。执行层服务负责跑那些不依赖大模型的纯逻辑操作比如文档解析、JSON校验、字段映射。模型层则是纯粹的API封装服务把不同厂商的模型接口统一成一个标准接口。部署时最需要留神的是超时时间的配置。模型调用动辄几十秒HTTP网关层的超时设置如果默认是30秒跑大任务时极容易超时。我在网关层把读写超时都调大到10分钟同时用异步任务的方式把重活放到后台执行前端只负责轮询状态。5.2 上线前的压测与容灾一条实际使用的检查清单上线前的测试不能只是功能验证。多智能体系统有两个特有的风险点我会在压测时重点关照一个是并发压力下模型调用频率会不会触发API限流另一个是长耗时流程中途失败后能不能自动恢复。压测方法很简单用JMeter或WRK对编排服务入口发起并发请求逐步加大压力观察模型调用的错误率和响应延迟。如果错误率飙升说明当前并发数已经逼近API限流阈值这时有两个调整方向一是加本地缓存减少重复调用二是在执行层加队列把并发请求排队控制模型调用的瞬间并发量。容灾方面我加了一个失败转移机制某个智能体调用连续失败三次后自动把下游任务切换到备用逻辑上。比如报告生成智能体挂了就切到模板填充模式先保证业务结果出来等模型服务恢复后再重跑生成精确报告。这套机制听着简陋但对线上稳定性的帮助极大。5.3 后续演进方向从固定流程到动态路由编排式方案稳定可靠但代价是流程写死之后不能灵活应变。模拟项目X跑通上线之后我观察到一个很明显的需求不同类型的文档其实走的子流程应该不同。比如一份采购合同和一份服务协议抽取字段不同合规校验项也不同硬塞进同一条流水线既浪费算力又容易误报。下一步的优化方向就是动态路由。用一个大模型做路由控制器根据输入文档的类型动态生成对应的流程实例。把步骤表从“静态定义”改成“动态生成”——路由控制器先判断类型再从流程片段库里组装合适的DAG。这种方式能兼顾编排式的稳定和群聊式的灵活是我目前比较看好的演进方向。但方向归方向落地的时候还得保持克制。动态路由做得太激进又会回到不可控的老路。我的建议是先用有限的几类模板覆盖主流场景路由只在这个模板库里面做选择不要指望模型可以凭空生成一个全新的流程。先把不确定性关在笼子里再谈扩展可能性。踩过几次坑之后我个人的体会是多智能体项目真正的难点不在“会调用大模型”而在“怎么把一个大任务拆成一个可靠的工程系统”。框架和模型能力都在快速迭代但任务拆解、接口设计、状态管理、成本控制这套工程方法论不会过时。希望这篇实战记录能帮你少走几步弯路把这套方案真正落到自己的项目里。