AutoGen：微软多智能体对话框架安装与使用指南

一、项目背景

单个 LLM 再强，也有"一本正经胡说八道"的时候。让两个或多个 Agent 互相辩论、互相检查，往往能显著降低错误率——这就是多智能体（Multi-Agent）范式的核心思想。但要真的实现起来，你得自己管对话历史、控制谁先说话、什么时候终止循环、如何安全执行代码，工程量不小。

Microsoft AutoGen 由微软研究院于 2023 年开源，是最早把"多智能体对话"做成开箱即用框架的项目之一。它把每个 Agent 抽象成一个可对话的角色：AssistantAgent（助手）、UserProxyAgent（人类/代码执行者代理）、CodeExecutor（在沙箱里跑 Python 代码），你只要定义好角色和终止条件，几个 Agent 就能自动围绕一个任务展开对话、写代码、跑代码、Debug、直到给出答案。

2025 年起，微软把 AutoGen 与 Semantic Kernel 合并，演进为新的 Microsoft Agent Framework（Python 包名 agent-framework），但 AutoGen 仓库仍然活跃维护，生态里大量教程、教材、论文都基于 AutoGen 0.2/0.4。本文以稳定版 AutoGen 为主线介绍部署方式。

二、核心特性

• 可对话 Agent 抽象：AssistantAgent、UserProxyAgent、MultimodalWebSurfer 等开箱即用角色。
• 多 Agent 群聊：GroupChat + GroupChatManager 支持任意数量 Agent 轮替发言。
• 代码执行沙箱：LocalCommandLineCodeExecutor、DockerCommandLineCodeExecutor 安全跑生成的 Python 代码。
• 工具调用原生：用 @user_proxy.register_for_execution() 装饰器即可把任意 Python 函数变成 Agent 工具。
• 人机协同：UserProxyAgent 可以配置成每步都问人类，或全自动执行。
• 多 LLM 后端：OpenAI、Azure OpenAI、Anthropic、Gemini、本地 vLLM、Ollama。
• 异步高性能：基于 asyncio，支持并发跑多个 Agent 会话。
• .NET / Python 双语言：同时提供 Python 与 C# SDK，方便企业 .NET 栈集成。

三、环境要求

• Python：3.9 – 3.12（AutoGen 0.4.x 推荐 3.10/3.11）。
• 操作系统：Linux / macOS / Windows。
• Docker：如果使用 Docker 代码执行器，需要本地 Docker。
• LLM API Key：至少一个 OpenAI / Azure OpenAI / DeepSeek 等兼容 Key。
• 内存：2 GB+ 即可，本地跑模型另算。

四、详细部署步骤

方式一：pip 安装（推荐）

python3 -m venv .venv
source .venv/bin/activate

# AutoGen 0.4 采用分包发布
pip install -U autogen-agentchat autogen-ext[openai]

# 如果要用 Docker 代码执行器
pip install -U "autogen-ext[docker]"

老版本 0.2（很多教程还在用）：

pip install "autogen-agentchat~=0.2"
# 或旧包名
pip install pyautogen

方式二：从源码安装

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

pip install -e packages/autogen-core
pip install -e packages/autogen-agentchat
pip install -e "packages/autogen-ext[openai]"

配置 LLM

import os
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_core.models import UserMessage

os.environ["OPENAI_API_KEY"] = "sk-xxxx"

client = OpenAIChatCompletionClient(
    model="gpt-4o-mini",
    # 如用 DeepSeek：
    # base_url="https://api.deepseek.com/v1",
    # model="deepseek-chat",
)

第一个多 Agent 对话

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.ui import Console

# 1) 定义两个 Agent
assistant = AssistantAgent(
    name="assistant",
    model_client=client,
    system_message="你是一个 Python 专家，遇到问题给出代码。完成后回复 'APPROVE'。",
)

critic = AssistantAgent(
    name="critic",
    model_client=client,
    system_message="你是代码审查员，检查 assistant 给出的代码是否正确。如果正确就回复 'APPROVE'。",
)

# 2) 组群聊，收到 "APPROVE" 就结束
team = RoundRobinGroupChat(
    [assistant, critic],
    termination_condition=TextMentionTermination("APPROVE"),
)

# 3) 跑起来
await Console(team.run_stream(task="写一个快速排序的 Python 函数"))

带工具调用的 Agent

from autogen_core.tools import FunctionTool

def get_weather(city: str) -> str:
    """查询城市天气（示例）"""
    return f"{city} 今天晴，22℃"

weather_tool = FunctionTool(get_weather, description="查询城市天气")

weather_agent = AssistantAgent(
    name="weather_agent",
    model_client=client,
    tools=[weather_tool],
    system_message="你是天气助手，需要时调用工具。",
)

