Microsoft AutoGen · 对话式多 Agent 协作框架 · 原理学习、本地运行与迁移说明全指南

项目仓库： https://github.com/microsoft/autogen

代码协议：MIT（文档 CC-BY 4.0） · 运行时：Python 3.10 及以上（另提供 .NET 生态包） · 运行形态：Python 库 / AutoGen Studio 本地图形界面（默认端口 8080） · 常驻模型服务：无（调用外部模型接口） · 分支：main（命令、包名与端口以官方仓库最新说明为准）

⚠️ 归档状态前置声明（务必先读）：根据当前官方 README，microsoft/autogen 仓库已归档（Archived），Microsoft 不再主动维护：不提供 Bug 修复、安全修复、新特性或官方支持；仓库仅保留用于历史参考。官方同时提示：缺乏持续维护与安全修复时，项目及其依赖中的漏洞可能长期存在，继续使用会抬高安全风险，尤其在处理敏感数据时应谨慎评估；AutoGen 面向研究与实验设计，官方持续建议不要将其用于生产环境。新项目请使用后继框架 Microsoft Agent Framework；现有 AutoGen 用户可参考官方迁移指南从 AutoGen 迁移到 MAF。本文档用于梳理该框架的历史架构、编排原理与最小可运行示例，供学习与迁移对照使用。

1 项目简介

AutoGen 最初由 Microsoft Research 发起，是一个用于构建多智能体 AI 应用的框架：Agent 可以自主行动，也可以与人协作。框架以可分层、可扩展的方式设计——高层 API 便于快速原型，低层组件保留灵活控制力——在多 Agent 对话编排、工具调用、代码执行与原型可视化方面影响了后续一大批 Agent 框架。

当前仓库内的包采用分层结构：

• Core API：实现消息传递、事件驱动 Agent、本地与分布式运行时，支持 Python 与 .NET 跨语言互操作；
• AgentChat API：在 Core 之上提供更简洁、约定明确的快速原型 API，支持双 Agent 对话、群组聊天等常见多 Agent 模式，也是 v0.2 用户最熟悉的一层；
• Extensions API（autogen-ext）：提供一等公民与第三方扩展，包括 OpenAI、Azure OpenAI 等模型客户端，以及代码执行等能力。

配套的开发者工具包括 AutoGen Studio（无代码图形界面，用于搭建和运行多 Agent 工作流原型）与 AutoGen Bench（Agent 性能评测套件）。仓库内还包含 Magentic-One 等基于 AgentChat 与 Extensions 构建的多 Agent 团队示例。

后继项目提示：官方 README 明确，Microsoft Agent Framework（MAF）是 AutoGen 的企业级后继产品，提供稳定 API、长期支持、多厂商模型、通过 A2A 与 MCP 的跨运行时互操作；新建项目应从 MAF 开始，而非在归档的 AutoGen 上继续投入生产开发。

1.1 核心信息一览

1.2 适用场景

• 学习多 Agent 对话编排历史范式：双 Agent 对话、群组聊天（RoundRobin、Selector 等终止条件）、Agent 作为工具（AgentTool）被主 Agent 调用等经典模式。
• 研究与课程实验：在隔离实验环境中复现 AgentChat 示例、体验消息传递与事件驱动运行时的结构。
• 对照迁移：现有 AutoGen v0.2 / 新版代码需要梳理 API 对应关系，评估迁移到 Microsoft Agent Framework 的工作量。
• 快速原型可视化：用 AutoGen Studio 在画布上拖拽组装团队、模型、工具与终止条件，观察执行轨迹（官方定位为原型工具，不是生产应用）。

1.3 能力边界（官方口径与归档提示）

• 官方 README 明示：仓库归档后不再提供 Bug 修复、安全修复、新功能或支持；依赖漏洞与兼容性问题可能长期无人处理。
• AutoGen Studio 是原型工具：官方注明它用于快速搭建多 Agent 工作流原型并演示终端用户界面样例，不是生产就绪应用；开发者若要落地应用，需自行实现认证、安全与生产所需的其他能力。
• 框架不提供模型本身，也不附带模型 Key；示例默认调用 OpenAI API，需自备密钥。
• 仓库处于社区维护状态，Discord 与 GitHub Discussions 的响应可能有限；功能开发应转向 Microsoft Agent Framework。
• 官方安全提示：只连接可信的 MCP 服务器——不可信的 MCP 服务可能在本地环境执行命令或暴露敏感信息。
• Microsoft、Windows、Microsoft Azure 等名称与徽标属于微软商标；框架许可证不授予使用微软名称、Logo 或商标的权利。

2 功能特性

2.1 分层 API：从快速原型到底层运行时

