---
myst:
html_meta:
"description lang=zh-CN": |
AgentChat 用户指南，AutoGen 的高级 API
---
# Magentic-One
[Magentic-One](https://aka.ms/magentic-one-blog) 是一个通用型多智能体系统，用于解决跨多个领域的开放式网页和文件处理任务。它代表了多智能体系统发展的重大进步，在多项智能体基准测试中取得了具有竞争力的性能（完整细节请参阅[技术报告](https://arxiv.org/abs/2411.04468)）。
最初于[2024年11月](https://aka.ms/magentic-one-blog)发布时，Magentic-One是[直接基于`autogen-core`库实现的](https://github.com/microsoft/autogen/tree/v0.4.4/python/packages/autogen-magentic-one)。我们现在已将Magentic-One移植到使用`autogen-agentchat`，提供了更加模块化且更易用的接口。
为此，Magentic-One的协调器 {py:class}`~autogen_agentchat.teams.MagenticOneGroupChat` 现在只是一个标准的AgentChat团队，支持所有标准AgentChat智能体和功能。同样，Magentic-One的 {py:class}`~autogen_ext.agents.web_surfer.MultimodalWebSurfer`、{py:class}`~autogen_ext.agents.file_surfer.FileSurfer` 和 {py:class}`~autogen_ext.agents.magentic_one.MagenticOneCoderAgent` 智能体现在也作为AgentChat智能体广泛可用，可用于任何AgentChat工作流中。
最后，还有一个辅助类 {py:class}`~autogen_ext.teams.magentic_one.MagenticOne`，它将所有这些组件按照论文中的配置方式进行了最小化封装。
更多关于Magentic-One的信息，请参阅我们的[博客文章](https://aka.ms/magentic-one-blog)和[技术报告](https://arxiv.org/abs/2411.04468)。
**示例**：上图展示了Magentic-One多agent团队完成GAIA基准测试中的一项复杂任务。Magentic-One的Orchestrator agent负责制定计划、将任务委派给其他agent，并跟踪目标进展，根据需要动态调整计划。Orchestrator可以将任务委派给FileSurfer agent来读取和处理文件，委派给WebSurfer agent来操作网页浏览器，或者分别委派给Coder或Computer Terminal agent来编写或执行代码。
```{caution}
使用Magentic-One涉及与为人类设计的数字世界交互，这存在固有风险。为最小化这些风险，请考虑以下预防措施：
1. **使用容器**：在docker容器中运行所有任务，以隔离agent并防止直接系统攻击。
2. **虚拟环境**：在虚拟环境中运行agent，防止其访问敏感数据。
3. **监控日志**：在执行期间和执行后密切监控日志，以检测和缓解风险行为。
4. **人工监督**：在人工监督下运行示例，以监控agent并防止意外后果。
5. **限制访问**：限制agent对互联网和其他资源的访问，以防止未经授权的操作。
6. **保护数据**：确保agent无法访问可能被泄露的敏感数据或资源。不要与agent共享敏感信息。
请注意，agent偶尔可能会尝试高风险行为，例如在没有人类参与的情况下招募人类协助或接受cookie协议。务必确保agent受到监控并在受控环境中运行，以防止意外后果。此外，需注意Magentic-One可能容易受到来自网页的提示注入攻击。
```
## 入门指南
安装所需软件包：
```bash
pip install "autogen-agentchat" "autogen-ext[magentic-one,openai]"
```
# 如果使用 MultimodalWebSurfer，还需安装 playwright 依赖：
playwright install --with-deps chromium
```
若尚未完成，请先学习 AgentChat 教程以了解其核心概念。
之后，您可以尝试将 {py:class}`autogen_agentchat.teams.SelectorGroupChat` 替换为 {py:class}`~autogen_agentchat.teams.MagenticOneGroupChat`。
例如：
```python
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 for Fermat's Last Theorem"))
await model_client.close()
asyncio.run(main())
```
如需使用其他模型，请参阅 [Models](./tutorial/models.ipynb) 获取更多信息。
或者，在团队中使用 Magentic-One agents：
```{caution}
示例代码可能会从互联网下载文件、执行代码并与网页交互。运行前请确保处于安全环境。
```
```python
import asyncio
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.teams import MagenticOneGroupChat
from autogen_agentchat.ui import Console
from autogen_ext.agents.web_surfer import MultimodalWebSurfer
# from autogen_ext.agents.file_surfer import FileSurfer
# from autogen_ext.agents.magentic_one import MagenticOneCoderAgent
# from autogen_agentchat.agents import CodeExecutorAgent
```
# 从 autogen_ext.code_executors.local 导入 LocalCommandLineCodeExecutor
async def main() -> None:
model_client = OpenAIChatCompletionClient(model="gpt-4o")
surfer = MultimodalWebSurfer(
"WebSurfer",
model_client=model_client,
)
team = MagenticOneGroupChat([surfer], model_client=model_client)
await Console(team.run_stream(task="今天墨尔本的紫外线指数是多少？"))
# # 注意：你也可以在团队中使用其他 agents
# team = MagenticOneGroupChat([surfer, file_surfer, coder, terminal], model_client=model_client)
# file_surfer = FileSurfer( "FileSurfer",model_client=model_client)
# coder = MagenticOneCoderAgent("Coder",model_client=model_client)
# terminal = CodeExecutorAgent("ComputerTerminal",code_executor=LocalCommandLineCodeExecutor())
asyncio.run(main())
```
或者，使用 {py:class}`~autogen_ext.teams.magentic_one.MagenticOne` 辅助类，
它已将所有 agents 捆绑在一起：
```python
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)
task = "编写一个从API获取数据的Python脚本"
result = await Console(m1.run_stream(task=task))
print(result)
if __name__ == "__main__":
asyncio.run(example_usage())
```
## 架构
Magentic-One 采用多agent架构，其中主导的 Orchestrator agent 负责高层规划、指挥其他agent并跟踪任务进度。Orchestrator 首先创建任务执行计划，在维护的 Task Ledger（任务台账）中收集所需事实和有根据的推测。在计划的每个步骤中，Orchestrator 会创建 Progress Ledger（进度台账）进行任务进度自检，确认任务是否完成。若任务未完成，它将指派 Magentic-One 的其他agent完成子任务。被指派agent完成子任务后，Orchestrator 更新 Progress Ledger 并持续该流程直至任务完成。如果 Orchestrator 发现连续多个步骤未取得进展，可以更新 Task Ledger 并制定新计划。如上图所示，Orchestrator 的工作因此分为更新 Task Ledger 的外循环和更新 Progress Ledger 的内循环。
总体而言，Magentic-One 包含以下agent：
- **Orchestrator**：主导agent，负责任务分解与规划，指挥其他agent执行子任务，跟踪整体进度，并在必要时采取纠正措施
- **WebSurfer**：基于LLM的agent，擅长控制基于Chromium的网页浏览器状态。对于每个请求，WebSurfer 在浏览器上执行操作后报告网页新状态。其操作空间包括导航（如访问URL、执行网页搜索）、网页操作（如点击和输入）以及阅读操作（如摘要生成或问题回答）。WebSurfer 依赖浏览器无障碍功能树和标记提示集来执行操作。
- **FileSurfer**：基于LLM的agent，通过基于Markdown的文件预览应用读取多数类型的本地文件。该agent还能执行常见导航任务，如列出目录内容和浏览文件夹结构。
- **Coder**：通过系统提示专门化的LLM agent，擅长编写代码、分析从其他agent收集的信息或创建新产物。
- **ComputerTerminal**：为团队提供控制台终端访问，可执行Coder编写的程序并安装新编程库。
Magentic-One 的agent共同为 Orchestrator 提供了解决各类开放式问题所需的工具和能力，以及自主适应动态变化的网页和文件系统环境并采取行动的能力。
虽然我们为所有agent默认使用的多模态LLM是GPT-4o，但Magentic-One与模型无关，可以整合异构模型来支持不同能力或满足任务完成时的多样化成本需求。例如，可以使用不同的LLM和SLM及其专门版本来驱动不同agent。我们建议为Orchestrator agent配备强推理模型如GPT-4o。在Magentic-One的另一种配置中，我们还尝试在Orchestrator的外循环和Coder中使用OpenAI o1-preview，而其他agent继续使用GPT-4o。
## 引用
```
@misc{fourney2024magenticonegeneralistmultiagentsolving,
title={Magentic-One: 一个用于解决复杂任务的通用多Agent系统},
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},
}
```