autogen

AutoGen 专家技能

此技能面向 Python 3.10+ 上的 AutoGen AgentChat 0.7.5 API。AutoGen（由 Microsoft Research 开发）是一个用于对话式多 Agent AI 的框架。与 LangGraph 的显式图拓扑或 CrewAI 的基于角色的团队不同，AutoGen 将 Agent 间对话作为编排的基本单元。Agent 通过结构化聊天进行通信，并内置群聊路由、人工输入和代码执行模式。

核心范式

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(model="gpt-4o-mini")

assistant = AssistantAgent(
    name="assistant",
    system_message="You are a helpful assistant.",
    model_client=model_client,
)

AgentChat 0.7.5 中的角色划分： UserProxyAgent 代表人类，并通过 input_func 获取回复。CodeExecutorAgent 使用 CodeExecutor 执行代码块。它们是不同的 Agent；两者都不接受旧版 human_input_mode 选项。

核心原则

1. 对话是编排的基本单元。 Agent 发送消息、接收回复，对话结构决定工作流。
2. 将人工输入与代码执行分开。 使用 UserProxyAgent 代表人类参与者；使用配合 CodeExecutor 的 CodeExecutorAgent 执行代码。
3. GroupChat 在 Agent 之间路由。 RoundRobinGroupChat 按固定顺序轮流发言。SelectorGroupChat 使用大模型选择下一位发言者。
4. 嵌套聊天用于委派工作。 一个 Agent 可以启动专家 Agent 之间的子对话，并返回结果。
5. Docker 是安全的代码执行模式。 本地代码执行（LocalCommandLineCodeExecutor）会在你的计算机上运行由大模型生成的代码——生产环境中请使用 Docker。
6. 取消令牌可停止失控的 Agent。 对于长时间运行的任务，始终传入 CancellationToken。

从哪里开始

你已有……	从这里开始
什么都没有——正在探索 AutoGen	创建助手聊天，或创建一个包含人工 UserProxyAgent 的团队
需要协同工作的 Agent	使用多个 Agent 构建 GroupChat
需要执行代码的 Agent	配置 Docker 代码执行器
复杂的多步骤任务	使用嵌套聊天处理子任务

快速参考

任务	方法	参考
人在回路中的聊天	AssistantAgent + UserProxyAgent	references/agent-types.md
多 Agent 群组	使用 RoundRobinGroupChat 的 GroupChat	references/group-chat.md
代码执行	DockerCommandLineCodeExecutor	references/code-execution.md
工具集成	register_function() 或 @tool	references/tool-integration.md
嵌套聊天	AgentTool 或由工具启动的团队运行	references/conversation-patterns.md
取消	CancellationToken	references/conversation-patterns.md
MCP 工具	McpWorkbench	references/tool-integration.md

框架选择指南

场景	选择	原因
对话驱动的多 Agent	AutoGen	原生支持 Agent 间聊天编排
基于角色的多 Agent 团队	CrewAI	Role/Goal/Backstory 是其原生抽象
状态机式多 Agent	LangGraph	图拓扑、子图、人在回路中
链/Agent 组合	LangChain	LCEL 管道运算符适用于通用链

参考文件

参考	何时加载	文件
Agent 类型	AssistantAgent、UserProxyAgent	references/agent-types.md
对话模式	收发消息、嵌套聊天、取消	references/conversation-patterns.md
群聊	RoundRobin、Selector、MagenticOne	references/group-chat.md
代码执行	Docker、本地执行、取消令牌	references/code-execution.md
工具集成	register_function、@tool、MCP 集成	references/tool-integration.md
v0.4 迁移	v0.2->v0.4 迁移、AgentTool、流式处理、终止	references/v04-migration.md
验证审查	对所有 API 声明进行研究验证	references/validation-audit.md
常见问题与故障排除	常见错误及修复方法	references/faq-and-troubleshooting.md

在此技能目录中运行 python -m pip install -r requirements.txt，安装模板使用的确切软件包版本。代码执行示例使用 Docker，需要 Docker 守护进程正常运行。

模板

模板	适用场景	文件
双 Agent 聊天	助手 + 人工输入	templates/two-agent-chat.py
群聊	带发言者路由的多 Agent 团队	templates/group-chat.py
代码执行 Agent	助手 + Docker 支持的代码执行器	templates/code-execution.py

故障排除

症状	可能原因	修复方法	参考
Agent 无限循环	团队没有终止条件	添加 TerminationCondition，例如 MaxMessageTermination	references/conversation-patterns.md
代码执行失败	Docker 未运行	启动 Docker，或使用 LocalCommandLineCodeExecutor	references/code-execution.md
嵌套聊天始终不返回	未传递取消令牌	传递带超时设置的 CancellationToken	references/conversation-patterns.md
v0.2 代码无法运行	v0.4 API 已更改	按照迁移指南操作	references/faq-and-troubleshooting.md
GroupChat 发言者选择陷入循环	SelectorGroupChat 未明确指定下一位发言者	固定顺序时使用 RoundRobinGroupChat	references/group-chat.md
UserProxyAgent 等待输入	它是人工参与者，其 input_func 正在等待	提供合适的输入函数，或使用自动化 Agent	references/agent-types.md

何时不应使用 AutoGen

• 简单的单 Agent 任务 — 功能过剩，请直接调用 API
• 需要细粒度的图控制 — 使用 LangGraph
• 需要具有固定流程的基于角色的团队 — 使用 CrewAI
• 需要链式组合 — 使用 LangChain LCEL