• AgentChat：AssistantAgent、群组聊天、终止条件、控制台流式输出等高层抽象，适合快速上手；
• Core：消息、事件、本地与分布式运行时，支持 Python 与 .NET；
• Extensions：模型客户端与代码执行等可插拔能力，随生态持续扩展。

2.2 Agent 与工具调用

• AssistantAgent 可配置 system_message、description、tools、model_client_stream、max_tool_iterations 等参数；
• 支持把一个 Agent 包装为 AgentTool 供主 Agent 按需调用，实现“专家 Agent 团队”式编排；
• 支持 MCP 服务器挂载（如 Playwright MCP），以 McpWorkbench 与 StdioServerParams 描述本地标准输入输出型服务。

2.3 多 Agent 编排模式

• 双 Agent 对话、群组聊天、轮询 / 选择器团队等模式在 AgentChat 层提供；
• 终止条件（如最大消息数 MaxMessageTermination）控制团队运行边界；
• Magentic-One 是基于本框架构建的多 Agent 团队示例，覆盖网页浏览、代码执行、文件处理等任务类型。

2.4 人机协作与人在环

• 框架支持人类参与对话环节；AutoGen Studio 内置 huma_in_loop_team 等默认团队样例，用于演示人工审批节点。

2.5 AutoGen Studio 无代码原型

• 浏览器内 Team Builder 画布：新建团队、从组件库拖入 Agent、模型、工具与终止条件；
• Playground 调试运行，Gallery 浏览默认团队样例，Deploy 面板查看导出选项；
• 侧边栏包含 Teams 列表、Recents、Gallery 与 Settings，界面语言与版本以当前 Studio 版本为准。

2.6 评测工具与跨语言生态

• AutoGen Bench 提供 Agent 性能评测套件；
• Core 层支持 .NET 包体系（Contracts、Core、Core.Grpc、RuntimeGateway.Grpc，见 NuGet 条目）；
• 官方文档站提供 Python、.NET、Studio 三条安装、快速开始、教程与 API 参考入口。

3 官方界面预览

3.1 框架生态分层图

下图为官方 README 的生态示意图：开发工具侧为 Studio 与 Bench；框架层由 Core、AgentChat、Extensions 组成；应用层可基于框架构建 Magentic-One 或自有应用。

3.2 AutoGen Studio Team Builder

下图（仓库 autogen-studio 文档截图）展示 Studio 的 Team Builder 主界面：左侧为 Teams 列表与 Gallery，中间是组件库（Agents、Models、Tools、Terminations），右侧画布以团队节点为中心，连接 Agent 节点、Model 节点与终止条件节点。截图底部标注版本号与“Maintained by the AutoGen Team”字样，版本号随发布变化，以实际安装为准。

4 官方跳转链接汇总

下表列出项目相关的官方入口，均可直接点击访问。

5 前置要求与本地环境准备

5.1 软件前提

• Python 3.10 或更高版本：官方 README 明确要求；用 python --version 确认。

• 模型服务凭据：示例默认调用 OpenAI API，先在模型服务商处获取密钥，并以环境变量导出：

  export OPENAI_API_KEY="sk-..."

  其他模型接入方式（Azure OpenAI 等）见官方模型文档。

• Node.js（仅 MCP 示例需要）：Playwright MCP 示例需要先全局安装 MCP 服务器：

  npm install -g @playwright/mcp@latest

• AutoGen Studio（可选）：需要单独安装 autogenstudio 包；原型运行在本机浏览器。

• 网络访问：需要能连通所选模型接口；MCP 服务器在本地或可信远程环境运行。

5.2 硬件与系统建议（官方口径）

5.3 端口与目录分配

6 方式一：Python 包安装与最小示例运行（框架入门）

AutoGen 是 Python 库框架，无常驻后端服务端，官方未提供一键 Compose 部署文件；本章按官方 README 的 pip 安装流程如实编写，不虚构容器编排。

6.1 安装 AgentChat 与 OpenAI 扩展

# 安装 AgentChat 与 OpenAI 客户端扩展
pip install -U "autogen-agentchat" "autogen-ext[openai]"

当前稳定版本号以仓库 Releases 页面为准；从 v0.2 升级时先阅读官方 v0.2 迁移指南。

6.2 Hello World 最小示例

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")
    agent = AssistantAgent("assistant", model_client=model_client)
    print(await agent.run(task="Say 'Hello World!'"))
    await model_client.close()

asyncio.run(main())

6.3 MCP 服务器工具示例（Playwright 浏览助手）

