这两年LLM应用开发圈子里最常被问到的已经从怎么调API变成了怎么让多个Agent协作干活。GitHub上一个专注多智能体编排的开源框架硬生生攒到了5.9万Star仓库里每天都有新插件、新案例、新讨论往外冒。这个数字在AI应用框架里属于第一梯队也说明大家确实需要一套能落地的多Agent方案。这篇文章写给三类人看想把LLM从聊天机器人升级成能跑业务的系统的后端开发者刚接触AI应用、被各种Agent概念绕晕的新手以及已经在用LangChain之类的单链工具、想评估要不要引入多Agent编排的选型者。我会按自己实际跑过的流程来讲代码拿过来就能试坑也尽量提前给你标出来。1. 多智能体框架到底在解决什么问题1.1 单Agent方案的天花板先想清楚一个前提为什么不能继续用一个Prompt一个模型的老套路我自己在早期做AI应用时也尝试过把所有需求塞进一个大Prompt里让模型自己判断该干什么。前几个demo跑起来还挺唬人一旦任务复杂就现原形。单Agent有四个绕不过去的坎上下文窗口是有限的。你没法把行业知识、公司制度、历史对话、工具说明全塞进一次请求里更别说让模型在几千行上下文里还保持稳定的注意力。角色是冲突的。一段系统提示词只能定义一种人设。你让同一个Agent既当严格的代码审查员又当热情的产品经理模型很容易精神分裂——一会儿太苛刻一会儿太客气。任务拆解靠人工。单Agent面对帮我分析这批简历并组织面试这类复合任务要么一股脑瞎做要么需要你在对话里手动一步步引导自动化程度很低。工具调用容易乱。上下文一长模型自己都忘了手上有什么工具、该不该调用、调完怎么处理结果。打个比方这就像让一个全栈工程师同时干产品、开发、测试、运维的活。小项目能撑项目一复杂人与人之间的分工协作就是必然选择。多智能体框架干的就是这件事给AI定义角色、定义沟通规则、定义任务流转让一群模型像团队一样协同。1.2 多Agent协作的核心设计多智能体框架的底层思路其实不复杂核心就是三个词角色、消息、编排。角色是指每个Agent拥有独立的系统Prompt比如你是资深后端工程师擅长Python和系统设计消息是指Agent之间通过自然语言对话来传递信息而不是通过硬编码的函数调用编排是指有一个机制决定谁在什么时候跟谁说、任务交出去之后怎么收回来。这里有一个很多人容易忽略的设计选择为什么Agent之间要用对话而不是函数调用来协作答案在于大模型的强项是理解和生成自然语言。用自然语言做协议Agent之间不需要维护复杂的接口文档前端Agent可以直接表达我需要一个能计算用户信用评分的模块后端Agent自然就能响应。虽然这会让消息变长、增加延迟但换来的灵活性和解耦是值得的。我一开始也觉得这不是脱裤子放屁吗实际跑完才知道这种自然语言协议才是多Agent方案能快速搭建各种场景的根本原因。1.3 为什么它能在开源社区攒到5.9万StarStar数量不代表一切但5.9万Star至少说明三件事第一这个项目解决的是普遍痛点不是某个小圈子的自嗨第二它的上手门槛被压到了一个合适的水平新手能跑通老手能扩展第三社区的贡献者一直在迭代对比同类的MetaGPT和CrewAI这个框架的优势在于对对话式协作的支持最原生。我拿这三个主流框架做一个横向对比方便你心里有个谱框架核心定位协作方式适合场景特点本文讲的框架通用多Agent编排对话式群聊自动路由复杂任务拆解、人机协同生态大、资料多、灵活度高MetaGPT软件公司模拟SOP流水线、角色固定代码生成、文档产出偏结构化流程角色细化CrewAI轻量任务代理任务流程绑定中小型自动化流程简洁好懂深度略浅单看Star这个框架把社区活跃度和框架抽象程度平衡得比较好。你要真做生产系统它的API演进虽然有点频繁后面会讲但目前来看是所有同类项目里踩坑资料最全的。2. 核心概念与设计思路拆解2.1 三个必须搞懂的基础组件拿这个框架的API来说说到底就是三个组件Agent、Conversation、GroupChat。Agent是最小工作单元。它封装了三样东西人设system prompt、大脑模型配置、手脚工具列表。一个Agent就是一个机器人员工。Conversation负责管理对话历史。多Agent场景下每一对Agent之间的交流都是一段独立的会话记录历史消息不会互相污染。这一点帮了大忙——如果所有Agent共享一个上下文A和B的闲聊会把C和D的专业讨论冲得乱七八糟。GroupChat则是会议室。所有Agent进入同一个群聊由一个Manager或者叫GroupChatManager来调度。Manager不负责具体干活它只负责一件事根据当前对话内容决定下一条消息该轮到谁发言。搞懂这三个概念整个框架的使用方法就赢了一半。剩下的一半是理解它们怎么流转先有AgentAgent们在Conversation里对话多个Agent和Manager聚在一起就组成GroupChat。2.2 两种主流协作模式怎么选这个框架支持两种典型的协作模式我实际用下来它们的适用场景差异很明显。第一种是双Agent对话模式。A出题、B做题或者A写代码、B审代码。这种模式最稳定因为两个角色各司其职上下文可控非常适合生成审查这类必须互相制衡的任务。我很多线上小工具就用这个模式效果非常稳。第二种是Manager群聊模式。三个以上Agent进GroupChat由Manager做路由。适合任务需要多个专业角色依次或者交错参与的场合比如一个项目经理拆需求、一个后端估工期、一个前端出方案。但灵活性的代价是不可控性增加Manager偶尔会带偏话题需要设计好终止条件。新手我的建议是不要一上来就搞五六个Agent的大群聊。先跑通双Agent模式再加第三个做监督者逐步复杂化。你踩过的坑会少一半。2.3 人机协同human-in-the-loop不是可选项很多人把多Agent框架理解成全自动这其实是个误区。生产环境里必须保留人的介入点。框架里有个参数叫human_input_mode它决定Agent在什么时候需要等待人来输入。跑批任务可以设成NEVER全自动执行但涉及成本决策、内容发布、代码合并这类动作务必要设成需要人类确认的模式。我自己的习惯是框架可以自动执行分析和起草但最终输出对外生效前一定留一道人工审核。所谓人在回路不是为了显摆框架功能而是给错误兜底。LLM的能力再强也扛不住业务规则里那些只可意会不可言传的边界。2.4 模型无关设计不绑定某一家这个框架比较良心的一点是模型无关。你既可以用商业API也可以用开源的本地模型而且都走标准的OpenAI兼容接口。实操层面这意味着你只需要在配置里改两样东西model指定模型名base_url指向模型服务地址。如果你本地起了Ollama把base_url指到http://localhost:11434/v1其他代码一行都不用动。这个设计对于要控成本、要数据不出内网的企业场景特别重要。我在公司内部做试点时就是靠这个切换能力先在商用模型上验证效果再切到本地模型跑推理。3. 从零搭建一个可运行的多Agent系统3.1 环境准备虚拟环境和安装开始之前先把环境收拾干净。我用的是Python 3.10强烈建议用虚拟环境避免和你机器上其他项目的依赖打架。python -m venv agentenv source agentenv/bin/activate # Windows 下是 agentenv\Scripts\activate pip install --upgrade pip pip install autogen-agentchat不同版本的包名可能略有区别装的时候注意看官方仓库当前README里的推荐写法。装完后可以跑一下版本确认python -c import autogen_agentchat; print(autogen_agentchat.__version__)这个框架的API演进比较激进网上很多旧教程的代码直接跑会报错所以看到版本不一致时别慌优先看仓库里examples目录下的最新写法。3.2 配置模型服务API Key和本地模型我用环境变量管理模型配置不写死在代码里。以OpenAI兼容接口为例export OPENAI_API_KEYsk-你的key export OPENAI_BASE_URLhttps://你的服务地址/v1 export OPENAI_MODEL_NAMEgpt-4o-mini如果你用的是本地模型以Ollama举例export OPENAI_API_KEYollama # 占位符本地模型不校验 export OPENAI_BASE_URLhttp://localhost:11434/v1 export OPENAI_MODEL_NAMEqwen2.5:14b配置完成后先写个最简代码验证连通性别等堆了一堆代码才发现模型服务没通from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.messages import TextMessage agent AssistantAgent( nameprobe, model_client..., system_message你是一个连通性测试机器人收到消息只回复PONG, )这一步走通了后面就顺了。3.3 第一个多Agent对话一问一答的双Agent协作下面这段代码我建议你原样跑一遍它是后面所有复杂案例的地基。目标是让程序员Agent写代码评审Agent挑毛病import asyncio from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.teams import RoundRobinGroupChat from autogen_agentchat.ui import Console from autogen_ext.models.openai import OpenAIChatCompletionClient model_client OpenAIChatCompletionClient( modelgpt-4o-mini, api_key你的key, base_url你的服务地址, ) coder AssistantAgent( namecoder, model_clientmodel_client, system_message你是资深Python工程师负责编写简洁可靠的代码。, ) reviewer AssistantAgent( namereviewer, model_clientmodel_client, system_message你是严格的代码评审专家指出问题并提出修改建议。, ) team RoundRobinGroupChat([coder, reviewer], max_turns4) async def main(): await Console(team.run_stream(task写一个用列表实现栈的Python类并进行代码评审)) asyncio.run(main())max_turns4的意思是整个团队最多轮流发言4轮防止对话无限进行。这个参数非常关键我一开始图省事没设置结果两个Agent互相客气你写得不错谢谢夸奖来来回回聊了几十轮token烧得我心绞痛。3.4 升级到群聊多个Agent加一个Manager双Agent跑通后加第三个Agent就顺理成章了。群聊模式下注意要把之前的RoundRobinGroupChat换成GroupChat并指定一个Manager来做路由from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.teams import GroupChat, GroupChatManager analyst AssistantAgent( nameanalyst, model_clientmodel_client, system_message你是数据分析师负责拆解需求并给出数据方案。, ) engineer AssistantAgent( nameengineer, model_clientmodel_client, system_message你是后端工程师负责实现接口和处理逻辑。, ) tester AssistantAgent( nametester, model_clientmodel_client, system_message你是测试工程师负责设计测试用例并指出缺陷。, ) group_chat GroupChat( participants[analyst, engineer, tester], termination_condition..., ) manager GroupChatManager(group_chatgroup_chat, model_clientmodel_client)这个组队方式有个好处每个Agent只关注自己的专业视角不会被额外信息干扰。但要注意Manager本身也会消耗token因为它每轮都要读一遍群聊内容来决策谁来发言。群聊越长这部分的成本越高。所以群聊里的Agent数量不是越多越好三个能做完的事就不要拉五个。3.5 让Agent动起来注册工具与函数调用只靠对话多Agent做不了实事。要让Agent真正干活必须给它注册工具。这个框架里注册工具非常直接——把普通Python函数注册成Agent的工具即可from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.tools import FunctionTool def query_stock_price(code: str) - str: 根据股票代码返回最新价格。 # 这里对接真实的行情接口 return f{code} 最新价格: 12.35 元 stock_tool FunctionTool(query_stock_price, description查询A股最新价格) quant_agent AssistantAgent( namequant, model_clientmodel_client, system_message你是量化分析助手查询股票价格并给出分析结论。, tools[stock_tool], )注意FunctionTool的description字段。这个描述不是给人看的是给模型看的。模型会根据描述判断什么时候该调用哪个工具描述写得越清楚模型选工具的准确率越高。我见过很多工具调用乱套的案例最后查下来都是description写得模棱两可。4. 实战案例做一个招聘助理系统4.1 需求拆解讲完基础组件用一个完整的案例把它们串起来。我挑一个比较典型的场景招聘助理系统。它要能做三件事根据岗位描述分析核心要求、筛选候选人简历、模拟一轮面试并给出综合评价。这个需求的自然分工是三个Agent各干一段。但要实现真正的协作不能只是把三个Agent简单排队得让它们之间产生信息和意见的传递简历筛选Agent要参考岗位分析Agent的输出面试官Agent的提问要基于前面两者给出的重点。4.2 Agent角色设计与协作流程我的角色设计如下Agent职责关键输入输出岗位分析师解析JD提炼硬性要求和加分项岗位描述文本岗位画像、评分维度简历筛选员逐条比对候选人简历与岗位画像岗位画像、简历文本候选人排序、优劣势清单面试官基于画像和简历生成模拟面试问题与评分岗位画像、简历评估面试问题列表、建议评分协作流程上岗位分析师先发言产出岗位画像简历筛选员拿到画像后逐份分析简历面试官最后拿到前面所有信息生成面试提纲。这个流程天然适合顺序执行所以我用群聊模式加一个必须按顺序发言的规则来约束不让Manager乱调度。4.3 核心代码与运行效果核心代码片段jd_text 岗位名称资深后端工程师 职责负责交易系统后端架构设计与开发保障系统高可用。 要求5年以上后端经验精通Python/Go熟悉分布式系统有高并发项目经验。 resume_text 姓名张三 经验6年后端开发3年交易系统方向 技能Python、Go、Kafka、Redis、MySQL 项目主导过日订单量百万级的交易系统重构 # 三个Agent角色配置省略按4.2表格设计 # 群聊执行 async def run_recruitment(): result await team.run(taskf岗位描述{jd_text}\n候选人简历{resume_text}) return result asyncio.run(run_recruitment())实际跑出来的效果先不说结论质量如何单看流程是很有价值的岗位分析师把JD里高可用高并发拆成了具体的评分维度简历筛选员据此重点考察了候选人的交易系统重构经历面试官的问题也都围绕分布式一致性、缓存策略这些关键能力展开。整个链条上信息没有断裂这就是多Agent和单Agent大Prompt的本质区别——专业角色把信息消化之后再传递而不是一股脑堆给下一个环节。4.4 Token预算与成本控制这个案例看起来简单但你要留意token消耗点其实有四处每个Agent处理自己的任务各消耗一份上下文Manager每轮决策消耗一份群聊里各Agent还要读一遍历史消息。三轮群聊跑下来相当于一个任务烧了五到六份对话成本。我控制成本的做法是能精简上下文的就精简比如简历筛选阶段只把岗位画像的关键字段传进去不把完整JD再背一遍能少跑轮次的就少跑比如面试官生成问题列表后立刻终止不再让它自我反思一番。开源框架的特点是方便但它不会替你省钱预算策略必须自己设计。5. 常见问题与排查技巧实录5.1 API连接与鉴权报错多Agent场景下任何一个Agent调用模型失败都可能让整个对话崩溃。最常见的报错是401和404。401基本是API Key错误或权限不足404则多半是base_url配错了比如漏了版本号或者域名写错。排查顺序我建议是先单独用一个旁路脚本直连模型服务确认服务本身通再用框架的probe Agent测试最后才跑完整多Agent链路。一次只测一个环节不要在多Agent的日志里猜网络问题。5.2 Agent陷入死循环和话题跑偏这是多Agent系统最让开发者头疼的问题。表现是Agent之间来回对话聊的内容开始重复或者逐渐离题万里。我的经验是三条防线齐上设置max_turns上限这是硬性保险丝。在系统Prompt里写清楚你的回答应聚焦当前任务不要复述前文内容。对输出格式做校验比如要求最终结果必须包含特定标记负责解析的程序发现没标记就强制截断。如果还不行就检查是不是自己的Prompt给了Agent过多开放性。比如让面试官自由提问它就真的自由了。给Agent明确只允许基于简历内容提问这类限制跑偏概率会大幅下降。5.3 输出不稳定和幻觉问题多Agent的幻觉和单Agent的本质相同但危害被放大了——因为前一个Agent的幻觉会成为后一个Agent的输入错误会像滚雪球一样累积。我的对策是在关键节点引入事实核查Agent或者工具。比如招聘系统里简历筛选员给出的排序结论必须引用简历原文里的具体字段来支撑。让模型在输出结论时强制附带证据引用很多幻觉在这个环节就暴露了。再提供一个我实测有效的技巧把需要准确的信息放进工具里查而不是让模型从记忆里猜。模型可以做判断但不要让它做记忆。5.4 上下文爆炸和性能优化多Agent方案的另一个通病是上下文越滚越长。每个Agent保存完整对话历史拖慢响应速度还白烧token。优化思路有三个一是历史消息做摘要把前面的长篇对话压缩成要点再喂给后续Agent二是每个Agent只保留与自己相关的子会话不共享全部上下文三是限制单条消息的长度超长输出让模型用要点形式返回。我实际项目里的经验是消息摘要带来的收益最大。同样是十轮对话全量历史可能占了3000个token摘要之后可能只要500个性能提升非常明显。附上一份排查速查表贴墙用的现象可能原因处理方案401/403报错Key错误或权限不足检查环境变量、检查模型服务账户余额404错误base_url错误与服务商文档核对API路径注意版本号对话无终止缺少终止条件设置max_turns、设置termination condition输出重复循环Prompt开放性过高增加约束、强制输出格式、校验关键标记结果明显错误上游Agent幻觉传染增加事实核查环节、要求结论引用证据响应很慢上下文过长做历史摘要、按Agent拆分会话成本飙升轮次过多/消息冗余限制轮次、精简传入内容、复用工具结果6. 从Demo到生产环境的一点反思6.1 Demo很酷生产很现实我见过太多人跑通两个Agent对话就高呼AI要替代开发了结果一上生产就傻眼。Demo和生产的差距主要在三处稳定性、可观测性、评估体系。稳定性方面多Agent的随机性比单Agent大得多。同一份输入今天跑和明天跑可能得到不同的流程走向。生产上必须先定义哪些环节可以随机、哪些必须确定。比如任务路由可以灵活但最终对外输出必须经过确定性校验。可观测性方面多Agent的调试比传统程序难因为你看不到中间状态。我的做法是给每个Agent都加上日志钩子把每一步的消息、工具调用、token消耗都记下来。Debug多Agent问题的第一件事永远是翻日志而不是盯着最终输出猜。6.2 没有评估就不算完成多Agent系统上线前一定要准备一套评估集。说白了就是准备20到50个典型任务每个任务标注期望的流程走向和期望的最终结果每次改完代码就跑一遍看有没有变差。这个习惯救过我很多次。框架升级、模型换版本、Prompt微调都可能悄悄把系统质量带崩。没有评估集你根本感觉不到直到用户投诉的时候已经晚了。6.3 扩展方向RAG、记忆与工具增强多Agent框架的进阶玩法是把RAG、记忆机制和更多工具接进来。让其中一个Agent专职做知识检索把外部文档转成向量后供其他Agent查询再加上长期记忆组件让系统记住历史项目里的偏好和决策。我个人实际跑下来最稳的组合是双Agent对话RAG检索人类审核一个Agent负责拆解问题和检索知识另一个Agent负责生成答案最后由人来确认。这套结构比十个Agent的群聊实用得多也好维护得多。写这篇文章掏了不少压箱底的东西。多Agent框架确实是现阶段让LLM应用上一个台阶的好工具但它不是银弹不要为了多Agent而多Agent。先把单Agent的边界摸清楚把评估集建起来再一步步引入协作这样踩坑最少、见效最快。