AutoGen 中 Magentic-One 多智能体系统的 AgentChat 集成指南:从编排器、冲浪者到代码执行
AutoGen 中 Magentic-One 多智能体系统的 AgentChat 集成指南:从编排器、冲浪者到代码执行
Magentic-One 是微软研究院提出的一类"通才"多智能体系统,面向开放式的网页与文件类复杂任务。本仓库中的 python/packages/autogen-magentic-one/README.md 说明了一个关键事实:Magentic-One 现已整体移植到 autogen-agentchat 库,原先直接构建在 autogen-core 之上的独立实现已经废弃。本文基于该说明与仓库源码,为你梳理 Magentic-One 的架构组成、在 AutoGen 中的新使用形态(MagenticOneGroupChat、MagenticOne helper、三大子 Agent),并给出可运行的安装、配置、运行与安全实践示例,帮助你在一套标准 AgentChat 工作流中复现论文级的多智能体编排能力。
Magentic-One 是什么
Magentic-One 是一个通用型多智能体系统(generalist multi-agent system),用于解决多种领域的开放网页与文件任务——例如"去某个网页收集信息并整理成报告"或"读取本地一批文件后写一段脚本处理它们"。它代表了多智能体系统的一次重要进展,在一系列 agentic benchmark 上取得了具有竞争力的成绩(完整细节参见技术报告与论文,论文信息见文末引用小节)。
Magentic-One 的价值不在于发明了新的模型,而在于一套分工 + 编排的工程范式:一个主导的 Orchestrator 负责拆解任务与制定计划,其余各司其职的子 Agent 负责浏览网页、浏览本地文件、编写代码、执行代码。这使得整个系统能够自主适应动态变化的网页与文件系统环境。
重要变化:从独立实现到 AgentChat 团队
本 README 的核心信息是 Magentic-One 的载体已经改变:
- 最初(2024 年 11 月发布时),Magentic-One 直接基于
autogen-core库独立实现; - 现在,它已被移植到
autogen-agentchat之上,提供了更模块化、更容易使用的接口; - 旧实现已废弃,仅供历史版本参考。
移植后的具体形态分为三个层次,这也在仓库源码目录中清晰可见:
| 形态 | 类别 | 说明 | 仓库位置 |
|---|---|---|---|
MagenticOneOrchestrator |
群聊管理者(GroupChatManager) | 基于 ledger(任务账本/进度账本)的编排器 | src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py |
MagenticOneGroupChat |
AgentChat 团队(Team) | 一个普通的 BaseGroupChat 子类,使用 MagenticOneOrchestrator 管理参与者 |
src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_group_chat.py |
MultimodalWebSurfer、FileSurfer、MagenticOneCoderAgent |
独立的 AgentChat Agent | 供任意 AgentChat 工作流直接复用 | src/autogen_ext/agents/ |
MagenticOne |
组装好的团队子类 | 按论文原配置把上述组件"打包",仅需最小化配置即可运行 | src/autogen_ext/teams/magentic_one.py |
一句话总结:Magentic-One 的 Orchestrator 现在就是一个 AgentChat team,支持所有标准 AgentChat agent 与特性;其子 Agent 也不再被 Magentic-One 绑定,可以被用到任何 AgentChat 工作流中。
Magentic-One 的五类核心 Agent 角色
在 src/autogen_ext/teams/magentic_one.py 的类文档(L54-L68)中,完整描述了 Magentic-One 的经典五角色架构:
- Orchestrator(编排器):主导 Agent,负责任务分解与规划、指挥其他 Agent 执行子任务、跟踪整体进度,并在需要时采取纠正行动。它不是独立的参与者 agent,而是以群聊管理者的身份存在于
MagenticOneGroupChat内部。 - WebSurfer:基于 LLM 的 Agent,擅长指挥与管理 Chromium 内核浏览器状态。它在浏览器上执行动作,并把网页新状态回报给编排器(对应
MultimodalWebSurfer)。 - FileSurfer:基于 LLM 的 Agent,指挥一个基于 Markdown 的文件预览应用来读取本地大多数类型的文件,也能执行列目录、在目录层级间导航等常见操作(对应
FileSurfer)。 - Coder:基于 LLM、专精写代码的 Agent,可分析其他 Agent 收集的信息或创建新产物(对应
MagenticOneCoderAgent)。 - ComputerTerminal:为团队提供控制台 Shell 访问,用于运行 Coder 写出的程序并安装新的编程库(对应
CodeExecutorAgent+ 具体CodeExecutor)。
上述各角色的 Python 组装逻辑见 magentic_one.py 中 MagenticOne.__init__(L192-L221):它会创建 FileSurfer("FileSurfer")、MultimodalWebSurfer("WebSurfer")、MagenticOneCoderAgent("Coder") 与 CodeExecutorAgent("ComputerTerminal") 四个 Agent 作为默认参与者。
安装环境
Magentic-One 相关组件分散在 autogen-agentchat 与 autogen-ext 两个包中。从 python/packages/autogen-ext/pyproject.toml 的 extras 定义(L31-L65)可以看到,各能力均有对应的可选安装组:
# 安装 MagenticOne helper 及全部 Magentic-One 子 Agent
pip install "autogen-ext[magentic-one]"
# 若只使用 WebSurfer
pip install "autogen-ext[web-surfer]"
# 若只使用 FileSurfer
pip install "autogen-ext[file-surfer]"
# Magentic-One 依赖 Docker 代码执行器(可选)
pip install "autogen-ext[magentic-one,docker]"
各 extras 对应的运行时依赖包括:magentic-one 组会拉取 autogen-agentchat、magika、markitdown、playwright、pillow 等;web-surfer 在以上基础上同样依赖 Playwright;file-surfer 需要 magika 与 markitdown;docker 组额外引入 docker~=7.0。
特别提示: MultimodalWebSurfer 底层通过 Playwright 驱动 Chromium(源码见 src/autogen_ext/agents/web_surfer/_multimodal_web_surfer.py 的 _lazy_init,L289-L330),安装包之后还需下载浏览器内核:
python -m playwright install chromium
在 Windows 上运行需注意事件循环策略:源码(L296-L309)会检测当前策略并警告,建议设置 asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy()),避免子进程相关异常。
最快路径:使用 MagenticOne helper 类
如果你希望"开箱即用、和论文一致",直接实例化 MagenticOne 即可。其签名(magentic_one.py)如下:
MagenticOne(
client: ChatCompletionClient, # 模型客户端,必填
hil_mode: bool = False, # True 时追加 UserProxyAgent 实现人在环
input_func: InputFuncType | None = None, # 人在环模式下获取用户输入的函数
code_executor: CodeExecutor | None = None, # 代码执行器,None 时自动选择
approval_func: ApprovalFuncType | None = None, # 代码执行前的审批函数
)
第一个可运行示例:全自动完成编码任务
以下示例来自 magentic_one.py 类文档(L74-L90):
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.teams.magentic_one import MagenticOne
from autogen_agentchat.ui import Console
async def example_usage():
client = OpenAIChatCompletionClient(model="gpt-4o")
m1 = MagenticOne(client=client) # 默认使用 Docker 代码执行器
task = "Write a Python script to fetch data from an API."
result = await Console(m1.run_stream(task=task))
print(result)
if __name__ == "__main__":
asyncio.run(example_usage())
运行后,Orchestrator 会依次调度 WebSurfer/FileSurfer/Coder/ComputerTerminal 完成上述任务,Console 会把团队流转的每一步消息实时打印出来。
模型客户端要求(重要)
MagenticOne 构造时会对 client 做能力校验(magentic_one.py):
client.model_info中必须同时具备function_calling与json_output能力(代码中还要求vision,用于给 WebSurfer 传截图),否则发出警告;- 若
client不是 OpenAI 兼容客户端(非BaseOpenAIChatCompletionClient子类),同样会警告——Magentic-One 在 OpenAI GPT-4o(OpenAI 或 Azure OpenAI 通道)下表现最佳。
代码执行器与自动降级逻辑
默认不传 code_executor 时,会走 code_executors/init.py 中的 create_default_code_executor()(L41-L58):Docker 可用时优先使用 DockerCommandLineCodeExecutor,否则回退到本地 LocalCommandLineCodeExecutor。源码同时提示,不带 code_executor 直接实例化会触发 DeprecationWarning,官方建议显式传入执行器。
对应的行为也有测试覆盖(test_magentic_one.py):
- Docker 可用时默认参与者
ComputerTerminal内部是DockerCommandLineCodeExecutor且默认无审批函数(L57-L81); - 传入
approval_func后审批函数会被正确挂载(L84-L108); - Docker 不可用时自动回退本地执行器(L118 起)。
代码执行审批与人在环(HIL)模式
若你希望在代码真正运行前由人审批,或引入人类参与对话,可参考仓库类文档中的完整示例。核心 API 是 approval_func 与 hil_mode:
from autogen_agentchat.agents import ApprovalRequest, ApprovalResponse
def approval_func(request: ApprovalRequest) -> ApprovalResponse:
"""打印即将执行的代码,并由用户决定是否放行。"""
print(f"Code to execute:\n{request.code}")
user_input = input("Do you approve this code execution? (y/n): ").strip().lower()
if user_input == 'y':
return ApprovalResponse(approved=True, reason="User approved the code execution")
else:
return ApprovalResponse(approved=False, reason="User denied the code execution")
hil_mode=True时,MagenticOne会向参与者列表追加一个名为"User"的UserProxyAgent(input_func决定其如何获取用户输入);hil_mode=False但提供approval_func,则保留对话全自动、仅对危险动作(执行代码)加审批闸门。
实践中推荐显式使用 Docker 执行器,例如:
async with DockerCommandLineCodeExecutor() as code_executor:
m1 = MagenticOne(
client=client,
hil_mode=True,
input_func=user_input_func,
code_executor=code_executor,
approval_func=approval_func,
)
result = await Console(m1.run_stream(task=task))
安全警告
仓库在 magentic_one.py 类文档(L42-L52)中明确列出了风险与建议,使用 Magentic-One 时请务必遵守:
- 使用容器:把所有任务放到 Docker 容器中运行,隔离 Agent,防止直接攻击宿主系统;
- 虚拟环境:在虚拟环境中运行 Agent,防止其访问敏感数据;
- 监控日志:执行期间与执行后密切监控日志,发现并缓解风险行为;
- 人类监督:尽量以人在环方式运行示例,监督 Agent 防止意外后果;
- 限制访问:限制 Agent 对互联网和其他资源的访问,防止越权操作;
- 保护数据:确保 Agent 无法接触敏感数据;不要把敏感信息分享给 Agent。
同时要注意:Agent 偶尔会尝试冒险动作(如"招募人类帮忙"或未经人类参与就接受 Cookie 协议),且 Magentic-One 可能遭受来自网页的提示注入攻击。
编排原理:基于账本(Ledger)的双层循环
若想理解 MagenticOneGroupChat 与普通群聊(如 RoundRobinGroupChat、SelectorGroupChat)的本质差异,关键在于 MagenticOneOrchestrator 的 ledger-based orchestration(orchestrator 源码)。
外层循环:Task Ledger(任务账本)
任务启动时(handle_start,L134-L190)会经历两个规划步骤:
- GATHER FACTS(收集事实):编排器先用"闭卷"方式生成对任务的已知事实(
self._facts),记录到一个 Task Ledger; - CREATE A PLAN(制定计划):基于团队描述与事实,让模型生成执行计划(
self._plan)。
这两次模型调用都会追加进 planning_conversation,随后把"任务 + 团队 + 事实 + 计划"组成的完整账本通过 _reenter_outer_loop(L262-L298)广播给全体参与者并启动内层循环。
若任务中途"卡住",编排器会调用 _update_task_ledger(L451-L476)刷新事实与计划(再次"重读"事实、基于最新进展改计划),然后重新进入外层循环、重置各参与者——这就是它能够自我纠偏的原因。
内层循环:Progress Ledger(进度账本)
在 _orchestrate_step(L300-L449)中,每一轮编排器都会让模型输出一个结构化 JSON 的进度账本,要求包含五个键(L349-L355),且每个键都必须有 answer 与 reason 两个子字段:
| 键 | 含义 |
|---|---|
is_request_satisfied |
原始任务请求是否已被满足(为真则收尾) |
is_progress_being_made |
本轮是否在取得实质进展 |
is_in_loop |
是否陷入重复循环 |
instruction_or_question |
下发给下一位发言者的指令或问题 |
next_speaker |
下一位发言人是谁(及理由) |
输出解析带容错:源码设定 _max_json_retries = 10(L94),且会按客户端能力自动选择 structured_output、json_output 或普通输出路径(L319-L330),再通过 extract_json_from_str 解析并校验键结构,失败则重试。若单参与者团队,则确定性地把 next_speaker 指向该唯一参与者(L341-L346)。
停滞检测(Stall Detection)与重规划
源码 L393-L406 展示了停滞计数逻辑:
- 当
is_progress_being_made为假,或is_in_loop为真时,n_stalls加一;否则适度回退(max(0, n_stalls - 1)); - 当
n_stalls >= self._max_stalls(默认 3)时,判定"卡住",触发_update_task_ledger+_reenter_outer_loop的重规划动作。
这保证了系统不会在同一个死胡同里无限徘徊:内层循环负责一步步执行,停滞到阈值就跳回外层重新规划。
终止条件
任务结束的几种途径:
is_request_satisfied["answer"]为真 → 准备最终答案;- 达到
max_turns(默认 20)→ 以 "Max rounds reached." 收尾; - 显式传入的
TerminationCondition触发 → 以对应终止消息结束; - 停滞超限重规划或状态异常会抛错终止。
无论哪种方式,最终都会调用 _prepare_final_answer(L478-L512):把完整对话历史与 final_answer_prompt 交给模型生成总结性答案并广播。MagenticOneOrchestrator 还实现了 save_state / load_state(L225-L245),把消息线程、当前轮次、task/facts/plan、n_rounds/n_stalls 一并序列化,支持有状态恢复。
自由组合:MagenticOneGroupChat
MagenticOneGroupChat 继承自 BaseGroupChat,同时实现了 Component 声明式配置协议(源码,构造签名见 L109-L123)。它把 MagenticOneOrchestrator 作为群聊管理者(L131-L132),而参与者完全由你自定义。
构造参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
participants |
List[ChatAgent] |
无(必填,且至少一个) | 群聊参与者,必须是 ChatAgent 实例 |
model_client |
ChatCompletionClient |
无(必填) | 编排器与生成响应共用的模型客户端 |
name / description |
str |
"MagenticOneGroupChat" / "A team of agents." |
团队名称与描述 |
termination_condition |
TerminationCondition |
None |
终止条件;缺省时由编排器逻辑或在达到最大轮数时停止 |
max_turns |
int |
20 |
最大轮数 |
max_stalls |
int |
3 |
触发重规划前的最大停滞次数 |
final_answer_prompt |
str |
ORCHESTRATOR_FINAL_ANSWER_PROMPT |
依据团队对话生成最终答案的 LLM 提示词(默认值针对 GPT-4o 类模型调优) |
custom_message_types |
List[type] |
None |
自定义消息类型(须为 BaseAgentEvent/BaseChatMessage 子类) |
emit_team_events |
bool |
False |
是否通过 run_stream 发出团队事件 |
构造时的强校验值得注意:参与者不是 ChatAgent 会直接抛 TypeError(L124-L126);参与者为空抛 ValueError(L141-L142)。此外,与 RoundRobinGroupChat、SelectorGroupChat 不同,MagenticOneGroupChat 不支持把"团队"作为参与者(类文档 L44-L45)——需要层级结构时请自行拆分任务或组合多个团队。
最小示例
从该模块 docstring(L67-L87)取一个"自定义参与者 + MagenticOne 编排"的完整可运行示例:
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import MagenticOneGroupChat
from autogen_agentchat.ui import Console
async def main() -> None:
model_client = OpenAIChatCompletionClient(model="gpt-4o")
assistant = AssistantAgent(
"Assistant",
model_client=model_client,
)
team = MagenticOneGroupChat([assistant], model_client=model_client)
await Console(team.run_stream(task="Provide a different proof to Fermat last theorem"))
asyncio.run(main())
运行后可以观察到:单参与者场景下,编排器不再依赖"选人"(源码 L341-L346 固定指向唯一参与者),而是把注意力放在评估当前结果、下达下一步指令上。这展示了 MagenticOneGroupChat 的一个常见用法:把你自己训练的、或已有的任意 AssistantAgent/BaseChatAgent 放进去,立刻获得 Magentic-One 风格的编排管理。仓库相应行为有测试覆盖(test_magentic_one_group_chat.py)。
可单独复用的三大子 Agent
README 强调:WebSurfer、FileSurfer、Coder 已作为通用 AgentChat Agent 发布,可在任何 AgentChat 工作流中使用——包括 RoundRobinGroupChat、SelectorGroupChat、SequentialWorkflow,甚至被其他团队嵌套。
MultimodalWebSurfer
定义在 src/autogen_ext/agents/web_surfer/_multimodal_web_surfer.py。它是多模态网页冲浪 Agent:基于 Playwright 启动 Chromium,能搜索、访问网页并对页面元素(点击链接、滚动视口、填写表单)进行操作。其核心机制(类文档 L103-L111):
- 首次调用时惰性初始化浏览器并加载页面(
_lazy_init),之后复用; - 截取页面截图,提取可交互元素,生成带交互区域边界框的 set-of-mark(SOM)截图;
- 把 SOM 截图、历史消息与工具列表一起发给多模态模型客户端;
- 模型返回字符串则直接作为答复;返回工具调用列表则执行并回报页面新状态与元数据。
关键构造参数(L209-L226):downloads_folder(下载目录,默认 None 不保存)、headless(默认 True)、start_page(默认值为 "https://www.bing.com/")、animate_actions、to_save_screenshots(需要同时设置 debug_dir,否则抛 ValueError)、use_ocr、browser_channel、browser_data_dir(持久化浏览器上下文目录)、to_resize_viewport。构造时若检测到模型不支持 function calling 会直接抛错(L235-L238)。
内置工具集(L276-L286)包括:visit_url、web_search、history_back、click、type、read_page_and_answer、summarize_page、sleep、hover 等。使用前提是支持工具调用的多模态模型客户端(当前理想选择是 GPT-4o 类)。
FileSurfer
定义在 src/autogen_ext/agents/file_surfer/_file_surfer.py,扮演"本地文件预览器":可打开并读取多种常见文件类型,也能在本地目录层级中导航。构造参数为 name、model_client(须支持工具调用)与可选的 description、base_path(默认当前工作目录,L74-L84)。
其内部使用 MarkdownFileBrowser(视口 1024×5)把文件渲染成 Markdown 分页浏览,提供的工具包括 open_path、page_up、page_down、find_on_page_ctrl_f、find_next 等(_tool_definitions.py)。每次回复前会把当前打开的路径与页标题、视口位置(如 "Showing page 1 of 5")拼进上下文(L106-L138),模型基于浏览器状态决定下一步导航动作;出现异常时则以 "File surfing error" 包装错误返回(L98-L101)。
MagenticOneCoderAgent
定义在 src/autogen_ext/agents/magentic_one/_magentic_one_coder_agent.py,是 AssistantAgent 的子类,仅固定了 description 与 system message 以复刻原始 Magentic-One 配置(L22-L40)。其提示词核心约束非常值得借鉴:
- 需要收集信息时,输出 Python 或 shell 代码块让用户/执行器运行,并依靠
print输出所需信息; - 不允许给出需要用户修改的半成品代码;每条回复只允许一个代码块;不要要求用户复制粘贴结果;
- 出错时给出完整修复代码而非片段;
- 找到答案时必须谨慎验证,尽量附带可验证证据。
说明:如需修改上述提示词,源码注释明确建议改用通用的 AssistantAgent 自行构造(该类设计上封闭了这些值)。
最佳实践清单
综合仓库文档与源码,使用 Magentic-One 时推荐:
- 模型选型:优先 OpenAI / Azure OpenAI 的 GPT-4o 类模型(
model_info需含function_calling、json_output、vision); - 代码执行容器化:显式传入
DockerCommandLineCodeExecutor,必要时开启approval_func审批闸门; - 人在环优先:
hil_mode=True让人类可随时接管,可显著降低意外动作风险; - 控制开放程度:把 WebSurfer 的
start_page与下载/调试目录收敛到可控范围,监控日志(trace/event logger 在autogen_agentchat中定义); - 遇到停滞不必惊慌:先理解
max_turns、max_stalls两个旋钮——前者限制总轮数,后者决定"多久算卡住并触发重规划"; - 状态恢复场景:Orchestrator 的
save_state/load_state支持有状态恢复,可用于长时间任务的断点续跑。
引用信息
若在你的工作中使用了 MagenticOneGroupChat 或 MagenticOne,请按 README 提供的方式引用论文:
@misc{fourney2024magenticonegeneralistmultiagentsolving,
title={Magentic-One: A Generalist Multi-Agent System for Solving Complex Tasks},
author={Adam Fourney and Gagan Bansal and Hussein Mozannar and Cheng Tan and Eduardo Salinas and Erkang and Zhu and Friederike Niedtner and Grace Proebsting and Griffin Bassman and Jack Gerrits and Jacob Alber and Peter Chang and Ricky Loynd and Robert West and Victor Dibia and Ahmed Awadallah and Ece Kamar and Rafah Hosn and Saleema Amershi},
year={2024},
eprint={2411.04468},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2411.04468},
}
仓库内相关源码与测试可直接作为进一步研究的入口:编排与团队实现位于 python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/,打包类位于 python/packages/autogen-ext/src/autogen_ext/teams/magentic_one.py,行为验证测试位于 python/packages/autogen-ext/tests/teams/test_magentic_one.py 与 python/packages/autogen-agentchat/tests/test_magentic_one_group_chat.py。