上个周末我花了几个小时把一个调研报告生成流程拆成了三个 Agent 来做一个负责读资料、一个负责整理表格、一个专门挑错。跑通之后我最大的感受是与其在一个 Agent 里塞一大堆角色设定和复杂指令不如让不同 Agent 去扮演不同角色互相聊着把事情做了。当时用的工具就是 AutoGen 多智能体对话框架这也是我目前做多 Agent 协作系统时最顺手的一套方案。这篇文章不打算做那种面面俱到的文档翻译我就从“怎么把一个真实需求拆成多个 Agent再用 AutoGen 把它们组织起来”这个角度出发把我踩过的坑、验证过的写法、以及一些底层逻辑一起聊清楚。哪怕你之前没接触过 Agent 概念只要会写一点 Python按着文章里的步骤也能搭出一个能跑的协作 Demo。1. 先看核心问题为什么单个 Agent 不够用非得引入多智能体协作先说一个我经常遇到的场景。我需要让大模型写一份业务周报里面要有数据、有结论、有风险提示。最直接的做法是写一个很长的 Prompt要求模型“先分析数据再归纳结论最后给出建议”一次调用全部完成。但这种做法有两个非常明显的毛病。第一个问题是上下文容易被占满。你把原始数据、历史结论、注意事项全塞给同一个模型模型既要理解数据又要组织语言还要兼顾格式要求。一旦输入变长输出质量就会明显下降经常出现结论和数据对不上的情况。第二个问题是职责不清。一个人又当运动员又当裁判很难做到独立复核。哪怕模型推理能力很强也容易在“自己写的答复”里反复打转找不到逻辑漏洞。用 AutoGen 这种多智能体对话框架思路就完全变了。我不需要把任务一次性压给一个 Agent而是拆成“分析师”、“写手”、“审校”这类角色。每个 Agent 各自维护独立的对话上下文专注做自己那部分活然后通过会话机制把结果传给下一个人。这就是所谓的“多智能体协作系统”核心不再是“一个更强的模型”而是“一组有分工、能对话的 Agent”。我在某公司做数据产品原型时就是靠这套思路解决了过去单 Agent 处理不好的一类任务需要多轮校验、跨步骤依赖、并且要求最终结果能被追溯的流程。2. 拆解 AutoGen 的核心概念Agent、ConversableAgent、GroupChat 和 GroupChatManager在开始写代码之前这几个概念必须弄清楚。AutoGen 里面没有太多花哨的东西核心就是四个Agent、ConversableAgent、GroupChat、GroupChatManager。把这四个东西理解透了整个框架基本就通了。2.1 Agent一切角色的抽象基类Agent 在 AutoGen 里是所有参与者的抽象基类。你可以把它理解成一个“能收发消息的单位”。它本身不一定直接调大模型也可以是一个能执行 Python 代码的进程、一个能读取文件的消息源、甚至可以是一个收到消息后把结果写进数据库的触发器。我们从实际使用层级来讲不需要自己实现 Agent 抽象类更多时候是用它的子类比如 ConversableAgent这也引出了第二个概念。2.2 ConversableAgent既能对话又能调用工具的默认主角ConversableAgent 是 AutoGen 里最重要的类之一。它除了能接收和发送消息还内置了 LLM 对话能力、工具调用能力、以及代码执行能力。还有一个最方便的特性就是它能维护自己的对话上下文不需要你在外部单独管理消息列表。实际开发中我一般会直接用 ConversableAgent 来创建自定义角色。比如你希望一个角色专门做信息检索你可以给他配不同的 system message让它只负责检索动作。你希望另一个人专门挑毛病那也能给这个 Agent 设计完全不同的提示词和行为规则。我见过很多第一次用 AutoGen 的人会纠结于“为什么不直接命令一个助手角色干所有事”。这里有个关键认知多 Agent 的每一个个体都可以使用同一个底层模型但系统提示词和历史消息不同表现出来的能力就不一样。AutoGen 的价值不是“多个模型各聊各的”而是“一套协调机制让不同上下文彼此传递信息”。2.3 GroupChat把多个 Agent 拉进同一个“会议室”GroupChat 是 AutoGen 中用来管理多 Agent 会话的容器。它负责维护三个东西参与者列表、消息流转历史、以及一些会话控制参数。当两个 Agent 单独对话时是一问一答的串行结构比较简单。但到了三个及以上的 Agent就需要有“谁该发言”的规则。GroupChat 就是挂靠会话上下文的地方。它内部保存了一个 messages 列表记录所有 Agent 说过的话。任何一个 Agent 发言之后管理器都可以从中读取最新的上下文再决定下一步交给谁。需要注意GroupChat 本身并不做“发言决策”它只是一个会议室提供讨论环境和历史记录真正主持会议的是 GroupChatManager。2.4 GroupChatManager决定下一轮谁能说话GroupChatManager 是我在整套框架里下功夫最多的地方。它负责核心的“发言人选择逻辑”。从实现角度说每当一个 Agent 讲完话GroupChatManager 会根据当前的对话历史、参与者能力、以及预设的 speaker_selection_method决定下一个轮到谁。这里有个非常实用的细节speaker_selection_method 有几种常见模式默认是 auto也就是让 LLM 自己判断还可以设置成 round_robin也就是所有 Agent 轮流发言或者用 manual由人指路适合调试阶段。我在早期试验里喜欢用 auto因为可以让模型根据讨论内容动态调整发言顺序看起来更“智能”。但后来发现在多轮任务里round_robin 反而更稳定因为每个角色的发言机会是均匀的不容易出现某个 Agent 频繁抢话或者从头到尾没机会说话的情况。推荐做法是初版跑通流程用 round_robin等稳定之后再切回 auto 做优化。简单总结一下这四个概念的关系Agent 是角色ConversableAgent 是带对话和工具能力的角色GroupChat 是角色开会的会议室GroupChatManager 是会议室里的主持人。理解了这个模型下面的代码就好写了。3. 从零搭建一个多智能体协作 Demo周报生成器这一节我分享一个可以直接复现的示例。场景是做一个“周报生成器”读入一组业务数据让一个分析 Agent 提炼关键指标让一个写作 Agent 把指标写成结构化周报再由一个审校 Agent 检查格式和逻辑最后输出终稿。3.1 环境准备安装 autogen 并确认依赖先用 Python 3.9 或以上版本创建虚拟环境然后安装核心库。pip install autogen如果你还打算用代码执行功能需要安装 Docker或者干脆设置不执行代码。大多数 Agent 场景下代码执行并不是必须的我更建议在早期先关掉它避免环境配置的额外麻烦。导入模块import os from autogen import ConversableAgent, GroupChat, GroupChatManager api_key os.environ.get(LLM_API_KEY) llm_config { config_list: [ { model: your-model-name, api_key: api_key, } ] }这里用 your-model-name 占位换成你实际使用的模型名即可。3.2 创建三个角色 Agent下面创建三个 ConversableAgent分别扮演分析师、写手、审校。analyst ConversableAgent( nameAnalyst, system_message( 你是数据分析师。你只负责从原始数据中抽取关键指标 并用简洁的要点输出。不要撰写完整周报。 ), llm_configllm_config, human_input_modeNEVER, ) writer ConversableAgent( nameWriter, system_message( 你是周报撰写员。你会收到分析师提炼的要点 并将其扩展为一篇结构完整的周报。全文需要有条理、有结论。 ), llm_configllm_config, human_input_modeNEVER, ) reviewer ConversableAgent( nameReviewer, system_message( 你是审校员。你负责检查周报是否遗漏关键数据、是否存在逻辑跳跃、 格式是否清晰。发现问题时提出修改意见没有问题就回复 TERMINATE。 ), llm_configllm_config, human_input_modeNEVER, )这里有一个关键点每个 Agent 的 system_message 都写明了职责边界和输出终点。特别是审校 Agent我明确给出了 TERMINATE 信号这直接影响到整个多智能体协作系统能否正常收敛。如果某个 Agent 的 system_message 写得太开放比如“请继续处理所有问题”它很可能永远不结束。所以我强烈建议每个负责收尾的 Agent 在提示词里显式加入“没问题时回复 TERMINATE”这类结束指令。3.3 配置会议室与主持人代码如下group_chat GroupChat( agents[analyst, writer, reviewer], messages[], max_round8, speaker_selection_methodround_robin, ) manager GroupChatManager( groupchatgroup_chat, llm_configllm_config, )我把 max_round 设置为 8意思是整个讨论最多执行 8 轮发言超过这个数被迫终止。这是防止死循环和 Token 消耗失控的保险丝线上环境必须配。3.4 发起任务并观察输出发起对话原始数据 项目A目标完成率 92%同比提升 12%风险点依赖第三方数据接口。 项目B目标完成率 85%同比提升 5%风险点人员不足。 result analyst.initiate_chat( manager, messagef请针对以下业务数据生成这周的周报\n{原始数据}, summary_methodreflection_with_llm, )这段代码跑起来以后你能看到三个 Agent 在控制台轮流输出发言。分析师会先提炼指标写手根据指标生成长文审校再检查并给意见。全部跑完后结果会保存在 result.chat_history 里你可以统一读取。据我实测这种三 Agent 结构能明显减少“单模型一站式生成”常见的缺数据问题。因为审校 Agent 的输出格式里包含检查清单它天然会把分析师和写手遗漏的点找出来。4. 把框架用得更顺工具注册、人工介入和终止条件设计跑通基础 Demo 之后就该进入真实项目的细节了。我总结出三个最影响实际效果的配置模块。4.1 工具注册让 Agent 不只是聊天还能查数据和算指标之前讲 ConversableAgent 时提到过工具调用。在 AutoGen 里注册自定义工具的标准接口是 register_function。拿我实际的“销售数据分析 Agent”举例我希望 Agent 能调用一个计算增长率的函数而不是自己硬算。代码如下def calc_growth(current, previous): if previous 0: return None return (current - previous) / previous * 100 carry_agent ConversableAgent( nameDataHelper, llm_configllm_config, human_input_modeNEVER, ) analyst.register_function( function_map{ calc_growth: calc_growth, }, ) carry_agent.register_function( function_map{ calc_growth: calc_growth, }, )这里要特别注意工具的注册方式不能只在一个 Agent 上注册就完事。AutoGen 里的工具调用涉及两个角色一个是发起调用的 caller通常是有 LLM 能力的 Agent另一个是真正执行函数的 executor通常是 UserProxyAgent 或某个执行容器。所以推荐的写法是from autogen import register_function register_function( calc_growth, calleranalyst, executorcarry_agent, description计算同比或环比增长率输入当期值和上期值, )这样 analyst 负责决定调用carry_agent 负责实际执行职责清晰也容易排查问题。4.2 人工介入什么时候需要 human_input_mode 不是 NEVERhuman_input_mode 是 ConversableAgent 的一个控制参数。取值主要有三种NEVER完全自动不让用户输入。ALWAYS每次发言前都询问用户适合调试。TERMINATE只在对话结束前询问用户是否允许结束。我在很多自动化流程里都习惯写 NEVER但某些场景真的不该这么做。比如涉及审核确认、资金操作、或者对外发布的任务应该至少在最终环节留一个 TERMINATE 模式的人工审查点。这就是所谓的“人工介入闭环”。以我的经验最常见的安全用法是内部提数、中间分析完全自动最后把结果交给一个人工 Agent 去确认。这个人工 Agent 的 human_input_mode 设置成 TERMINATE收到最终结果后询问操作者是否放行。这样既保留了自动化效率又控制住了风险点。4.3 终止条件一个项目的成败往往取决于怎么停下来多智能体系统最尴尬的情况不是不能回答而是停不下来。我见过一个 24 小时跑不停的群聊任务最后花了几百美元 Token 费原因是没人触发终止信号。AutoGen 里终止条件有两个层面第一个层面是终局消息。某个 Agent 的消息里出现特定关键词比如 TERMINATE系统就会判定对话结束。写法如下def is_termination_msg(msg): return isinstance(msg.get(content), str) and TERMINATE in msg[content]这是最常用、也最好理解的一种结束方式。第二个层面是轮数上限。不管是否出现终止信号只要达到 max_round就强制停止。这相当于保险丝不能省。我调研过的真实案例里80% 以上的失控场景都是因为终止条件写得太宽松。推荐标准是“提示词里明确写结束条件 Termination 检测器 max_round 限制”三者同时使用。尤其注意不要让所有 Agent 都在最后回复同样的关键词因为有些版本里任意 Agent 的终止消息都会让整体结束如果你的中间分析 Agent 提前输出 TERMINATE整个流程就被截断了。所以更稳妥的做法是把终止信号只放在最后一个负责总结的 Agent 提示词里。参数可参考下表配置项建议值说明max_round8-12根据任务复杂度调整保守优先is_termination_msg内容包含 TERMINATE必须配合系统提示词使用speaker_selection_methodround_robin 起步稳定后再切换 autohuman_input_modeNEVER / TERMINATE涉钱涉人场景选 TERMINATE5. 常见问题与排查技巧实录这部分是我实际操作里踩过坑之后整理出来的速查表每一条都有真实来由。现象原因解决办法Agent 一直重复同一句话会话历史太长提示词缺少停止信号缩短 max_round明确终止条件某 Agent 全程没发言发言顺序被 auto 策略跳过改用 round_robin或降低该 Agent 发言成本对话在几轮后突然停止is_termination_msg 误判中间消息严格约束 TERMINATE 只出现在末尾 Agent 提示词中工具函数没被执行没有配置 executor 或注册映射不对称用 register_function 同时绑定 caller 和 executor输出格式不符合预期只靠默认提示词没有给出输出模板在 system_message 中贴出完整 Markdown 或 JSON 模板上下文越长越慢每轮都保留完整历史增加摘要机制或拆分多级 GroupChat再分享几个比较隐蔽的细节。第一个是“系统提示词污染”。有人在测试时让一个 Agent 说“你不是助手你是 HR”另一个 Agent 说“你不是 HR你是财务”结果整个群聊都在讨论身份问题任务完全偏掉了。解决方法是把“角色身份”写成上下文的一部分而不是对抗性提示同时在 system_message 里强调目标是完成业务任务而不是抬杠。第二个是“工具返回信息不规范”。当你注册了一个返回复杂结构或很长文本的工具时模型很容易找不到重点。建议函数返回值尽量简洁最好只返回完成状态、核心数据、错误信息三个字段其他细节放到后续 Agent 再查。第三个是“Docker 执行环境隐患”。AutoGen 支持在 Docker 容器里执行代码提升隔离性。但如果容器没有正确的网络策略和资源限制它可能成为安全薄弱点。我的建议是如果只是分析 JSON、生成图表直接用本地进程并限制可访问目录只有在需要运行来源不明代码时才启用 Docker且必须配置只读文件系统、受限网络。这里涉及的就是一个安全边界不能在开发环境随便开绿灯。6. 我的一些个人经验与后续扩展思路最后聊点框架之外的东西。AutoGen 这种多智能体协作系统的诞生背后是“任务分解”和“上下文隔离”这两个思想。它真正擅长处理的不是单一复杂问题而是那些能拆成多个子任务、并且子任务之间存在校验和递进关系的工作流。我在实战项目里最常用的一种设计方式是先用一个 Agent 做初步分析把它的输出当成临时结果再用第二个 Agent 做深度校验让它在自己的上下文里提出质疑最后由第三个 Agent 汇总并输出符合商业文档格式的终稿。这是典型的“草稿-审查-定稿”链路AutoGen 的会话机制天然契合这种节奏。如果你打算把这个框架用于生产环境我建议在动手前先画三张图第一张是“角色分工图”列出每个 Agent 的职责、输入、输出、由谁触发。第二张是“消息流转图”标出在什么情况下由哪个 Agent 发言、什么情况下结束。第三张是“异常处理图”说明遇到解析失败、超时、内容不安全时应该怎么降级。我当时在一套跨平台系统里就是这样推进的先把图上逻辑跟同事对齐再落代码。这样就算后面调整模型或更换基础模型整体替换成本也会低很多因为你拆出来的是稳定的业务模块而不是把逻辑死死绑在某个模型的提示词里。如果你对 GroupChat 的自动发言人选择机制感兴趣还有个很值得探索的方向自定义 speaker selection。你可以通过传入一个函数让自己决定下一轮发言人这样能实现非常精准的编排控制比如“数据分析完成后必须让审校先发言”。这也是它进阶玩法里的高频能力。做多智能体系统最大的收获在于你把“模型的随机性”限制在了一个个小角色里而不是让一个巨大提示词去赌它的单次输出。哪怕某个 Agent 这次答得一般只要下一个 Agent 有校验逻辑整体质量依然稳定。AutoGen 给的不是魔法而是这层“结构化的稳定性”。如果你想做 Agent 协作方向建议从这篇的迷你周报生成器开始先跑通再慢慢加工具、加人、加规则。