AutoGen多智能体协作实战：从环境搭建到代码生成测试全流程

多智能体协作这个方向，我从去年开始断断续续跟了几个项目，踩过的坑不算少。AutoGen 刚出来那阵子我就拿来跑过几个 Demo，当时第一感觉是"这东西把 Agent 之间对话的抽象做得挺干净"，但真正落到生产级场景时，问题也不少。今天这篇就围绕 AutoGen 这个开源框架，把我自己从环境搭建、核心概念理解、到实际跑通一个多智能体协作流程的完整经验梳理一遍，顺带把那些文档里不会写的坑都摊开讲。

如果你正在评估要不要用多智能体框架来做自动化任务编排，或者已经上手 AutoGen 但被它的对话循环、工具调用、终止条件搞得有点晕，这篇应该能帮你省不少时间。我会尽量用大白话把每个设计决策背后的"为什么"讲清楚，而不是只贴代码。

1. 为什么多智能体框架值得认真对待

1.1 单 Agent 的天花板在哪里

先说清楚一个前提：为什么我们需要多智能体，而不是把一个 Agent 做得足够强就行？

我最早做自动化任务的时候，思路很朴素——写一个超级 Prompt，把任务拆解、执行、校验全塞进去，让一个模型从头干到尾。跑简单任务没问题，但一旦任务链条超过三四步，问题就集中爆发了。最典型的是上下文污染：前面步骤产生的中间结果、错误尝试、无关信息全堆在对话历史里，模型到后面就开始"忘事"或者被带偏。另一个问题是角色混淆：你让同一个模型既当执行者又当审核者，它往往会倾向于认可自己的输出，审核形同虚设。

这就像一个人既写代码又做 Code Review，很难真正挑出自己的毛病。多智能体的核心价值，就是把不同职责拆给不同的 Agent，每个 Agent 有自己的系统提示词、自己的上下文窗口、自己的工具集。执行者只管干活，审核者只管挑刺，规划者只管拆任务。职责一分开，每个 Agent 的 Prompt 可以写得更聚焦，上下文也更干净。

AutoGen 这个框架的设计哲学就建立在这个认知上。它不追求做一个"万能 Agent"，而是提供一套对话驱动的协作机制，让多个 Agent 通过互相发消息来推进任务。这个抽象看起来简单，但扩展性很强。

1.2 AutoGen 的定位与它解决的问题

AutoGen 是微软开源的一个多智能体应用框架，核心能力可以概括成三块：可对话的 Agent 抽象、Agent 之间的消息传递机制、工具与代码执行能力。

它解决的问题很具体：当你需要多个角色协作完成一个任务时，不用自己从零实现消息路由、对话循环、终止判断这些基础设施。框架把这些都封装好了，你只需要定义每个 Agent 的角色和行为，然后让它们"聊起来"。

我个人的判断是，AutoGen 最适合的场景是任务流程相对明确、但需要多轮迭代和校验的自动化任务。比如代码生成加测试、数据分析加报告撰写、多轮问答式的信息提取。它不太适合那种需要极强实时性、或者任务边界极其模糊的场景。

提示：AutoGen 的版本迭代比较快，不同版本之间 API 差异不小。我下面讲的内容基于较新的版本结构，如果你用的是老版本，部分类名和参数可能需要对照官方迁移文档调整。

2. 核心概念拆解：Agent、对话与消息

2.1 ConversableAgent：一切的基础

AutoGen 里最核心的基类是ConversableAgent。顾名思义，就是一个"能对话的 Agent"。它封装了几个关键能力：接收消息、生成回复、执行工具、判断是否终止对话。

你可以把它理解成一个"带状态的消息处理器"。每个 Agent 有自己的name、system_message（系统提示词）、llm_config（模型配置），以及一组可调用的工具函数。当它收到一条消息时，会根据当前配置决定：是直接让模型生成回复，还是先调用某个工具，还是触发终止条件。

这里有个设计细节值得说：AutoGen 把"生成回复"和"执行动作"分成了两个阶段。模型先输出一段内容，框架再解析这段内容里有没有工具调用请求，如果有就执行工具，把结果作为新消息喂回去。这个循环会一直持续到满足终止条件。理解这个两阶段机制，是后面排查问题的关键。

