AutoGen多智能体配置：用GroupChat和角色分工搭一个可运行团队
AutoGen 的多智能体配置，本质是把一个任务拆给几个角色明确的 AssistantAgent，再用 GroupChat 管理谁先发言、谁总结，最后由 GroupChatManager 驱动整场对话。
只要角色、发言顺序和终止条件三件事配好，就能在本地跑起一个可用的协作团队。
下面按安装、编写配置、运行验证、避坑的顺序展开，适合刚接触 AutoGen、想先跑通最小多智能体流程的读者。
先确认运行环境和依赖
建议使用 Python 3.9 及以上版本，并单独建一个虚拟环境，避免和系统里其他包冲突。
python -m venv autogen-env
source autogen-env/bin/activate # Windows 用 autogen-env\Scripts\activate
pip install -U autogen-agentchat autogen-ext[openai]安装完成后，用 pip show autogen-agentchat 确认包已存在。
AutoGen 的包结构在不同版本间有调整，如果导入时报 ModuleNotFoundError，先检查安装的包名是否与当前版本一致，不要直接照搬旧教程里的 import autogen。
模型调用需要 API Key。
以 OpenAI 兼容接口为例，在环境变量里配置：
export OPENAI_API_KEY="你的密钥"如果用的是国内兼容 OpenAI 协议的服务，还需要在客户端配置里指定 base_url，否则请求会发到默认地址而失败。
定义角色并配置 GroupChat
多智能体配置的关键不是堆角色，而是让每个角色的职责单一、可判断。
下面是一个最小可运行示例，包含一个负责拆解任务的规划者、一个负责执行的工程师，以及一个负责收尾的总结者。
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_ext.models.openai import OpenAIChatCompletionClient
async def main():
model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")
planner = AssistantAgent(
name="planner",
model_client=model_client,
system_message="你负责把用户任务拆成 3 到 5 个可执行步骤，只输出步骤列表。",
)
engineer = AssistantAgent(
name="engineer",
model_client=model_client,
system_message="你根据步骤给出具体实现方案或代码片段，不要重复拆解任务。",
)
reviewer = AssistantAgent(
name="reviewer",
model_client=model_client,
system_message="你检查方案是否完整，最后输出一段总结。看到总结任务后回复 TERMINATE。",
)
team = RoundRobinGroupChat(
participants=[planner, engineer, reviewer],
max_turns=6,
)
result = await team.run(task="用 Python 写一个读取 CSV 并统计行数的小脚本")
for msg in result.messages:
print(msg.source, ":", msg.content)
asyncio.run(main())这里用 RoundRobinGroupChat 按固定顺序轮流发言，适合流程确定的场景。
如果角色需要根据内容决定下一个发言者，可以改用 SelectorGroupChat，并配置选择策略；
更老版本的 GroupChat + GroupChatManager 写法仍然存在，但新项目建议先确认当前版本文档中的推荐方式，避免混用两套 API。
角色配置的三个要点：
name必须唯一，后续发言顺序和日志都靠它区分。system_message要写清“只做什么”和“不做什么”，否则多个角色容易输出重复内容。max_turns是防止死循环的第一道保险，建议先设小一点，跑通后再放宽。
运行、观察与结果验证
保存为 team_demo.py 后执行：
python team_demo.py预期结果是依次打印 planner、engineer、reviewer 的发言，且 reviewer 最后给出总结。
验证时重点看三件事：
- 每个角色的输出是否符合
system_message的约束，有没有越权。 - 对话是否在
max_turns内结束，没有出现同一角色反复说同一句话。 - 模型调用是否成功，若报鉴权错误，先检查
OPENAI_API_KEY和base_url。
如果输出为空或角色没有按顺序出现，先打印 result.messages 的长度和 source 字段，确认消息是否真的进入团队，而不是只看终端最后一行。
常见报错与配置避坑
导入模块失败：AutoGen 新旧版本包名不同，先确认 pip show autogen-agentchat 的结果，再对照当前版本示例调整导入路径。
API 鉴权失败或超时：检查密钥是否写入当前终端会话，代理或 base_url 是否指向可用地址。
不要在多智能体代码里硬编码密钥，统一走环境变量。
对话停不下来：只靠提示词写“请结束”并不可靠，必须同时设置 max_turns；
需要更严格终止时，在角色回复中约定固定结束词，并在外层判断。
角色输出重复：通常是 system_message 职责重叠。
把“拆解”“实现”“审核”拆开写，并明确每个角色不做什么，比增加角色数量更有效。
费用和耗时上升：每轮发言都是一次模型调用，角色越多、轮次越多成本越高。
调试阶段先用小模型和较少轮次，确认流程后再替换模型。
什么时候适合用多智能体
任务需要分阶段判断、多人视角互相检查时，多智能体配置才有明显价值，例如方案拆解加实现加审核。
如果只是单轮问答或简单文本处理，单 Agent 更省成本也更好排错。
先把两个角色的流程跑通，再逐步增加角色，比一开始就堆五六个角色更容易定位问题。
AutoGen 多智能体配置的落地顺序可以记成一句话：装对包、写清角色、选对团队类型、设好轮次上限、用日志验证。
按这个顺序执行，大多数配置问题都能在本地复现并解决。
