AutoGen多智能体实战：从GroupChat到工具调用的踩坑指南

最近我把 AutoGen 从 0.2 一路追到 0.4，断断续续用它在本地搭了三套多智能体协作系统，跑了不下上百次对话。说实话，第一次跑通几个 Agent 互相讨论、追问、修改代码的时候，确实有被惊艳到；但后面被它各种奇奇怪怪的死循环、上下文爆掉、工具调用失败折腾得也很酸爽。这篇文章不打算给你做 API 文档搬运，就聊聊我真实搭多智能体系统的过程、踩过的坑、以及 AutoGen 到底适合做什么、不适合做什么。

如果你刚好在纠结要不要用 AutoGen 做多智能体协作，或者已经在用但总觉得哪里别扭，这篇应该能给你一些参考。

1. 先搞清楚：AutoGen 到底解决什么问题？

1.1 从一个真实痛点说起

我最早的需求其实很简单：让大模型帮我分析一份技术方案，同时模拟“甲方”和“乙方”两种立场来回讨论，最后给出一个折中结论。用单 Agent 的方式，把两个角色塞进一段 system prompt 里，结果模型经常说着说着角色就串了，一会儿像甲方口吻，一会儿又变成了乙方，最后结论也是模棱两可。

后来我尝试用传统方式硬拆：写两套独立的 Prompt，分别调用模型，再把输出拼在一起。这虽然避免了角色串味，但本质是轮询，没有真正的“对话状态”。甲方 Agent 不知道乙方 Agent 上一轮说了什么，回复全靠我手动拼接上下文，一旦多几个角色，代码就成了一堆胶水。

AutoGen 解决的核心问题，恰恰是“让多个 Agent 在同一段会话里自主协作”。它把你需要手动维护的对话历史、角色切换、发言顺序、终止条件全部抽象成框架能力。你在本地定义一个 AssistantAgent，再定义一个 UserProxyAgent，让它们互相发消息，模型会在内部维护多轮上下文，Agent 之间可以自然衔接。

1.2 多智能体不是“多个 API 轮流调用”

网上很多文章把多智能体吹得很玄，但按照我的理解，它本质上是一套“对话路由系统”。多个 API 轮流调用，你还需要自己写状态机来记录谁说过什么、下一步轮到谁；而 AutoGen 把这条状态机内部化了，你只需要关注每个 Agent 的职责和消息格式。

它引入了几类核心抽象：

• ConversableAgent：可以参与对话的智能体基类。
• AssistantAgent：默认用 LLM 补全消息的助手，可以配置 system prompt。
• UserProxyAgent：默认代表人类执行代码、获取输入，也可以自动执行工具函数。
• GroupChat：多 Agent 群聊的会话管理对象。
• GroupChatManager：负责协调群聊顺序、选择下一发言人。

真正跑起来以后，你才会意识到这些抽象的价值。比如UserProxyAgent不只是“模拟用户”，它承担了一个关键职责：执行代码。你让大模型写一段 Python 脚本，它不会自己运行，但UserProxyAgent可以自动在本机跑这段代码，再把执行结果反馈给模型。这等于给 Agent 装上了“手”，让它能自己验证想法。

多智能体的难点从来不是“让多个模型回答”，而是“让它们有序地围绕同一个目标推进”。AutoGen 用群聊的机制来约束这种秩序，我听过的更形象的说法是——它更像一个“带主持人的圆桌会议”，而不是“广播站”。

1.3 它擅长什么，又真的不适合什么

根据自己的实测，我总结了几条边界，新手可以提前避坑：

擅长的事：

• 需要多角色观点碰撞的任务，比如方案评审、产品需求辩论、代码 Review。
• 需要“模型写代码 + 自动执行 + 根据结果修改”的闭环任务。
• 需要模拟用户反馈、反复迭代内容的场景，比如让模型扮演测试人员挑刺。
• 需要把大任务拆成子任务，让不同 Agent 分头负责的探索性流程。

不擅长的事：