先完成第 5.1 节的 npm install -g @playwright/mcp@latest，然后运行：

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")
    server_params = StdioServerParams(
        command="npx",
        args=[
            "@playwright/mcp@latest",
            "--headless",
        ],
    )
    async with McpWorkbench(server_params) as mcp:
        agent = AssistantAgent(
            "web_browsing_assistant",
            model_client=model_client,
            workbench=mcp,  # 多个 MCP 服务器时传入列表
            model_client_stream=True,
            max_tool_iterations=10,
        )
        await Console(agent.run_stream(task="Find out how many contributors for the microsoft/autogen repository"))


asyncio.run(main())

官方警告：只连接可信 MCP 服务器，不可信服务器可能在本机执行命令或泄露敏感信息。

6.4 多 Agent 编排：AgentTool 专家团队示例

import asyncio

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


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")

    math_agent = AssistantAgent(
        "math_expert",
        model_client=model_client,
        system_message="You are a math expert.",
        description="A math expert assistant.",
        model_client_stream=True,
    )
    math_agent_tool = AgentTool(math_agent, return_value_as_last_message=True)

    chemistry_agent = AssistantAgent(
        "chemistry_expert",
        model_client=model_client,
        system_message="You are a chemistry expert.",
        description="A chemistry expert assistant.",
        model_client_stream=True,
    )
    chemistry_agent_tool = AgentTool(chemistry_agent, return_value_as_last_message=True)

    agent = AssistantAgent(
        "assistant",
        system_message="You are a general assistant. Use expert tools when needed.",
        model_client=model_client,
        model_client_stream=True,
        tools=[math_agent_tool, chemistry_agent_tool],
        max_tool_iterations=10,
    )
    await Console(agent.run_stream(task="What is the integral of x^2?"))
    await Console(agent.run_stream(task="What is the molecular weight of water?"))


asyncio.run(main())

更复杂的群组编排与工作流请阅读官方 AgentChat 文档。

6.5 安装并启动 AutoGen Studio（可选原型工具）

# 安装 Studio 包
pip install -U "autogenstudio"

# 在 http://localhost:8080 启动，应用目录为 ./my-app
autogenstudio ui --port 8080 --appdir ./my-app

浏览器访问 http://localhost:8080，在 Team Builder 中新建团队并从组件库拖入 Agent、模型、工具与终止条件后运行调试。官方提示：Studio 仅用于原型演示，不包含生产环境所需的认证、安全加固与部署能力。

7 方式二：源码克隆与本地开发

7.1 克隆仓库

git clone https://github.com/microsoft/autogen.git
cd autogen

仓库内 Python 包位于 python/packages/（autogen-core、autogen-agentchat、autogen-ext、autogen-studio、agbench 等），.NET 包位于 dotnet/ 目录。具体包管理、测试命令与贡献规范以仓库 CONTRIBUTING.md 当前内容为准；归档状态下贡献仅接受缺陷修复、安全补丁与文档改进。

7.2 本地可编辑安装（按包目录分别执行）

以 autogen-agentchat 为例，在对应包目录内按 Python 项目常规方式安装可编辑版本；具体构建与依赖命令以仓库各包 pyproject.toml 与文档说明为准，不在本文凭印象补全。

7.3 阅读源码的推荐路径

1. 先读 python/packages/autogen-agentchat/ 下的 Agent 与团队实现，理解 AssistantAgent、团队类型与终止条件；
2. 再读 python/packages/autogen-core/ 的消息与运行时抽象；
3. 最后浏览 python/packages/autogen-ext/ 的模型客户端与工具扩展；
4. 对照 Studio 目录理解可视化原型如何调用 AgentChat 层。

7.4 迁移到后继框架的准备

新建项目直接基于 Microsoft Agent Framework 开发；现有代码先阅读官方 AutoGen → MAF 迁移指南，梳理 Agent、团队、工具与模型客户端的对应关系后分模块迁移。

8 配置项说明

8.1 模型客户端与运行参数

8.2 MCP 服务器参数（StdioServerParams）

8.3 Studio 启动参数

8.4 模型与扩展包选型

以上字段名与包名来自当前官方 README 与文档站；归档后不再随版本更新，实际安装时以 PyPI 包元数据与源码注释为准。

9 常用运维命令

9.1 安装与版本核对

# 安装核心包与 OpenAI 扩展
pip install -U "autogen-agentchat" "autogen-ext[openai]"

# 安装 Studio（可选）
pip install -U "autogenstudio"

# 核对已安装版本（版本号以 PyPI 与 Releases 为准）
pip show autogen-agentchat autogen-ext autogenstudio

9.2 运行示例

# 脚本方式运行（示例保存为 hello.py）
python hello.py

# 启动 Studio 原型界面
autogenstudio ui --port 8080 --appdir ./my-app

9.3 环境与会话检查

# 确认模型密钥已导出
echo "${OPENAI_API_KEY:+已设置}"

# 查看 Python 版本是否 >=3.10
python --version

