做LLM应用开发这一年多我把市面上叫得上名字的Agent框架基本都摸了一遍AutoGen是我在项目里真正落地过、也踩坑最多的一套。这期正好是系列内容的第6.2节专门把AutoGen框架从设计思路到代码实操完整拆一遍想看理论综述的可以绕道想看怎么用、怎么避坑的这篇应该能帮你省下不少时间。AutoGen是微软研究院开源的多人对话式Agent框架核心思想就一句话把一个模型处理所有事变成多个角色协作解决一个任务。它适合谁适合想搭多智能体应用、研究Agent协作模式、或者被长流程复杂任务搞得焦头烂额的开发者。如果你刚接触LLM靠调Prompt就够用那确实可以先不上框架但一旦任务需要拆解、需要调用工具、需要人在关键节点纠偏AutoGen的价值立刻就能体现出来。这篇文章不绕弯子按设计思路→核心组件→完整实操→问题排查的顺序走代码都是能直接跑的版本差异和避坑点我会单独标出来。1. AutoGen到底在解决什么问题1.1 单模型对话的瓶颈先说一个我自己的观察。很多人第一次接触LLM应用都是从一个Prompt搞定一切开始的比如让模型写个Python脚本、总结一份文档、生成一段营销文案。这个模式在小任务上非常好用因为模型本身能力足够强输入输出都在一次对话内完成逻辑链路短出错的概率低。但任务一旦复杂起来问题就暴露了。举个例子你要做一个数据分析报告生成器输入一份CSV输出一份带结论、带图表的HTML报告。如果只靠单次Prompt模型需要同时处理读取数据、理解统计口径、决定可视化方案、撰写结论、拼接HTML模板。任何一个环节出错整个输出就废了。更麻烦的是你没法在中间环节插入人工检查也没法让模型自己拿着数据去验证结论是不是对的。换句话说单模型对话的本质是一个一步到位的赌注赌模型的综合能力足够强赌任务不会出错赌中间不需要人为干预。AutoGen的出发点恰恰就是承认这个赌注不靠谱。它把任务拆开让不同的Agent各管一段再用对话把各个角色串起来。写代码的专心写代码执行代码的专心执行审查逻辑的专心审查人在关键节点可以做裁决。这样每一项子任务都足够简单模型的成功率大幅提升而且整个流程可控、可观察、可介入。1.2 多智能体协作的核心思想AutoGen对多智能体的实现方式可以说是所有框架里最直白的一种——它不搞复杂的编排引擎而是把对话本身当作协作机制。Agent之间通过发送消息来工作你回一句、我回一句跟两个人聊天解决问题一模一样。这个设计有一个容易被忽略的好处调试直观。因为所有协作过程都走消息传递你只要打印对话历史就能看到每一步发生了什么是谁提出了什么方案是谁指出问题又是谁最终拍板。相比之下一些基于图编排或状态机的框架流程是隐形在配置里的出了问题只能对着日志猜。对于我这种习惯看现场的开发者来说AutoGen的对话式设计天然就带了一层可观测性。另一个核心思想是人机协同而不是全自动替代。AutoGen里的UserProxyAgent本质就是人的替身它可以接收人类输入也可以代表人类去执行代码、读取结果。你可以让Agent在遇到关键决策时停下来问人也可以设置成全自动跑完再让人审核。这种灵活度非常重要因为真实业务里没有哪个正经项目敢让Agent从头到尾全自动跑完一遍不做任何人工确认这是我在实际落地中体会最深的一点。2. 核心组件与关键设计拆解2.1 Agent到底是什么AutoGen里最基础的概念就是Agent你可以理解成一个能收发消息、并做出响应的独立对象。它不一定非得是LLM也可以是一个执行器、一个人工入口甚至是一段固定的规则代码。这种抽象非常像现实中的岗位每个角色有自己的职责通过沟通来协作。在实际使用中最常碰到的三个Agent类型是ConversableAgent所有对话型Agent的基类能发消息、收消息、处理消息。理解成通用工位就行。AssistantAgent默认由LLM驱动的助手Agent负责产出方案、写代码、提建议相当于团队里的大脑担当。UserProxyAgent代表人类的代理可以模拟人类输入也可以在本地执行代码并返回执行结果相当于团队里动手又动嘴的那个人。这里要特别说一下AssistantAgent和UserProxyAgent的分工这是AutoGen最经典的组合。AssistantAgent只负责想和写比如生成一段Python代码UserProxyAgent只负责做比如把代码拿去执行再把输出结果或报错信息传回去。如果执行出错AssistantAgent看到报错信息后会自动修正再生成一段新代码UserProxyAgent再执行循环往复直到成功。这个提出方案—执行验证—发现问题—再修正的闭环就是AutoGen解决复杂任务的基本功。2.2 两种对话模式双边聊与群聊AutoGen支持两种交互模式分别对应不同复杂度的场景。第一种是双边对话也就是两个Agent你一句我一句地来回交流最典型的就是上面说的Assistant UserProxy组合。这种模式适合任务边界清晰、只需要一个专家角色和一个执行者角色的场景比如帮我把数据清洗成指定格式或者根据需求生成一个Python函数并测试通过。第二种是群聊模式由三个及以上的Agent组成团队通过一个GroupChatManager来调度发言顺序。群聊里可以放置多个性格和能力不同的角色比如一个负责全局规划的Planner、一个负责写代码的Coder、一个负责挑刺的Critic。每次对话由谁发言可以由GroupChatManager自动决定也可以设定固定的轮转规则。群聊解决的是一个角色搞不定、需要多方碰撞的任务典型场景是复杂项目的方案设计需要有人提想法、有人实现、有人审核。从我的使用经验来说双边对话能解决80%的问题群聊适合那20%确实需要角色碰撞的复杂场景。很多新手一上来就搞五六个Agent的群聊结果经常是Agent们聊得很热闹任务却迟迟不收敛这个后面在排查部分会详细讲。2.3 工具注册与人机协作的核心设计AutoGen最值钱的设计我觉得是工具注册机制。它允许你给Agent挂载自定义函数挂载方式分为两步register_for_llm把函数信息注入给模型看让模型知道有这么一个工具可用和register_for_execution把函数的实际执行逻辑交给某个Agent。这两步分离的好处是模型只负责决定是否调用执行由指定的Agent完成职责清晰。我再举个具体例子。假设你要做一个股票数据查询Agent你写一个get_stock_price(symbol)函数通过register_for_llm注册给AssistantAgent模型在回答帮我查一下苹果的股价时就会生成一个调用该函数的请求然后你再通过register_for_execution把这个函数的执行权交给UserProxyAgent由它在本地执行真实的API查询把结果返回给AssistantAgent去组织成自然语言回答。整个调用链透明可追踪出了问题能精准定位是模型选错了工具还是工具本身执行失败。人机协作方面AutoGen给UserProxyAgent提供了human_input_mode参数三个取值对应三种协作强度NEVER表示全自动不等人输入ALWAYS表示每次响应前都等人工确认TERMINATE表示只在需要终止对话时才征求人的意见。我在项目里最常用的是第三种让Agent自由跑但到了真正需要收尾或者遇到不确定决策时停下来让我拍板。3. 实操从零搭一个AutoGen应用3.1 环境准备与版本选择先说版本这是AutoGen目前最大的坑之一。网上你搜到的教程大量还是基于0.2版本的老API比如autogen.AssistantAgent、initiate_chat这套写法而从0.4版本开始微软做了一个大重构包结构变成了autogen_agentchat和autogen_coreAPI风格变化非常大。我这篇主体按更常见的0.2.x写法来讲因为存量项目多、参考资料也多但会在最后单独用一节讲0.4迁移需要注意什么免得你照着旧教程写新版本代码直接报错。安装很简单直接装Python 3.9以上的环境然后执行pip install autogen如果你需要用到群聊或者代码执行推荐加装pip install autogen[autobuild]装完以后配置模型是关键。AutoGen通过config_list传入LLM配置最常用的当然是OpenAI兼容接口。这里我踩过一个坑很多人以为只能填OpenAI官方地址其实base_url完全可以填任何兼容OpenAI协议的服务地址这个对国内用户、或者公司内网部署私有模型的人来说特别重要。配置示例import autogen config_list [ { model: gpt-4o, api_key: your-api-key, base_url: https://api.openai.com/v1 } ] llm_config { config_list: config_list, temperature: 0.7, }3.2 双Agent对话Demo最小可用闭环下面这个例子是AutoGen官方文档里的经典开场也是我建议所有新手先跑通的第一段代码。它的效果是AssistantAgent负责写代码UserProxyAgent负责执行代码如果代码报错就自动修改重来直到成功。import autogen assistant autogen.AssistantAgent( nameassistant, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeTERMINATE, max_consecutive_auto_reply10, is_termination_msglambda x: x.get(content, ).rstrip().endswith(TERMINATE), code_execution_config{ work_dir: workspace, use_docker: False, }, ) user_proxy.initiate_chat( assistant, message写一个Python脚本输入n后输出斐波那契数列前n项并运行验证结果。, )这段代码里有两个参数特别值得说。第一个是max_consecutive_auto_reply10它限制UserProxyAgent在没有人类介入的情况下最多自动回复10次防止两个Agent陷入无限循环。第二个是code_execution_config里的use_dockerFalse表示代码直接在本地Python环境执行。我建议初学阶段先关掉Docker因为配置Docker本身又是一道门槛但真正做严肃项目时强烈建议换成use_dockerTrue让代码在隔离容器里跑避免模型生成的代码碰到你本机的文件系统。跑通这个Demo以后你就掌握了AutoGen的完整工作闭环任务发起→方案生成→代码执行→结果反馈→修正迭代。后面所有复杂应用都是在这个闭环上加角色、加工具、加规则。3.3 群聊模式与角色分工实操群聊模式是我在项目里真正用出价值的地方。举个实际案例我给企业内部搭过一个技术方案评审Agent三个人设分别是规划师、开发者、评审官。规划师负责梳理需求并输出技术选型建议开发者负责把方案落地成具体代码评审官负责挑毛病——检查代码安全隐患、边界条件、性能问题。实现代码如下planner autogen.AssistantAgent( nameplanner, system_message你是一个高级技术规划师擅长梳理需求、拆解任务、输出技术方案。, llm_configllm_config, ) developer autogen.AssistantAgent( namedeveloper, system_message你是一个资深开发工程师负责把方案实现为可运行的python代码。, llm_configllm_config, ) reviewer autogen.AssistantAgent( namereviewer, system_message你是一个代码评审专家严格检查代码的bug、安全问题和边界条件。, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeTERMINATE, max_consecutive_auto_reply10, code_execution_config{work_dir: workspace, use_docker: False}, ) group_chat autogen.GroupChat( agents[user_proxy, planner, developer, reviewer], messages[], max_round20, ) manager autogen.GroupChatManager( namemanager, groupchatgroup_chat, llm_configllm_config, ) user_proxy.initiate_chat( manager, message请设计并实现一个带超时重试机制的HTTP请求工具函数并完成评审。, )这里要注意max_round参数它控制群聊的最大轮数。我建议先设成20左右跑通流程再根据实际任务复杂度调整。设太小任务做不完设太大Agent们会开始无效闲聊尤其是Reviewer这种挑刺型角色容易在鸡蛋里挑骨头无限扩展话题。运行后你可以打印group_chat.messages直观看到每一个角色在每一步说了什么。我个人强烈建议每次跑群聊都看一眼完整对话记录你会发现模型在角色扮演下的行为非常有意思——同一个模型在评审官人设下真的会更严格在开发者人设下会更倾向直接给代码这就是多智能体协作的魅力所在。3.4 工具调用完整示例让Agent学会用真实函数前面说过的工具注册这里给一个完整可跑的示例。场景是做一个数学计算助手给Agent挂一个根据日期计算星期几的真实工具让它把自然语言请求转成真实函数调用。import autogen from datetime import datetime def day_of_week(date_str: str) - str: 根据yyyy-mm-dd格式的日期返回星期几 dt datetime.strptime(date_str, %Y-%m-%d) weekdays [周一, 周二, 周三, 周四, 周五, 周六, 周日] return weekdays[dt.weekday()] assistant autogen.AssistantAgent( nameassistant, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeNEVER, code_execution_configFalse, ) # 注册给LLM让模型知道存在这个工具 assistant.register_for_llm(nameday_of_week, description根据日期返回星期几, funcday_of_week) # 注册给执行端让user_proxy真实执行函数 user_proxy.register_for_execution(nameday_of_week, funcday_of_week) user_proxy.initiate_chat( assistant, message2026年1月1日是星期几请使用工具查询。, )几个关键点register_for_llm里的description写得好不好直接影响模型能不能正确触发工具。我见过太多人把description写得太含糊比如就写一个函数模型根本不知道该什么时候用。好的描述要模拟人的表达习惯比如当你需要根据日期查询星期几时使用此工具参数为yyyy-mm-dd格式的字符串。另外注意我用code_execution_configFalse关掉了代码执行因为这个场景不需要Agent写代码跑代码只需要执行工具函数。很多人默认开着代码执行结果工具函数还没触发模型先自己写了一段模拟代码在那里跑方向完全偏了。这个细节看着小实际影响很大。4. 常见问题与排查技巧实录4.1 运行层问题速查表下面这些是我在实际运行AutoGen时真实碰过的问题整理成速查表照着排查能省很多时间。问题现象常见原因解决办法两个Agent无限对话不停max_consecutive_auto_reply设置过大或没设置终止条件设置合理上限10~20并设置is_termination_msg识别终止词模型一直不调用注册的工具description写得模糊或模型版本不支持function calling重写description包含使用场景和参数格式换支持工具调用的模型代码执行报错找不到文件work_dir目录不存在或代码依赖相对路径先创建workspace目录代码里尽量用绝对路径群聊里某一个Agent一直抢话GroupChat自动选择策略导致偏向某角色改造GroupChatManager的选择函数或限制该Agent的max_consecutive_auto_reply报错model not foundmodel名称填成了别名或模型服务不支持该名称核对模型提供方支持的模型ID别只看展示名中文输出乱码终端编码问题不是AutoGen问题设置环境变量PYTHONIOENCODINGutf-8LLM请求超时模型服务响应慢或timeout设置太小在llm_config里调大timeout并加retry_wait_time4.2 设计层面的几个坑代码层面的问题都能靠报错定位真正麻烦的是设计层面的坑报错不会告诉你但效果会直接打折。第一个坑是Agent人设不一致。你给AssistantAgent设定了system_message之后它所有的回复都受这个设定约束。我见过有人给同一个Agent既设了代码专家人设又要求它负责最终总结结果这个Agent在总结时还在疯狂写代码角色混乱。解决办法是每个Agent只做一件事人设越聚焦越好。想要总结就单独加一个Summarizer角色。第二个坑是过度群聊。新手容易把Agent数量当作复杂度觉得角色越多越厉害结果一个简单任务塞了六个Agent光协调说话顺序就浪费了大量token而且任务迟迟收不拢。我的经验法则是能双边聊完的不用群聊三到四个Agent足够覆盖绝大多数任务。群聊的核心价值是观点碰撞不是为了热闹。第三个坑是人工介入时机不对。human_input_modeALWAYS会让每次Agent回复前都问你一遍非常打扰基本上用一次就再也不想了NEVER又太激进出了错就是连环错。我常用的组合是关键节点用TERMINATE模式配合写清楚终止条件让Agent在真正需要拍板的时候才来问人。4.3 版本迁移要特别注意的差异最后专门说版本。如果你打开AutoGen官方文档发现API跟我上面写的完全不一样不要慌你大概率看的是0.4的新文档。0.4大版本里老接口拆成了autogen_core底层运行时和autogen_agentchat高层Agent API老写法的autogen.AssistantAgent在新版换成了从autogen_agentchat.agents导入的AssistantAgent对话启动方式也从initiate_chat变成了更显式的异步消息循环。我的建议分两种情况如果你只是学习、做Demo、跑通流程继续用0.2.x没问题生态成熟、教程多、坑都被人踩过了如果你要搭建长期维护的生产系统建议直接看0.4的新架构虽然学习曲线陡一些但底层是事件驱动的运行时扩展性和可观测性都比老版本强很多。迁移核心要注意三件事一是导入路径全变了二是群聊配置API换了三是消息类型系统从纯字典变成了带类型的ChatMessage体系。除了版本还有一个很容易被忽略的坑是API Key的安全问题。千万别把config_list硬编码在代码里提交到Git仓库我在公司代码评审里见过太多次这种事故。正规做法是放到环境变量或者.env文件里用os.getenv读取这一点虽然老生常谈但确实值得反复强调。以我个人的使用体会来说AutoGen最值得学习的不是它的API而是它的对话式协作设计思路。它让我重新理解了大模型应用的本质——不是让一个模型变得全能而是让多个模型各司其职、通过对话形成合力。这个框架后期如果要扩展还可以往几个方向走接入AutoGen Studio做低代码可视化编排、给Agent挂更多真实业务工具、甚至把群聊方案沉淀成企业内部的标准评审流程。先把今天这套双Agent和群聊跑通你对多智能体应用的理解会上一个台阶。
AutoGen多智能体框架实战：从设计思路到避坑指南
做LLM应用开发这一年多我把市面上叫得上名字的Agent框架基本都摸了一遍AutoGen是我在项目里真正落地过、也踩坑最多的一套。这期正好是系列内容的第6.2节专门把AutoGen框架从设计思路到代码实操完整拆一遍想看理论综述的可以绕道想看怎么用、怎么避坑的这篇应该能帮你省下不少时间。AutoGen是微软研究院开源的多人对话式Agent框架核心思想就一句话把一个模型处理所有事变成多个角色协作解决一个任务。它适合谁适合想搭多智能体应用、研究Agent协作模式、或者被长流程复杂任务搞得焦头烂额的开发者。如果你刚接触LLM靠调Prompt就够用那确实可以先不上框架但一旦任务需要拆解、需要调用工具、需要人在关键节点纠偏AutoGen的价值立刻就能体现出来。这篇文章不绕弯子按设计思路→核心组件→完整实操→问题排查的顺序走代码都是能直接跑的版本差异和避坑点我会单独标出来。1. AutoGen到底在解决什么问题1.1 单模型对话的瓶颈先说一个我自己的观察。很多人第一次接触LLM应用都是从一个Prompt搞定一切开始的比如让模型写个Python脚本、总结一份文档、生成一段营销文案。这个模式在小任务上非常好用因为模型本身能力足够强输入输出都在一次对话内完成逻辑链路短出错的概率低。但任务一旦复杂起来问题就暴露了。举个例子你要做一个数据分析报告生成器输入一份CSV输出一份带结论、带图表的HTML报告。如果只靠单次Prompt模型需要同时处理读取数据、理解统计口径、决定可视化方案、撰写结论、拼接HTML模板。任何一个环节出错整个输出就废了。更麻烦的是你没法在中间环节插入人工检查也没法让模型自己拿着数据去验证结论是不是对的。换句话说单模型对话的本质是一个一步到位的赌注赌模型的综合能力足够强赌任务不会出错赌中间不需要人为干预。AutoGen的出发点恰恰就是承认这个赌注不靠谱。它把任务拆开让不同的Agent各管一段再用对话把各个角色串起来。写代码的专心写代码执行代码的专心执行审查逻辑的专心审查人在关键节点可以做裁决。这样每一项子任务都足够简单模型的成功率大幅提升而且整个流程可控、可观察、可介入。1.2 多智能体协作的核心思想AutoGen对多智能体的实现方式可以说是所有框架里最直白的一种——它不搞复杂的编排引擎而是把对话本身当作协作机制。Agent之间通过发送消息来工作你回一句、我回一句跟两个人聊天解决问题一模一样。这个设计有一个容易被忽略的好处调试直观。因为所有协作过程都走消息传递你只要打印对话历史就能看到每一步发生了什么是谁提出了什么方案是谁指出问题又是谁最终拍板。相比之下一些基于图编排或状态机的框架流程是隐形在配置里的出了问题只能对着日志猜。对于我这种习惯看现场的开发者来说AutoGen的对话式设计天然就带了一层可观测性。另一个核心思想是人机协同而不是全自动替代。AutoGen里的UserProxyAgent本质就是人的替身它可以接收人类输入也可以代表人类去执行代码、读取结果。你可以让Agent在遇到关键决策时停下来问人也可以设置成全自动跑完再让人审核。这种灵活度非常重要因为真实业务里没有哪个正经项目敢让Agent从头到尾全自动跑完一遍不做任何人工确认这是我在实际落地中体会最深的一点。2. 核心组件与关键设计拆解2.1 Agent到底是什么AutoGen里最基础的概念就是Agent你可以理解成一个能收发消息、并做出响应的独立对象。它不一定非得是LLM也可以是一个执行器、一个人工入口甚至是一段固定的规则代码。这种抽象非常像现实中的岗位每个角色有自己的职责通过沟通来协作。在实际使用中最常碰到的三个Agent类型是ConversableAgent所有对话型Agent的基类能发消息、收消息、处理消息。理解成通用工位就行。AssistantAgent默认由LLM驱动的助手Agent负责产出方案、写代码、提建议相当于团队里的大脑担当。UserProxyAgent代表人类的代理可以模拟人类输入也可以在本地执行代码并返回执行结果相当于团队里动手又动嘴的那个人。这里要特别说一下AssistantAgent和UserProxyAgent的分工这是AutoGen最经典的组合。AssistantAgent只负责想和写比如生成一段Python代码UserProxyAgent只负责做比如把代码拿去执行再把输出结果或报错信息传回去。如果执行出错AssistantAgent看到报错信息后会自动修正再生成一段新代码UserProxyAgent再执行循环往复直到成功。这个提出方案—执行验证—发现问题—再修正的闭环就是AutoGen解决复杂任务的基本功。2.2 两种对话模式双边聊与群聊AutoGen支持两种交互模式分别对应不同复杂度的场景。第一种是双边对话也就是两个Agent你一句我一句地来回交流最典型的就是上面说的Assistant UserProxy组合。这种模式适合任务边界清晰、只需要一个专家角色和一个执行者角色的场景比如帮我把数据清洗成指定格式或者根据需求生成一个Python函数并测试通过。第二种是群聊模式由三个及以上的Agent组成团队通过一个GroupChatManager来调度发言顺序。群聊里可以放置多个性格和能力不同的角色比如一个负责全局规划的Planner、一个负责写代码的Coder、一个负责挑刺的Critic。每次对话由谁发言可以由GroupChatManager自动决定也可以设定固定的轮转规则。群聊解决的是一个角色搞不定、需要多方碰撞的任务典型场景是复杂项目的方案设计需要有人提想法、有人实现、有人审核。从我的使用经验来说双边对话能解决80%的问题群聊适合那20%确实需要角色碰撞的复杂场景。很多新手一上来就搞五六个Agent的群聊结果经常是Agent们聊得很热闹任务却迟迟不收敛这个后面在排查部分会详细讲。2.3 工具注册与人机协作的核心设计AutoGen最值钱的设计我觉得是工具注册机制。它允许你给Agent挂载自定义函数挂载方式分为两步register_for_llm把函数信息注入给模型看让模型知道有这么一个工具可用和register_for_execution把函数的实际执行逻辑交给某个Agent。这两步分离的好处是模型只负责决定是否调用执行由指定的Agent完成职责清晰。我再举个具体例子。假设你要做一个股票数据查询Agent你写一个get_stock_price(symbol)函数通过register_for_llm注册给AssistantAgent模型在回答帮我查一下苹果的股价时就会生成一个调用该函数的请求然后你再通过register_for_execution把这个函数的执行权交给UserProxyAgent由它在本地执行真实的API查询把结果返回给AssistantAgent去组织成自然语言回答。整个调用链透明可追踪出了问题能精准定位是模型选错了工具还是工具本身执行失败。人机协作方面AutoGen给UserProxyAgent提供了human_input_mode参数三个取值对应三种协作强度NEVER表示全自动不等人输入ALWAYS表示每次响应前都等人工确认TERMINATE表示只在需要终止对话时才征求人的意见。我在项目里最常用的是第三种让Agent自由跑但到了真正需要收尾或者遇到不确定决策时停下来让我拍板。3. 实操从零搭一个AutoGen应用3.1 环境准备与版本选择先说版本这是AutoGen目前最大的坑之一。网上你搜到的教程大量还是基于0.2版本的老API比如autogen.AssistantAgent、initiate_chat这套写法而从0.4版本开始微软做了一个大重构包结构变成了autogen_agentchat和autogen_coreAPI风格变化非常大。我这篇主体按更常见的0.2.x写法来讲因为存量项目多、参考资料也多但会在最后单独用一节讲0.4迁移需要注意什么免得你照着旧教程写新版本代码直接报错。安装很简单直接装Python 3.9以上的环境然后执行pip install autogen如果你需要用到群聊或者代码执行推荐加装pip install autogen[autobuild]装完以后配置模型是关键。AutoGen通过config_list传入LLM配置最常用的当然是OpenAI兼容接口。这里我踩过一个坑很多人以为只能填OpenAI官方地址其实base_url完全可以填任何兼容OpenAI协议的服务地址这个对国内用户、或者公司内网部署私有模型的人来说特别重要。配置示例import autogen config_list [ { model: gpt-4o, api_key: your-api-key, base_url: https://api.openai.com/v1 } ] llm_config { config_list: config_list, temperature: 0.7, }3.2 双Agent对话Demo最小可用闭环下面这个例子是AutoGen官方文档里的经典开场也是我建议所有新手先跑通的第一段代码。它的效果是AssistantAgent负责写代码UserProxyAgent负责执行代码如果代码报错就自动修改重来直到成功。import autogen assistant autogen.AssistantAgent( nameassistant, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeTERMINATE, max_consecutive_auto_reply10, is_termination_msglambda x: x.get(content, ).rstrip().endswith(TERMINATE), code_execution_config{ work_dir: workspace, use_docker: False, }, ) user_proxy.initiate_chat( assistant, message写一个Python脚本输入n后输出斐波那契数列前n项并运行验证结果。, )这段代码里有两个参数特别值得说。第一个是max_consecutive_auto_reply10它限制UserProxyAgent在没有人类介入的情况下最多自动回复10次防止两个Agent陷入无限循环。第二个是code_execution_config里的use_dockerFalse表示代码直接在本地Python环境执行。我建议初学阶段先关掉Docker因为配置Docker本身又是一道门槛但真正做严肃项目时强烈建议换成use_dockerTrue让代码在隔离容器里跑避免模型生成的代码碰到你本机的文件系统。跑通这个Demo以后你就掌握了AutoGen的完整工作闭环任务发起→方案生成→代码执行→结果反馈→修正迭代。后面所有复杂应用都是在这个闭环上加角色、加工具、加规则。3.3 群聊模式与角色分工实操群聊模式是我在项目里真正用出价值的地方。举个实际案例我给企业内部搭过一个技术方案评审Agent三个人设分别是规划师、开发者、评审官。规划师负责梳理需求并输出技术选型建议开发者负责把方案落地成具体代码评审官负责挑毛病——检查代码安全隐患、边界条件、性能问题。实现代码如下planner autogen.AssistantAgent( nameplanner, system_message你是一个高级技术规划师擅长梳理需求、拆解任务、输出技术方案。, llm_configllm_config, ) developer autogen.AssistantAgent( namedeveloper, system_message你是一个资深开发工程师负责把方案实现为可运行的python代码。, llm_configllm_config, ) reviewer autogen.AssistantAgent( namereviewer, system_message你是一个代码评审专家严格检查代码的bug、安全问题和边界条件。, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeTERMINATE, max_consecutive_auto_reply10, code_execution_config{work_dir: workspace, use_docker: False}, ) group_chat autogen.GroupChat( agents[user_proxy, planner, developer, reviewer], messages[], max_round20, ) manager autogen.GroupChatManager( namemanager, groupchatgroup_chat, llm_configllm_config, ) user_proxy.initiate_chat( manager, message请设计并实现一个带超时重试机制的HTTP请求工具函数并完成评审。, )这里要注意max_round参数它控制群聊的最大轮数。我建议先设成20左右跑通流程再根据实际任务复杂度调整。设太小任务做不完设太大Agent们会开始无效闲聊尤其是Reviewer这种挑刺型角色容易在鸡蛋里挑骨头无限扩展话题。运行后你可以打印group_chat.messages直观看到每一个角色在每一步说了什么。我个人强烈建议每次跑群聊都看一眼完整对话记录你会发现模型在角色扮演下的行为非常有意思——同一个模型在评审官人设下真的会更严格在开发者人设下会更倾向直接给代码这就是多智能体协作的魅力所在。3.4 工具调用完整示例让Agent学会用真实函数前面说过的工具注册这里给一个完整可跑的示例。场景是做一个数学计算助手给Agent挂一个根据日期计算星期几的真实工具让它把自然语言请求转成真实函数调用。import autogen from datetime import datetime def day_of_week(date_str: str) - str: 根据yyyy-mm-dd格式的日期返回星期几 dt datetime.strptime(date_str, %Y-%m-%d) weekdays [周一, 周二, 周三, 周四, 周五, 周六, 周日] return weekdays[dt.weekday()] assistant autogen.AssistantAgent( nameassistant, llm_configllm_config, ) user_proxy autogen.UserProxyAgent( nameuser_proxy, human_input_modeNEVER, code_execution_configFalse, ) # 注册给LLM让模型知道存在这个工具 assistant.register_for_llm(nameday_of_week, description根据日期返回星期几, funcday_of_week) # 注册给执行端让user_proxy真实执行函数 user_proxy.register_for_execution(nameday_of_week, funcday_of_week) user_proxy.initiate_chat( assistant, message2026年1月1日是星期几请使用工具查询。, )几个关键点register_for_llm里的description写得好不好直接影响模型能不能正确触发工具。我见过太多人把description写得太含糊比如就写一个函数模型根本不知道该什么时候用。好的描述要模拟人的表达习惯比如当你需要根据日期查询星期几时使用此工具参数为yyyy-mm-dd格式的字符串。另外注意我用code_execution_configFalse关掉了代码执行因为这个场景不需要Agent写代码跑代码只需要执行工具函数。很多人默认开着代码执行结果工具函数还没触发模型先自己写了一段模拟代码在那里跑方向完全偏了。这个细节看着小实际影响很大。4. 常见问题与排查技巧实录4.1 运行层问题速查表下面这些是我在实际运行AutoGen时真实碰过的问题整理成速查表照着排查能省很多时间。问题现象常见原因解决办法两个Agent无限对话不停max_consecutive_auto_reply设置过大或没设置终止条件设置合理上限10~20并设置is_termination_msg识别终止词模型一直不调用注册的工具description写得模糊或模型版本不支持function calling重写description包含使用场景和参数格式换支持工具调用的模型代码执行报错找不到文件work_dir目录不存在或代码依赖相对路径先创建workspace目录代码里尽量用绝对路径群聊里某一个Agent一直抢话GroupChat自动选择策略导致偏向某角色改造GroupChatManager的选择函数或限制该Agent的max_consecutive_auto_reply报错model not foundmodel名称填成了别名或模型服务不支持该名称核对模型提供方支持的模型ID别只看展示名中文输出乱码终端编码问题不是AutoGen问题设置环境变量PYTHONIOENCODINGutf-8LLM请求超时模型服务响应慢或timeout设置太小在llm_config里调大timeout并加retry_wait_time4.2 设计层面的几个坑代码层面的问题都能靠报错定位真正麻烦的是设计层面的坑报错不会告诉你但效果会直接打折。第一个坑是Agent人设不一致。你给AssistantAgent设定了system_message之后它所有的回复都受这个设定约束。我见过有人给同一个Agent既设了代码专家人设又要求它负责最终总结结果这个Agent在总结时还在疯狂写代码角色混乱。解决办法是每个Agent只做一件事人设越聚焦越好。想要总结就单独加一个Summarizer角色。第二个坑是过度群聊。新手容易把Agent数量当作复杂度觉得角色越多越厉害结果一个简单任务塞了六个Agent光协调说话顺序就浪费了大量token而且任务迟迟收不拢。我的经验法则是能双边聊完的不用群聊三到四个Agent足够覆盖绝大多数任务。群聊的核心价值是观点碰撞不是为了热闹。第三个坑是人工介入时机不对。human_input_modeALWAYS会让每次Agent回复前都问你一遍非常打扰基本上用一次就再也不想了NEVER又太激进出了错就是连环错。我常用的组合是关键节点用TERMINATE模式配合写清楚终止条件让Agent在真正需要拍板的时候才来问人。4.3 版本迁移要特别注意的差异最后专门说版本。如果你打开AutoGen官方文档发现API跟我上面写的完全不一样不要慌你大概率看的是0.4的新文档。0.4大版本里老接口拆成了autogen_core底层运行时和autogen_agentchat高层Agent API老写法的autogen.AssistantAgent在新版换成了从autogen_agentchat.agents导入的AssistantAgent对话启动方式也从initiate_chat变成了更显式的异步消息循环。我的建议分两种情况如果你只是学习、做Demo、跑通流程继续用0.2.x没问题生态成熟、教程多、坑都被人踩过了如果你要搭建长期维护的生产系统建议直接看0.4的新架构虽然学习曲线陡一些但底层是事件驱动的运行时扩展性和可观测性都比老版本强很多。迁移核心要注意三件事一是导入路径全变了二是群聊配置API换了三是消息类型系统从纯字典变成了带类型的ChatMessage体系。除了版本还有一个很容易被忽略的坑是API Key的安全问题。千万别把config_list硬编码在代码里提交到Git仓库我在公司代码评审里见过太多次这种事故。正规做法是放到环境变量或者.env文件里用os.getenv读取这一点虽然老生常谈但确实值得反复强调。以我个人的使用体会来说AutoGen最值得学习的不是它的API而是它的对话式协作设计思路。它让我重新理解了大模型应用的本质——不是让一个模型变得全能而是让多个模型各司其职、通过对话形成合力。这个框架后期如果要扩展还可以往几个方向走接入AutoGen Studio做低代码可视化编排、给Agent挂更多真实业务工具、甚至把群聊方案沉淀成企业内部的标准评审流程。先把今天这套双Agent和群聊跑通你对多智能体应用的理解会上一个台阶。