• 高并发、低延迟的线上推理管道。AutoGen 的对话循环是重量级的，每次发言都带完整历史，不适合做面向用户的实时接口。
• 简单的单轮调用。如果你只需要一次 completion，没必要引一个 Agent 框架，反而拖慢速度和成本。
• 需要强保证的自动化业务流程。Agent 的自由对话天然有不确定性，除非你做好校验和兜底，否则不建议直接对接生产系统。

另外特别提醒一下，多智能体不是越多越好。我做过 2 个 Agent 的协作，稳定性和效率都非常高；做到 5 个以上 Agent 的时候，对话圈数呈指数上涨，token 消耗非常吓人，而且经常讨论半天没有收敛。后面我会专门讲如何控制这种情况。

2. 我为什么选 AutoGen，而不是 LangChain 或其他框架？

2.1 从 LangChain 迁移过来的对比心得

在投入 AutoGen 之前，我用 LangChain 搭过一个简单的 Agent 工具调用流程。LangChain 的思路是“链式编排”，把每一步处理串成一个 pipeline，再通过 Agent 决定调用哪个工具。理论上很灵活，但实际维护起来有几个痛点：

• 状态管理比较隐晦，回调、记忆、中间步骤交错在一起，出了问题不好追。
• 多个 Agent 协作不是一等公民，更多是“链 + Agent”的组合，写起来很别扭。
• 调试需要层层打印，看不到完整的对话流转。

AutoGen 给我的第一感觉是“所有控制流都是一场对话”。调试的时候直接把消息历史打出来，谁在什么时间说了什么一目了然。这种可视性对开发多智能体系统太重要了。

我整理了一个选型对比表，都是个人感受：

当然，LangChain 的优势是周边工具丰富、集成面广，如果你的需求偏向“重管道、多资源整合”，它依然值得考虑。但如果核心诉求就是“让多个 AI 角色互相讨论、协同完成任务”，AutoGen 的结构更贴合、也更直接。

2.2 AutoGen 的核心抽象：Agent 不是“人”，是“流程节点”

很多人第一次接触 AutoGen 时，会下意识把 Agent 当成一个“有名字的模型”。我的理解是，一个 Agent 就是一个流程节点，它持有自己的上下文、能力和输出规则。你可以让两个 Agent 用同一个模型，只要 system prompt 不同、工具列表不同，它们就是两个不同的节点。

看一个最简单的定义：

from autogen import ConversableAgent, AssistantAgent, UserProxyAgent assistant = AssistantAgent( name="assistant", system_message="你是一个严谨的架构师，只输出结论和理由。", llm_config={ "config_list": [{"model": "gpt-4o", "api_key": "your_key"}], "temperature": 0.3, }, )

ConversableAgent是它们的公共基类，意味着你既可以用内置的AssistantAgent，也可以继承自定义 Agent。灵活度不错，实际做复杂任务时，我经常在自定义 Agent 里覆写generate_reply来做特殊处理，比如注入外部数据、检查关键词、决定是否终止对话。

另一个容易混淆的概念是UserProxyAgent。它的名字带 User，但它不一定要人工输入，也可以配置成自动执行工具。它的默认行为是：收到消息后，如果需要执行代码，就直接在本机运行，然后把 stdout/stderr 作为新消息发回去。如果配置了human_input_mode="NEVER"，它就变成一个“自动执行者”，适合无人值守的任务。

2.3 设计理念上的三个关键选择

用久了你会发现 AutoGen 的设计者做了几个很有味道的取舍：

第一，对话即控制流。它不搞复杂的图编排，而是用自然语言对话推动流程。一个 Agent 说“我来写代码”，另一个 Agent 说“我负责任务验收”，流程的推进藏在消息里，读起来非常直观。代价是隐私性和确定性稍弱，所以必须自己定好终止条件。

第二，代码优先。UserProxyAgent内部集成了代码执行器，模型输出的 Python 代码可以直接跑。这种“让 Agent 自己动手”的模式，特别适合数据分析和原型验证。我做过一个需求，让 Agent 根据 CSV 文件自动绘制图表，它自己写完 matplotlib 代码执行成功，再根据运行结果调整图表细节，整个过程几乎没有人工介入。

第三，人类可随时插话。即使多 Agent 跑得热火朝天，你也可以通过human_input_mode插入意见，或者用人工输入作为某个 Agent 的回复。这种“人在回路”的能力在生产环境很有价值，比如让 AI 负责草拟内容，人类负责最终拍板。