9.4 归档状态下的维护建议

• 不要在归档仓库上申请新特性；缺陷修复与安全补丁范围以官方说明为准。
• 定期检查运行时依赖（pip list --outdated）是否存在已知漏洞，实验环境优先隔离运行。
• 团队配置、Studio 产物目录按需备份；迁移到 MAF 时保留现有 Agent 提示词、工具清单与终止条件定义作为迁移输入。

10 常见故障排查

10.1 导入 autogen_agentchat 失败

现象：ModuleNotFoundError: autogen_agentchat。 排查：确认已安装 autogen-agentchat 且 Python 版本 ≥3.10；检查当前激活的虚拟环境是否与安装命令一致；必要时按 autogen-ext[openai] 方式补装模型扩展，避免只装 AgentChat 而缺少客户端。

10.2 模型认证失败（401 / 403）

现象：Agent 启动后调用模型返回认证错误。 排查：确认 OPENAI_API_KEY 已导出且未过期；脚本运行终端与 pip 安装终端处于同一环境；使用 Azure 或其他提供商时按官方模型文档替换对应客户端配置，不要混用环境变量名。

10.3 模型名不被支持或无权限

现象：返回模型不存在、无访问权限或模型下线提示。 排查：核对 model="gpt-4.1" 等名称在所选服务商处确实可用；切换为账户有权限的模型；完整支持清单见官方模型文档页面。

10.4 MCP 工具启动失败

现象：McpWorkbench 启动时报命令找不到或服务器初始化超时。 排查：先在终端单独执行 npx @playwright/mcp@latest --headless 验证服务器可运行；确认 Node.js 与 npx 已安装；核对 command 与 args 拼接后的命令在本机可执行；只使用来源可信的 MCP 服务器。

10.5 工具调用循环不停止

现象：Agent 反复调用工具不结束。 排查：设置合理的 max_tool_iterations；为团队配置明确的终止条件（如最大消息数）；检查 system_message 是否给出了清晰的完成标准。

10.6 Studio 启动后页面打不开

现象：autogenstudio ui 命令执行后浏览器无法访问 localhost:8080。 排查：确认端口未被占用；查看终端输出中的实际监听地址；远程服务器上不要直接暴露 8080，通过 SSH 隧道或带认证的反向代理访问；确认 --appdir 目录存在且有写权限。

10.7 从 v0.2 升级后代码报错

现象：旧版 AssistantAgent、GroupChat 等导入路径或参数在新版不兼容。 排查：先读官方 v0.2 迁移指南，按新包划分（autogen-agentchat / autogen-ext）调整导入语句与模型客户端构造方式；不要在旧环境上直接 pip install -U 覆盖依赖而不做回归测试。

10.8 归档后遇到安全公告无官方补丁

现象：依赖链披露 CVE 或供应链问题，但仓库不再跟进修复。 排查：将实验环境与生产网络隔离；用依赖审计工具排查受影响组件；能升级的传递依赖单独升级；敏感数据场景直接迁移到 MAF 等受支持框架，不要长期停留在归档项目上。

11 风险与合规说明

• 归档与停维风险（最高优先级）：microsoft/autogen 已归档，官方不再提供 Bug 修复、安全补丁、新特性与支持；框架及其依赖中的已知漏洞可能长期存在。官方明确建议不要在生产环境使用 AutoGen，尤其不要用于敏感数据处理；本文所述示例仅用于历史架构学习、研究实验与迁移对照。
• 后继框架选择：新建项目请直接使用 Microsoft Agent Framework；现有 AutoGen 代码按官方迁移指南分模块迁移，保留 Agent 提示词、工具与终止条件定义作为迁移基线。
• 许可证：代码以 MIT 许可证发布，使用时保留版权与许可声明；文档内容采用 CC-BY 4.0 署名许可；Microsoft、Windows、Azure 等名称与徽标为微软商标，许可证未授予相关商标使用权。
• 模型与数据隐私：任务描述、对话内容与工具结果会发送到所选模型服务商；使用第三方商业模型须遵守其服务条款；在隔离环境中调试示例，避免把未公开代码或客户数据送入实验流程。
• MCP 与工具安全：只挂载可信工具与 MCP 服务器；工具可能访问本地文件系统、网络与执行命令，运行前审查工具参数与权限；Studio 原型界面没有生产级认证与权限隔离，不要对公网开放。
• AI 产出审查：Agent 生成的代码、分析与方案属于辅助产物，可能包含错误或不安全实现；进入任何正式环境前必须由开发者审查、测试与重构。
• 文档时效：本文命令与包名依据归档时的官方 README 与文档站整理；社区衍生维护分支（如有）与官方仓库相互独立，引用前请自行核验来源与维护状态。