2.2 内置 Agent 类型与它们的适用场景

框架内置了几种常用的 Agent 类型，我按使用频率排一下：

AssistantAgent是最常用的，它默认不执行代码，只负责生成文本。UserProxyAgent则相反，它默认会执行收到的代码块，同时可以配置成"需要人类确认才执行"。这两个搭配起来，就是最经典的"一个出主意、一个动手"的组合。

GroupChatManager是进阶用法。当你有三个以上 Agent 需要协作时，直接两两对话就不够了，需要一个"主持人"来决定每轮谁发言。这个 Manager 本质上也是一个 Agent，它的职责是根据当前对话状态，选择下一个发言者。

2.3 消息传递与终止条件的设计逻辑

AutoGen 的对话是消息驱动的。每条消息有角色（role）、内容（content）等字段。Agent 之间通过initiate_chat或generate_reply来触发对话。

终止条件这块，我踩过坑，重点讲。框架提供了几种终止机制：

• max_consecutive_auto_reply：限制连续自动回复次数，防止无限循环
• is_termination_msg：自定义函数，判断某条消息是否代表任务结束
• 特定关键词触发：比如检测到 "TERMINATE" 就停

我一开始只设了max_consecutive_auto_reply，结果发现两个 Agent 经常在"你说得对""你也说得对"这种客套话里空转，白白烧 token。后来学乖了，一定要配合is_termination_msg，让 Agent 在任务真正完成时输出一个明确的结束标记。

注意：终止条件设计不好，是多智能体应用烧钱的头号原因。我见过一个 Demo 因为没设终止条件，两个 Agent 聊了上百轮，账单直接起飞。

3. 环境搭建与第一个可运行示例

3.1 依赖安装与模型配置

安装本身不复杂，但有几个细节要注意。我建议用虚拟环境，避免和系统里的其他包冲突。

python -m venv autogen_env source autogen_env/bin/activate # Windows 用 autogen_env\Scripts\activate pip install autogen-agentchat autogen-ext[openai]

这里要说明一下，较新版本的 AutoGen 做了模块拆分，核心包和扩展包分开了。autogen-agentchat是核心，autogen-ext里放各种模型客户端和工具集成。如果你只需要基础的对话能力，装核心包就够；要用特定模型或工具，再装对应的扩展。

模型配置这块，我用的是 OpenAI 兼容的接口。配置长这样：

llm_config = { "config_list": [ { "model": "gpt-4o-mini", "api_key": "你的密钥", "base_url": "你的接口地址" } ], "temperature": 0.1, "timeout": 120 }

temperature我一般设得很低，0.1 左右。原因是多智能体协作场景下，我们需要的是稳定可复现的行为，而不是创意发散。温度太高，Agent 容易"脑洞大开"，偏离任务目标。timeout设长一点，因为多轮对话加上工具执行，单次请求耗时可能比较久。

3.2 最小可运行的双 Agent 示例

先跑一个最简单的例子，两个 Agent 一问一答。这个例子的目的是让你理解对话是怎么流转的。

from autogen_agentchat.agents import AssistantAgent from autogen_agentchat.teams import RoundRobinGroupChat from autogen_ext.models.openai import OpenAIChatCompletionClient model_client = OpenAIChatCompletionClient( model="gpt-4o-mini", api_key="你的密钥", base_url="你的接口地址" ) assistant = AssistantAgent( name="assistant", model_client=model_client, system_message="你是一个乐于助人的助手，回答要简洁。" ) user_proxy = AssistantAgent( name="user_proxy", model_client=model_client, system_message="你负责提出问题和判断回答是否满意。" ) team = RoundRobinGroupChat( participants=[user_proxy, assistant], max_turns=4 )

RoundRobinGroupChat是轮询式的群聊，参与者按顺序轮流发言。max_turns限制总轮数，这是最基础的防死循环手段。

跑起来之后你会发现，两个 Agent 会按照 user_proxy → assistant → user_proxy → assistant 的顺序交替发言。这个顺序是固定的，适合流程明确的场景。

3.3 代码执行能力的开启与安全边界

真正让 AutoGen 好用的，是它能执行代码。UserProxyAgent或带代码执行器的 Agent 可以把模型生成的代码真正跑起来，把结果反馈回去。这就形成了一个"生成-执行-观察-修正"的闭环。