3. 搭建多智能体协作系统的实操过程

3.1 环境准备与安装依赖

我本地用的是 Python 3.11，安装很简单：

pip install pyautogen

如果你想用最新特性，可以直接装 nightly：

pip install pyautogen[teams] # 包含更多实验性功能，不一定稳定

安装完成后，第一件事是配置模型。AutoGen 支持 OpenAI 兼容接口，所以即使你本地跑的是开源模型，只要暴露成了兼容 API，也能接进来。我最初直接用 OpenAI，后面换成了本地模型做测试，配置方式几乎一样。

# config_list 是 AutoGen 管理模型配置的通用格式 config_list = [ { "model": "gpt-4o", "api_key": "sk-xxxx", "base_url": "https://api.openai.com/v1" # 也可以是本地服务地址 } ] llm_config = { "config_list": config_list, "temperature": 0.4, "timeout": 120, }

这里有个容易踩坑的点：config_list里可以配多个模型备选，AutoGen 会在请求失败或超时时自动切换。我一度以为它是做模型“轮询负载均衡”，后来细看发现它主要做高可用容错。如果你的不同模型能力差异大，建议不要把能力相差很大的模型放同一个列表里，否则同一个任务可能这次是 GPT-4 回复、下次变成小模型回复，效果波动很大。

3.2 先造一个只会“动嘴”的智能体

我先定义一个纯对话的助手，不接任何工具，当作“唠嗑版”。

from autogen import AssistantAgent planner = AssistantAgent( name="Planner", system_message=""" 你是一个项目规划专家。用户会给你一个目标，你负责： 1. 把目标拆解成 3-5 个步骤。 2. 每个步骤标注负责人和验收标准。 3. 不要讨论和计划无关的内容。 """, llm_config=llm_config, ) user_proxy = UserProxyAgent( name="User", human_input_mode="NEVER", max_consecutive_auto_reply=2, is_termination_msg=lambda msg: "TERMINATE" in msg.get("content", ""), )

这里我故意没接工具，让它先跑通最基本的“你问我答”。UserProxyAgent里有一个参数max_consecutive_auto_reply，意思是连续自动回复的次数上限。如果设成 2，那表示在用户没有新指令的情况下，最多自动往下推两轮就停下。

很多人一上来就把这个值设成 10 甚至更大，结果对话跑了好几圈都不停。我的实践经验是：大多数需要收敛的任务，max_consecutive_auto_reply设在 1 到 3 之间就够了，超过 5 就很容易放飞。

启动一次对话：

user_proxy.initiate_chat( planner, message="我要用 AutoGen 搭一个自动写周报的系统，帮我出一份计划。", )

看到输出后，你能明显感觉到 AutoGen 很自然地把“拆解步骤”的任务完成了。这一步的核心不是“哇好神奇”，而是让你理解 Agent 的消息通道：User发消息给Planner，Planner把回复作为新消息发回来，一轮一轮往复，直到触发终止条件。

3.3 让多个智能体真正“聊起来”：GroupChat 与 GroupChatManager

单个 Agent 太寂寞，多智能体才是 AutoGen 的主场。我搭的第一个多智能体场景是一个“模拟评审会”：产品、开发、测试三个角色围绕一个需求讨论。

