AutoGen 实战教程：AgentChat、Teams、Termination 与 v0.2 迁移边界

直接答案：2026 年新写 AutoGen，不应该再从 ConversableAgent + GroupChatManager + human_input_mode + max_round 这套 v0.2 心智模型开始。当前 AutoGen 的主线是 AgentChat 高层 API、Core 事件驱动运行时和 Extensions 集成层；多智能体协作使用 AssistantAgent + Teams，停止条件使用 TerminationCondition。

旧 API 仍然值得保留在迁移章节，因为大量历史代码还在使用它。但把旧 API 和当前 stable 混在一篇“实战教程”里，会让读者连 import path、状态模型和 Human-in-the-loop 该怎么写都判断错。

先决定：真的需要多个 Agent 吗？

AutoGen 官方当前对 Teams 的建议非常清楚：简单任务先优化单 Agent；只有一个 Agent 加 Tools 仍不能很好完成任务时，再使用 Team。

多 Agent 会额外引入：

• 多份 system message 和上下文；
• speaker 选择；
• termination 条件；
• 团队状态保存/恢复；
• 工具权限分配；
• 多 Agent 之间的错误传播；
• 更高 Token 与模型调用成本。

所以“Planner + Coder + Reviewer + Summarizer”不是越多越专业。能用一个 AssistantAgent + 两个清晰工具完成的任务，不要为了架构图好看拆成四个 Agent。

AutoGen 当前三层：AgentChat、Core、Extensions

可以把当前 AutoGen 拆成三层理解：

AgentChat：先从这里开始

适合大多数应用开发。它提供 Agent、Team、Message、Termination、State 等高层抽象。

常见入口包括：

• AssistantAgent
• UserProxyAgent
• RoundRobinGroupChat
• SelectorGroupChat
• Swarm
• GraphFlow

Core：需要底层事件驱动时再用

Core 是更底层的异步、事件驱动 Agent runtime。只有当你需要自定义 actor、消息路由、分布式运行或自己构建更高层框架时，才有必要直接进入 Core。

Extensions：模型客户端和执行器等集成

模型 Provider、代码执行器和其他扩展集成放在 Extensions 中。这样 AgentChat 本身不会绑死一个模型供应商或执行环境。

最小示例：两个 AssistantAgent 的 RoundRobin Team

固定轮转的 Team 最容易理解，也最适合做第一条多 Agent 生产基线：

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat

# model_client 由你的 Provider 配置创建

researcher = AssistantAgent(
    "researcher",
    model_client=model_client,
    system_message="Collect evidence and cite source boundaries. Do not invent facts.",
)

reviewer = AssistantAgent(
    "reviewer",
    model_client=model_client,
    system_message="Review evidence. Reply APPROVE only when requirements are satisfied.",
)

termination = (
    TextMentionTermination("APPROVE")
    | MaxMessageTermination(max_messages=12)
)

team = RoundRobinGroupChat(
    [researcher, reviewer],
    termination_condition=termination,
)

result = await team.run(task="Review this migration plan.")

这里的核心不是“两个 Agent 会聊天”，而是谁能发言、什么时候停止、停止后保存什么状态。

Termination：不要再把 max_round 当成当前主线

旧 v0.2 教程常见 max_round、is_termination_msg。当前 AgentChat 用可组合的 TerminationCondition 表达停止条件。

常见类型包括：

• MaxMessageTermination：限制消息数量；
• TextMentionTermination：检测明确完成词；
• TimeoutTermination：限制运行时间；
• 与 handoff、外部事件或自定义规则组合的 termination。

生产上通常至少同时存在两个条件：业务完成条件 + 硬预算上限。只依赖模型自己输出“TERMINATE”并不稳，因为模型可能漏掉终止词，也可能在任务未完成时提前说完成。

RoundRobin、Selector、Swarm、GraphFlow 怎么选

RoundRobinGroupChat

成员固定轮流发言。优点是可预测、容易做回归测试；缺点是不论当前是否需要某角色，它都会获得轮次。

适合：Reviewer 必须在 Researcher 之后检查的固定协作。

SelectorGroupChat

根据上下文选择下一位 speaker。适合角色较多、每一步不一定需要所有角色的场景。

它比 RoundRobin 更灵活，但需要更好的：

• 角色 description；
• selector prompt；
• candidate 限制；
• termination；
• 选择错误的观测指标。

Swarm

适合明确的 agent handoff。一个 Agent 完成自己的责任后把控制权交给另一个 Agent。

GraphFlow