但这里有个安全红线必须强调：代码执行意味着模型生成的任意代码都会在你的机器上运行。我强烈建议：

• 开发阶段用 Docker 容器隔离执行环境
• 生产环境绝对不要给 Agent 无限制的本地执行权限
• 对执行的代码做白名单或沙箱限制

我自己的做法是，本地调试时用一个专门的容器，容器里只装必要的依赖，不挂载任何敏感目录。这样即使模型生成了危险代码，影响范围也可控。

4. 实战：搭一个代码生成加自动测试的协作流程

4.1 任务拆解与角色设计

光讲概念没意思，我们做一个完整的实战案例：让多智能体协作完成"写一个函数并自动测试"的任务。

角色设计如下：

• Coder（编码者）：根据需求写代码
• Tester（测试者）：写测试用例并执行，反馈结果
• Reviewer（审核者）：判断代码是否满足需求，决定是否结束

这个三角结构的好处是职责清晰。Coder 只管写，Tester 只管测，Reviewer 做最终裁决。三者互相制衡，避免"自己写自己测自己通过"的问题。

为什么不用两个 Agent？因为两个 Agent 容易陷入"你说行就行"的妥协。加一个独立的 Reviewer，相当于引入了一个裁判，能显著提升输出质量。

4.2 关键配置与参数选择过程

先看 Coder 的配置：

coder = AssistantAgent( name="Coder", model_client=model_client, system_message="""你是一个Python程序员。 根据需求编写函数，代码要包含类型注解和文档字符串。 写完代码后，输出格式为： ```python # 你的代码 ``` 不要写测试，测试交给Tester。""" )

系统提示词里我特意强调了"不要写测试"，因为如果不限制，Coder 会顺手把测试也写了，导致 Tester 无事可做。这种职责边界要在 Prompt 里明确划清，是多智能体设计的一个关键技巧。

Tester 的配置需要开启代码执行：

tester = CodeExecutorAgent( name="Tester", code_executor=DockerCommandLineCodeExecutor( image="python:3.11-slim", timeout=60, work_dir="./test_workspace" ) )

这里用 Docker 执行器，timeout设 60 秒，防止死循环代码卡住。work_dir指定工作目录，所有临时文件都放这里，方便清理。

Reviewer 的配置重点是终止判断：

def check_termination(msg): content = msg.content if hasattr(msg, 'content') else str(msg) return "APPROVED" in content reviewer = AssistantAgent( name="Reviewer", model_client=model_client, system_message="""你审核代码是否满足需求。 如果满足，回复中包含 APPROVED。 如果不满足，指出具体问题。""", )

终止条件用关键词 "APPROVED" 来触发。这个设计简单但有效，比让模型自己判断"任务是否完成"要可靠得多。

4.3 完整流程跑通与结果观察

把三个 Agent 放进一个群聊：

team = RoundRobinGroupChat( participants=[coder, tester, reviewer], max_turns=9 ) result = await team.run( task="写一个函数，输入一个整数列表，返回其中所有偶数的平方和。" )

跑起来之后，你会观察到这样的流程：Coder 先输出代码，Tester 拿到代码后执行并生成测试结果，Reviewer 根据测试结果判断是否通过。如果不通过，Coder 会根据反馈修改，再走一轮。

我实测下来，这种简单任务通常两到三轮就能收敛。第一轮 Coder 写的代码可能有边界问题（比如空列表处理），Tester 测出来后，Reviewer 打回，第二轮就修好了。

这里有个观察值得分享：Tester 的反馈质量直接决定收敛速度。如果 Tester 只报"测试失败"而不说具体哪里失败，Coder 就得靠猜。所以我在 Tester 的提示词里要求它输出完整的错误信息和失败用例，这样 Coder 能精准定位问题。

5. 常见问题与排查技巧实录

5.1 对话不终止怎么办

这是最高频的问题。表现是两个 Agent 无限循环，或者在一个小问题上反复拉扯。

排查思路按顺序来：