from autogen import GroupChat, GroupChatManager product = AssistantAgent( name="Product", system_message="你是产品经理，负责描述需求和价值，注意逻辑清晰。", llm_config=llm_config, ) developer = AssistantAgent( name="Developer", system_message="你是技术负责人，分析实现方案和复杂度，直接指出风险。", llm_config=llm_config, ) tester = AssistantAgent( name="Tester", system_message="你是测试负责人，关注验收标准和边界场景。", llm_config=llm_config, ) group_chat = GroupChat( agents=[product, developer, tester, user_proxy], messages=[], max_round=10, # 整个群聊最多 10 轮 speaker_selection_method="auto", # 自动选择下一个发言人 ) manager = GroupChatManager( groupchat=group_chat, llm_config=llm_config, ) user_proxy.initiate_chat( manager, message="我们要做一个内部工具，自动汇总每日错误日志并发到群里，请大家评审。", )

GroupChat是核心容器，它维护消息历史，并决定下一个发言者是谁。speaker_selection_method有几种模式：

• "auto"：让GroupChatManager动态决定下一个发言者。
• "round_robin"：按顺序轮流发言。
• 自定义函数：你可以传入一个选择函数，完全控制发言顺序。

刚开始我推荐用"round_robin"，因为可控性强，每个 Agent 都有均等机会发言，不会出现某个 Agent 一直抢麦。跑通之后再切"auto"，配合不同角色的 system prompt 让模型自己选择谁该说话，对话会更自然。

max_round是群聊总轮次上限，这个非常重要。我建议按任务复杂度定，简单评审 8 轮以内，复杂方案评审 15 轮以内。设定得太高，token 消耗会急剧上升；设定得太低，又可能讨论不出结论。我的经验是先设 15 跑一次，看大概几轮收敛，再下调到合适的值。

3.4 给智能体装上“手”：接入工具函数

多智能体协作最大价值在于：它们不仅会聊，还能干活。AutoGen 通过register_function把 Python 函数暴露给模型调用。

我举个实际例子。我需要一个 Agent 帮我查询服务器当前磁盘使用情况，然后另一个 Agent 负责生成告警报告。于是我先写一个工具函数：

def check_disk_usage(server_ip: str) -> str: """检查服务器磁盘使用率，返回百分比""" # 实际中这里会执行 ssh 或读取监控接口 import random usage = random.randint(40, 95) return f"{server_ip} 当前磁盘使用率：{usage}%" from autogen import register_function register_function( check_disk_usage, caller=developer, # 哪个 Agent 可以调用这个函数 executor=user_proxy, # 由谁来执行 description="检查指定服务器的磁盘使用率", )

注意这里的caller和executor分别是“可以调用该函数”的角色和“执行该函数”的角色。通常caller是AssistantAgent，executor是UserProxyAgent。因为UserProxyAgent有能力真正执行代码和工具。

这看起来很简单，但实际项目里你可以把任意函数塞进去，比如发邮件、写数据库、调用内部 API。我在一个知识库问答系统里，把检索函数注册给了RAGAgent，再由它把检索结果转述给用户，效果比单纯让模型硬记知识库强很多。

一个非常关键的提示：工具函数必须有清晰且简单的docstring，AutoGen 会把函数描述和参数 schema 发给模型。如果描述含糊，模型可能不知道怎么调用或调错参数。我见过不少人工具调用失败，就是因为 docstring 写得太随意。

3.5 终止条件与最大轮次：让我调到头秃的参数

多智能体系统最常见的失控现象就是“聊个不停”。调试终止条件是我花时间最多的地方。

AutoGen 判定对话结束有两种方式：

• 消息中出现指定关键词，比如"TERMINATE"。
• 达到最大轮次max_round。

我推荐双管齐下。先写一个终止函数：

def is_termination_msg(msg): content = msg.get("content", "") if content.strip().upper().endswith("TERMINATE"): return True # 也可以根据内容判断，比如包含“最终结论是” return False user_proxy = UserProxyAgent( name="User", human_input_mode="NEVER", is_termination_msg=is_termination_msg, )

不过要注意：让模型自己输出TERMINATE并不总是可靠。模型可能忘了输出，或者提前输出。所以max_round是最后的兜底，一定要设。

我调参的经验是：给每个 Agent 的 system prompt 里加上明确的收敛要求，比如“当你认为讨论已经达成最终结论时，回复 TERMINATE 并附上结论摘要”。再加一层human_input_mode控制，重要节点让人类确认，这样即使模型误判，人也能拉回。

另外，max_consecutive_auto_reply也很关键。比如一个UserProxyAgent连续执行了 3 次工具调用，还没得到最终结论，如果达到上限就会停下来。这个参数能让对话不无限续杯。

4. 真实案例复盘：我搭的“技术方案评审小分队”

4.1 系统设计：三个 Agent 各司其职

前几天我正好要评审一个新功能的技术方案，就用 AutoGen 搭了一个“评审小分队”。参与 Agent 有四个：产品经理 Agent、架构师 Agent、测试 Agent，以及我自己（通过UserProxyAgent模拟）。它们围绕同一份需求文档，从三个不同视角提出意见，最后输出综合评估。

为什么选这四个角色？

因为一场技术方案评审本来就是这些角色之间的对话。产品经理关心“需求是否被满足”，架构师关心“实现方案是否合理、扩展性怎么样”，测试关心“边界条件和风险”。让这三个 Agent 在一个群里互相提问，比让单个模型同时扮演所有角色更接近真实的评审过程，也更容易暴露矛盾点。

4.2 每个 Agent 的 prompt 配置与心法

我贴一下实际的 system prompt（已脱敏），方便你感受写法：

product_sys = """你是产品经理 Agent，负责从用户价值和需求完整性角度评审技术方案。 要求： - 如果方案没有直接解决用户痛点，必须提出质疑。 - 考虑需求的优先级和投入产出比。 - 回答要简洁，最多 200 字，不废话。 - 在你的疑问被解决后，回复 "产品侧无异议"。""" arch_sys = """你是架构师 Agent，负责从技术角度评估方案可行性和扩展性。 要求： - 指出设计中的风险、复杂度以及备选方案。 - 给出明确的改进建议，不要泛泛而谈。 - 如果认为方案可行，回复 "架构侧无异议"。 - 回答控制在 300 字以内。""" test_sys = """你是测试负责人 Agent，负责从质量保障角度评审方案。 要求： - 找出至少 1 个边界场景或异常情况。 - 验证方案是否有明确的可测试性。 - 如果认为风险可控，回复 "测试侧无异议"。 - 回答控制在 200 字以内。"""

我写 prompt 的心法是：每个 Agent 都要有“自己的立场+输出约束+结束条件”。缺少任何一条，Agent 就容易变成复读机或者跑题。立场决定了它关注什么，输出约束控制了篇幅和风格，结束条件让它可以收敛。

这里还藏着一个细节：角色提示中的“无异议”并不是真正的结束，而是给GroupChatManager一个判断信号。当三个 Agent 都说了“无异议”，再配合后续一轮让用户总结，整个评审就自然收尾了。

4.3 运行过程实录与输出摘要

我挑一段运行过程，给你看真实的流转节奏（已简化）：

User: 现在我们评审新功能"自动日报生成"。该功能每天定时拉取日志，汇总为 Markdown 报告并发送到指定群。 Product: 用户价值明确，但日报的接收人是否可以自定义？如果不能，每个团队都要改代码，成本高。 Architect: 建议把接收人列表做成配置项，用 YAML 管理，避免硬编码。整体方案可行，但定时任务需要处理并发和失败重试。 Tester: 需要考虑日志为空、进程崩溃、以及多个任务同时运行的场景。建议增加一个 dry-run 模式，方便测试。 User: 好的，请各位基于以上意见给出最终评估。 Product: 如果支持配置化接收人，产品侧无异议。 Architect: 架构侧无异议，但需要补充重试策略。 Tester: 测试侧无异议，我会增加边界用例。 Product: 最终结论：采用配置化接收人 + 失败重试 + dry-run 模式。产品侧确认。 Architect: 确认。 Tester: 确认。

你注意到没有，模型会自己根据别人的发言调整观点。整个过程大概 10 轮左右，耗时 2 分钟，token 消耗接近 5 万。如果让我手动写这个评审文档，至少需要一两个小时，而且往往只想到了正面意见。多 Agent 的交叉提问确实能逼出一些容易被忽略的细节。

4.4 资源消耗与成本观察

这个案例用四个 Agent（包含 UserProxyAgent），实际计费按 token 算。我记录了参考数据：

从数据能看出两个趋势：Agent 数量越多、对话轮数越多，token 消耗呈指数级增长。所以我的建议是：

• 能用 3 个 Agent 解决的问题，绝不上 5 个。
• 优先使用本地模型做多轮协作测试，跑通逻辑后再切付费模型。
• 限制max_round和单个 Agent 的输出max_tokens。

成本不光是钱，还有时间。网络请求加上多轮往返，一个复杂对话可能要几分钟。如果你想做试验，最好把timeout设得宽松一些，否则还没聊到一半就超时中断了。

5. 常见问题速查与排错经验

5.1 对话陷入死循环

死循环基本是每个用 AutoGen 的人都会遇到的头号问题。表现就是几个 Agent 来回“你说得对”“我同意”“我也同意”，永远不进入下一阶段。

我排错时按这个顺序来：

1. 检查max_round是否设置为一个有限值，如果没设，默认可能非常大。
2. 检查每个 Agent 的 system prompt 是否明确了结束条件。
3. 检查is_termination_msg是否真的能匹配模型输出的终止词。
4. 检查speaker_selection_method，如果是"auto"，模型可能频繁选择同一个 Agent，然后不断产生相似回复。

有一次我排查了半天，最后发现是is_termination_msg里用的关键词是TERMINATE，但模型输出的是terminate。，有句号，我的判断函数要求字符串相等，自然匹配不上。改成content.upper().endswith("TERMINATE")就解决了。

5.2 上下文越聊越长，直接爆掉

多轮对话会把完整历史传给模型，轮数一多，上下文长度就爆炸。尤其 Agent 用工具执行完代码之后，输出会塞进历史，导致下一次请求越来越大。

对策有几种：

• 设置max_tokens限制每个回复的长度。
• 用summary_method做对话摘要，把旧消息压缩后替代原文。AutoGen 支持在群聊里启用摘要，这样历史不会无限膨胀。
• 在 Prompt 中明确要求“不要重复之前的内容，直接给增量信息”。

我用summary_method="last"的时候比较多，也就是只保留最近的总结消息，避免旧消息塞满上下文。如果你的任务需要保留所有细节，那就只能接受成本，或者换更长上下文的模型。

5.3 工具调用总是“虚假成功”

有时模型会“假装”调用了工具，然后直接编造结果。比如我定义了一个check_disk_usage，模型可能不调用函数，而是在回复里写“磁盘使用率 75%”。这不一定是模型坏，更可能是不确定函数该什么时候用。

我的解决办法有三个：

1. 在 system prompt 中明确写“当需要获取真实数据时，你必须调用工具，禁止自己编造数值”。
2. 在工具函数内部做校验，返回失败信息而不是抛出异常，让模型能够感知异常。
3. 在UserProxyAgent中配置code_execution_config为{"use_docker": False, "work_dir": "workspace"}，让执行过程有迹可循，方便排查。

还有一点，工具函数返回的内容会作为普通消息进入对话，所以尽量让返回结果包含足够的“说话者信息”，比如在返回字符串前加[check_disk_usage]前缀，这样排查消息历史时能看清是工具输出而不是模型自述。

5.4 多智能体答非所问，各说各话

如果几个 Agent 话题漂移，多半是角色职责和上下文的约束不够。speaker_selection_method设为"auto"时，模型有时会突然让一个不相关的 Agent 发言，导致节奏混乱。

我的习惯是先"round_robin"跑通核心逻辑，确认每个 Agent 的输出符合预期；再切"auto"并观察一两次，如果还是乱，就定义自定义发言顺序函数。AutoGen 允许你传一个speaker_selection_method函数，返回下一个发言的 Agent 名字，完全自由控制。

另外，给每个 Agent 的 system prompt 里加上“你只负责XX，不讨论其他问题”能有效减少跑题。这不是限制，而是帮助 Agent 聚焦。

5.5 排错速查表

我把常见问题整理成了速查表，我每次遇到问题都会先对照一遍：

这张表也是我踩了很多坑才总结出来的，你可以直接保存。

最后再分享一个我自己的体会：多智能体系统最容易被忽视的其实是“收敛艺术”。很多人关注怎么让 Agent 有话可说，却忽略了怎么让它适时闭嘴。AutoGen 把控制权交给了开发者，ESL 上讨论很多的问题，都出在终止条件写得太随意。如果你刚开始搭，我强烈建议先用两个 Agent 做一个小闭环，比如“一个出方案、一个挑刺”，跑通之后再往里面加角色，否则一上来就建五六人群聊，除了烧 token，大概率还会收获一群复读机。这套工具的价值在于把对话编排从“胶水代码”里解放出来，但真正的效果上限，还是取决于你对任务边界和角色的理解。