当工作流本身已经有清晰方向、依赖或分支时，GraphFlow 比“让模型自由选 speaker”更合适。越接近审批、事务、固定工程管线，越应该显式表达拓扑。

当前 UserProxyAgent：不要再复制 human_input_mode

在 v0.2，UserProxyAgent 常与：

human_input_mode="ALWAYS" | "TERMINATE" | "NEVER"
max_consecutive_auto_reply=...

一起出现。

当前 AgentChat 的 UserProxyAgent 更直接：它是一个获取用户输入的 Agent，可以通过 input_func 自定义同步/异步输入方式。

真正需要注意的是生产等待边界。如果人工可能几分钟、几小时甚至几天后才回复，不要让一个请求或 Worker 一直阻塞。更稳的设计是：

1. Team 在 handoff / termination 边界停止；
2. 保存 Team state 和业务 approval_id；
3. Worker 退出；
4. 人工完成审批；
5. 后续请求加载 state 并继续。

状态恢复：Team state 不是业务事务日志

AutoGen AgentChat 可以保存和加载 Agent/Team 状态，但这不意味着业务副作用自动 Exactly-once。

生产状态至少分三层：

• AutoGen state：Agent / Team 的内部运行上下文；
• 业务 workflow state：pending / approved / rejected / expired / completed；
• side-effect ledger：外部邮件、支付、发布、数据库写入是否已经执行。

恢复 Team 前应该重新检查：工具版本、权限、approval 是否过期、幂等键是否已经命中。

工具权限：不要给整个 Team 一套全权限 Tools

多 Agent 最大的真实风险之一不是“角色说错话”，而是多个 Agent 都能执行高风险动作。

一个更稳的分配是：

• Researcher：只读检索；
• Planner：读业务上下文，不写生产；
• Executor：只获得当前任务需要的受控写 Tool；
• Reviewer：只读证据和测试结果；
• 发布/删除/支付：单独 approval gate。

即便 Selector 误选了 Agent，最小权限也能把故障限制在较小范围。

v0.2 到当前 API：哪些东西不能混写

v0.2 常见写法	当前教程应该怎么处理
ConversableAgent	只放迁移背景；新项目优先 AgentChat Agent
GroupChatManager	只放迁移背景；当前使用 Teams
human_input_mode	v0.2 UserProxy 配置；当前改为新的 UserProxyAgent / input_func 模型
max_round	旧 GroupChat 轮数限制；当前用 Termination Conditions
is_termination_msg	旧式终止判断；当前用可组合 TerminationCondition
pyautogen	不应作为 Microsoft 当前包来源；按官方 migration 文档选择包

官方 migration guide 明确指出 v0.2 到 v0.4 是 breaking rewrite，而且 pyautogen 在 0.2.34 之后的发布不再由 Microsoft 控制。历史 v0.2 项目如果必须继续维护，应按官方说明固定正确包来源，不要混装。

AutoGen 和 Microsoft Agent Framework 怎么看

Microsoft 现在提供从 AutoGen 迁移到 Microsoft Agent Framework 的官方迁移指南，并将 Agent Framework 作为新的多语言 Agent/Workflow SDK 方向。

这不意味着现有 AutoGen 应用必须立刻重写。更实用的决策顺序是：

1. 先隔离 model client、tool、state、approval 和 orchestration；
2. 确认当前 AutoGen 版本仍能满足业务；
3. 用一条真实工作流做 Agent Framework 对照迁移；
4. 比较 API 稳定性、恢复语义、Azure/Entra/Foundry 集成、维护成本；
5. 有明确收益再逐步切换。

“框架更新了”不是迁移理由，降低维护风险或获得明确能力才是。

FAQ

多 Agent 一定比单 Agent 准吗？

不一定。多个 Agent 会增加独立模型调用、上下文传递和错误传播路径。应该通过任务成功率、工具错误率、平均模型调用次数、Token 成本、人工介入率和最终验收率来判断。

SelectorGroupChat 能不能直接替代业务状态机？

不建议。Selector 解决“下一位谁说话”，不等于订单、审批或支付状态机。强业务约束仍应存在显式 workflow/database 中。

继续阅读

• AI Agent 框架选型：LangGraph、Google ADK、AI SDK 与 Microsoft Agent Framework
• AI Agent 全栈指南
• LangGraph Human-in-the-loop 审批流
• AI Agent Tool Authorization Policy Gate

专题入口 / AI Agent Hub

从单个 Agent 问题继续进入完整生产体系

AI Agent 专题统一组织架构、记忆、工具调用、评测、安全、部署和多智能体协作，让每篇文章都回到明确的主题主页面。

进入 AI Agent 专题 → 查看架构指南 订阅