1. 先看max_turns或max_consecutive_auto_reply有没有设。没设的话先设上，这是兜底。
2. 再看is_termination_msg的逻辑对不对。常见错误是关键词拼写不一致，比如 Agent 输出 "APPROVED." 带了个句号，你的判断是"APPROVED" in content其实能匹配，但如果判断写成content == "APPROVED"就匹配不上了。
3. 最后看 Prompt。如果 Agent 的系统提示词里没有明确的"何时结束"指令，它可能永远觉得"还能再优化一下"。

我的经验是，终止条件要设计成"显式信号"而不是"隐式判断"。让 Agent 在任务完成时输出一个特定标记，比让框架去猜"这轮对话是不是结束了"要可靠得多。

5.2 工具调用失败与参数错误

工具调用失败通常有两类原因：一是模型生成的参数格式不对，二是工具函数本身的异常没被捕获。

对于第一类，我建议在工具函数的 docstring 里把参数类型和格式写清楚，模型会参考 docstring 来生成参数。参数越明确，出错概率越低。

对于第二类，一定要在工具函数内部做异常捕获，返回结构化的错误信息，而不是让异常直接抛出。因为异常抛出后，整个对话可能就中断了，而返回错误信息的话，Agent 还能根据错误信息自我修正。

def safe_calculator(expression: str) -> str: """计算数学表达式。expression 必须是合法的 Python 数学表达式字符串。""" try: result = eval(expression, {"__builtins__": {}}, {}) return f"计算结果：{result}" except Exception as e: return f"计算失败：{str(e)}，请检查表达式格式。"

注意这里用了受限的eval，禁用了内置函数，这是基本的安全措施。

5.3 Token 消耗过高的优化思路

多智能体应用烧 token 是常态，但可以优化。我总结了几个有效的手段：

其中用不同模型做不同角色这招我觉得最实用。Coder 和 Reviewer 需要较强的推理能力，用大模型；Tester 主要是执行和报告，用小模型完全够。这样整体成本能降不少，效果几乎不受影响。

5.4 常见问题速查表

6. 进阶方向与我的实践体会

6.1 从固定流程到动态编排

前面讲的RoundRobinGroupChat是固定顺序的，适合流程明确的场景。但真实任务往往需要动态决定下一步谁发言。这时候就要用到基于模型选择发言者的机制，让一个 Manager Agent 根据当前状态决定下一个发言者。

这个机制更灵活，但也更难控制。我的建议是，先用固定流程跑通，确认角色设计和提示词没问题，再考虑动态编排。一上来就搞动态，调试成本会高很多。

6.2 人类介入节点的设计

AutoGen 支持在流程中插入人类确认节点。比如代码执行前需要人工批准，或者关键决策点需要人类拍板。

这个能力在实际落地时很重要。完全自动化的多智能体流程，在涉及敏感操作时风险太大。我通常会在"执行代码"和"最终输出"这两个节点设置人工确认，其他环节自动跑。这样既保证了效率，又守住了安全底线。

6.3 我踩过的几个印象深刻的坑

最后分享几个具体的教训。

第一个坑是过度信任模型的自我评估。我早期让一个 Agent 自己判断"任务是否完成"，结果它经常在任务只完成一半时就宣布完成。后来改成独立的 Reviewer 来判断，准确率明显提升。这印证了一个道理：让执行者自己验收，不如让第三方验收。

第二个坑是忽略了消息长度累积。多轮对话下来，历史消息会越来越长，不仅费 token，还会让模型注意力分散。我现在的做法是，在每轮对话后对历史做一次摘要压缩，只保留关键信息。这个改动让长任务的稳定性提升了不少。

第三个坑是工具描述写得太随意。有一次我写了个工具函数，docstring 只有一句话，结果模型调用时参数老是传错。后来把参数说明、格式要求、示例都补上，调用成功率立刻上去了。工具描述其实就是给模型的"使用说明书"，写得越清楚，模型用得越准。

AutoGen 这个框架本身还在快速演进，API 和最佳实践都在变。但底层的那套协作逻辑——角色分工、消息驱动、终止控制——是相对稳定的。把这几个核心概念吃透，不管框架怎么变，你都能快速上手。我个人的建议是，别急着追新特性，先把一个完整的协作流程跑通、跑稳，再逐步加复杂度。多智能体这东西，简单场景下未必比单 Agent 强，但一旦任务需要多角色制衡和迭代校验，它的价值就体现出来了。