# 跑起来，Agent 会自动决定何时调用 get_weather
result = await weather_agent.run(task="北京现在天气怎么样？")
print(result.messages[-1].content)

带 Docker 沙箱的代码执行 Agent

from autogen_ext.code_executors.docker import DockerCommandLineCodeExecutor
from autogen_agentchat.agents import CodeExecutorAgent

executor = DockerCommandLineCodeExecutor(work_dir="workspace")
await executor.start()

code_agent = CodeExecutorAgent(
    name="code_runner",
    code_executor=executor,
)

# 让 assistant 写代码，code_runner 在 Docker 里执行
team = RoundRobinGroupChat([assistant, code_agent], ...)
# ...

await executor.stop()

Docker 一键跑官方示例

docker run -it --rm \
  -e OPENAI_API_KEY=sk-xxxx \
  mcr.microsoft.com/autogen/stable:latest

五、进阶用法与生产建议

5.1 生产部署架构

把 AutoGen Agent 包成 FastAPI 服务：

from fastapi import FastAPI
app = FastAPI()

@app.post("/chat")
async def chat(msg: str):
    result = await team.run(task=msg)
    return {"reply": result.messages[-1].content}

配合 Uvicorn + Nginx 即可对外提供服务。注意 Agent 会话要做会话级隔离，每个用户一个独立 thread。

5.2 成本与超时控制

• 设置 MaxMessageTermination(15) 防止对话无限循环；
• 生产用 gpt-4o-mini 做普通对话，复杂任务再切 gpt-4o；
• 开启 logging.set_verbosity(WARNING) 减少日志噪音；
• 用 LangSmith/Phoenix 追踪每次 Agent 调用。

5.3 常见组合模式

• 单 Agent + 工具：一个助手配搜索/计算器；
• Assistant + Critic：一个写一个审，提升准确率；
• UserProxy + Assistant：人在回路，每步问人类；
• GroupChat：3+ Agent 自由辩论。

六、使用方法示例

查看对话历史：

stream = team.run_stream(task="...")
async for message in stream:
    print(message)   # 每条消息来自哪个 Agent、内容是什么

保存对话为 JSON：

from autogen_agentchat.base import TaskResult
state = await team.save_state()
import json; json.dump(state, open("team_state.json","w"))

典型任务示例：

• "让一个 Agent 写 Python，另一个 Agent 在 Docker 里跑并反馈错误。"
• "两个 Agent 辩论：远程办公是否比坐班效率高。"
• "一个 Agent 查资料，一个 Agent 写周报。"

默认账号密码：AutoGen 是 Python 库，没有独立 Web 后台、不需要登录。它调用你配置的 LLM API，账单走对应服务商。

七、常见问题（FAQ）

Q1：AutoGen 0.2 和 0.4 怎么选？

新项目建议直接上 0.4 / Microsoft Agent Framework，架构更清晰、异步支持更好；老项目、教材教程很多还在 0.2（pyautogen），API 不兼容，迁移时需要重写 Agent 定义。

Q2：Agent 一直在循环停不下来？

检查 termination_condition：建议组合使用 TextMentionTermination("APPROVE") + MaxMessageTermination(10)，避免死循环烧 Token。

Q3：代码执行安全吗？

默认 LocalCommandLineCodeExecutor 直接在你的机器上跑生成的 Python，有风险。生产环境务必切到 DockerCommandLineCodeExecutor 或远端沙箱。

Q4：能接本地 Ollama 模型吗？

可以，使用 autogen_ext.models.openai.OpenAIChatCompletionClient，把 base_url 改成 http://localhost:11434/v1，model 填 ollama 上的模型名即可。

Q5：和 CrewAI、LangGraph 比有什么区别？

AutoGen 偏"对话即协作"，Agent 之间靠自然语言来回；CrewAI 偏"角色扮演+任务流水线"；LangGraph 偏"显式状态机+图编排"。复杂可控流程选 LangGraph，快速多 Agent 试验选 AutoGen，业务分工清晰选 CrewAI。

Q6：Microsoft Agent Framework 是什么？

2025 年微软把 AutoGen 与 Semantic Kernel 合并为 Microsoft Agent Framework（pip 包 agent-framework）。老 AutoGen 代码仍可跑，但新功能优先在新框架开发。

Q7：如何做成本核算？

开启 OpenAI 的 usage 追踪：client = OpenAIChatCompletionClient(..., model="gpt-4o-mini")，每次 run 后从 result 里读 usage 字段统计 token。

八、跳转链接

• GitHub 仓库：https://github.com/microsoft/autogen
• 官方文档：https://microsoft.github.io/autogen/stable/
• PyPI：autogen-agentchat
• Microsoft Agent Framework：MS Agent Framework
• 示例库：python/samples