---

Magentic-UI是一个以人类为中心的研究原型AI智能体，能够解决复杂的Web和编码任务，这些任务可能需要监控。与其他黑盒智能体不同，该系统会在执行前展示其计划，允许您指导其行动，并在浏览网站、执行代码和分析文件时为敏感操作请求批准。 请查看演示部分，获取您可以完成的任务灵感。

✨ 最新动态

微软最新的智能体模型Fara-7B现已集成到Magentic-UI中，如何启动请参阅Fara-7B指南。

• “告诉我何时”：自动化需要访问Web或API的监控任务和可重复的工作流程，时间跨度从几分钟到几天不等。更多信息请见这里。
• 文件上传支持：通过UI上传任何文件进行分析或修改
• MCP智能体：使用您喜爱的MCP服务器扩展功能
• 更简便的安装：我们已将Docker容器上传至GHCR，因此您不再需要构建任何容器！现在安装时间大大缩短了。

🚀 快速入门

以下是如何开始使用Magentic-UI的方法：

# 1. 设置环境
python3 -m venv .venv
source .venv/bin/activate
pip install magentic-ui --upgrade

# 2. 设置您的API密钥
export OPENAI_API_KEY="your-api-key-here"

# 3. 启动Magentic-UI
magentic-ui --port 8081

然后在浏览器中打开http://localhost:8081即可与Magentic-UI互动！

先决条件：需要Docker和Python 3.10+。Windows用户应使用WSL2。更多详细信息请参阅详细安装说明。

其他使用方式

无需Docker（功能受限：无法执行代码）：

magentic-ui --run-without-docker --port 8081

命令行界面：

magentic-cli --work-dir PATH/TO/STORE/DATA

自定义LLM客户端：

# Azure
pip install magentic-ui[azure]

# Ollama（本地模型）
pip install magentic-ui[ollama]

随后您可以将配置文件传递给magentic-ui命令（客户端配置)，或者在UI设置中更改模型客户端。

有关安装的更多详细信息，请阅读🛠️ 安装部分。如遇常见安装问题及解决方案，请参阅故障排除文档。高级使用说明可通过命令magentic-ui --help查看。

快速导航：

🎬 演示  |  🟪 工作原理  |  🛠️ 安装  |  ⚠️ 故障排除  |  🤝 贡献  |  📄 许可证

---

演示

🍕 披萨订购 人机协作的Web自动化

🏠 Airbnb价格分析 MCP智能体集成

⭐ 星星监控 长期运行的监控任务

工作原理

Magentic-UI特别适用于需要在Web上执行操作的任务（例如填写表单、定制食物订单）、深入导航未被搜索引擎索引的网站（例如筛选航班、从个人网站查找链接），或需要Web导航和代码执行的任务（例如根据在线数据生成图表）。

Magentic-UI与其他浏览器使用工具的不同之处在于其透明且可控的界面，允许高效的人机协作。Magentic-UI基于AutoGen构建，提供了一个研究人机交互和试验Web智能体的平台。其主要特性包括：

• 🧑‍🤝‍🧑 协同规划：通过聊天和计划编辑器共同创建并批准逐步计划。
• 🤝 协同任务执行：直接通过网页浏览器或聊天中断并指导任务执行。Magentic-UI还可在需要时请求澄清和帮助。
• 🛡️ 动作防护：敏感操作仅在获得用户明确批准后才会执行。
• 🧠 计划学习与检索：从之前的运行中学习，以改进未来的任务自动化，并将其保存在计划库中。未来任务中可自动或手动检索已保存的计划。
• 🔀 并行任务执行：您可以同时运行多个任务，会话状态指示器会告知您Magentic-UI何时需要您的输入或已完成任务。

自主导航评估

为评估其自主能力，Magentic-UI 已在使用 o4-mini 模型时，针对多个基准测试进行了测试：GAIA 测试集（42.52%），该测试集从推理、工具使用和网络交互任务等方面评估通用 AI 助手；AssistantBench 测试集（27.60%），专注于真实且耗时的网络任务；WebVoyager（82.2%），用于衡量真实场景下的端到端网页导航能力；以及 WebGames（45.5%），通过互动挑战来评估通用网页浏览代理。

如需复现这些实验结果，请参阅以下说明。

如果您有兴趣进一步了解，请查阅我们的技术报告和博客文章.

安装

先决条件

注意：如果您使用的是 Windows，我们强烈建议您使用 WSL2（Windows Subsystem for Linux）。

1. 如果您在 Windows 或 Mac 上运行，应使用 Docker Desktop；如果在 WSL2 中运行，则可以直接在 WSL 内安装 Docker，具体请参考 WSL2 中安装 Docker 的指南。如果您在 Linux 上运行，则应使用 Docker Engine。

若使用 Docker Desktop，请确保其已配置为使用 WSL2： - 前往“设置”>“资源”>“WSL 集成” - 启用与您的开发发行版的集成。有关此步骤的更详细说明，请参阅 此处。

2. 在安装过程中，您需要设置 OPENAI_API_KEY。如需使用其他模型，请参阅下方的模型客户端配置部分。

3. 您至少需要安装 Python 3.10。

如果您使用的是 Windows，我们建议将 Magentic-UI 运行在 WSL2（Windows 子系统 for Linux）中，以确保 Docker 和文件路径的正确兼容性。

PyPI 安装

Magentic-UI 已在 PyPI 上发布。我们建议使用虚拟环境，以避免与其他软件包发生冲突。

python3 -m venv .venv
source .venv/bin/activate
pip install magentic-ui

或者，如果您使用 uv 进行依赖管理，可以按以下方式安装 Magentic-UI：

uv venv --python=3.12 .venv
. .venv/bin/activate
uv pip install magentic-ui

运行 Magentic-UI

要运行 Magentic-UI，请确保 Docker 已启动，然后执行以下命令：

magentic-ui --port 8081

注意：首次运行此命令时，系统将拉取 Magentic-UI 代理所需的两个 Docker 镜像。如果遇到问题，您可以直接使用以下命令构建它们：

cd docker
sh build-all.sh

如果在使用 Docker 时遇到问题，请参阅 TROUBLESHOOTING.md 文档。

服务器启动后，您可以通过 http://localhost:8081 访问 UI 界面。

Fara-7B

1. 首先使用 fara 扩展安装 Magentic-UI：

python3 -m venv .venv
source .venv/bin/activate
pip install magentic-ui[fara]

2. 在另一个进程中，使用 vLLM 提供 Fara-7B 模型服务：

vllm serve "microsoft/Fara-7B" --port 5000 --dtype auto 

3. 首先创建一个名为 fara_config.yaml 的配置文件，内容如下：

model_config_local_surfer: &client_surfer
  provider: OpenAIChatCompletionClient
  config:
    model: "microsoft/Fara-7B"
    base_url: http://localhost:5000/v1
    api_key: not-needed
    model_info:
      vision: true
      function_calling: true
      json_output: false
      family: "unknown" 
      structured_output: false
      multiple_system_messages: false

orchestrator_client: *client_surfer
coder_client: *client_surfer
web_surfer_client: *client_surfer
file_surfer_client: *client_surfer
action_guard_client: *client_surfer
model_client: *client_surfer

注意：如果您在不同的端口或主机上托管 vLLM，请相应地更改 base_url。

然后使用 Fara 代理启动 Magentic-UI：

magentic-ui --fara --port 8081 --config fara_config.yaml 

最后，访问 http://localhost:8081 即可进入界面！

配置

模型客户端配置

如果您想使用不同的 OpenAI 密钥，或者希望配置与 Azure OpenAI 或 Ollama 的集成，您可以在 UI 中通过导航到设置（右上角图标）并更改模型配置来完成。另一种方法是在启动 Magentic-UI 时传递一个 YAML 配置文件，该文件将覆盖 UI 中的所有设置：

magentic-ui --port 8081 --config config.yaml

其中 config.yaml 文件应如下所示，包含 AutoGen 模型客户端配置：

gpt4o_client: &gpt4o_client
    provider: OpenAIChatCompletionClient
    config:
      model: gpt-4o-2024-08-06
      api_key: null
      base_url: null
      max_retries: 5

orchestrator_client: *gpt4o_client
coder_client: *gpt4o_client
web_surfer_client: *gpt4o_client
file_surfer_client: *gpt4o_client
action_guard_client: *gpt4o_client
plan_learning_client: *gpt4o_client

您可以使用配置文件为每个代理更改客户端，并使用 AzureOpenAI (AzureOpenAIChatCompletionClient)、Ollama 等其他客户端。

MCP 服务器配置

您还可以通过向多智能体团队添加自定义的“McpAgents”来扩展 Magentic-UI 的功能。每个 McpAgent 可以访问一个或多个 MCP 服务器。您可以通过 config.yaml 文件中的 mcp_agent_configs 参数指定这些代理。

例如，以下是一个名为“airbnb_surfer”的代理，它可以通过 Stdio 在本地运行的 OpenBnb MCP 服务器进行访问：

mcp_agent_configs:
  - name: airbnb_surfer
    description: "The airbnb_surfer has direct access to AirBnB."
    model_client: 
      provider: OpenAIChatCompletionClient
      config:
        model: gpt-4.1-2025-04-14
      max_retries: 10
    system_message: |-
      You are AirBnb Surfer, a helpful digital assistant that can help users acces AirBnB.

      You have access to a suite of tools provided by the AirBnB API. Use those tools to satisfy the users requests.
    reflect_on_tool_use: false
    mcp_servers:
      - server_name: AirBnB
        server_params:
          type: StdioServerParams
          command: npx
          args:
            - -y
            - "@openbnb/mcp-server-airbnb"
            - --ignore-robots-txt

在底层，每个 McpAgent 实际上只是一个 autogen_agentchat.agents.AssistantAgent，其 MCP 服务器集合被暴露为一个 AggregateMcpWorkbench，这只是一个命名的 autogen_ext.tools.mcp.McpWorkbench 对象集合（每个 MCP 服务器对应一个）。

目前支持的 MCP 服务器类型包括 autogen_ext.tools.mcp.StdioServerParams 和 autogen_ext.tools.mcp.SseServerParams。

从源代码构建 Magentic-UI

此步骤主要适用于希望对代码进行修改、在 PyPI 安装过程中遇到问题，或希望在 PyPI 版本发布之前获取最新代码的用户。

1. 确保已安装上述先决条件，并且 Docker 正在运行。

2. 将仓库克隆到您的本地机器：

git clone https://github.com/microsoft/magentic-ui.git
cd magentic-ui

3. 使用 uv 或您喜欢的包管理器安装 Magentic-UI 的依赖项：

# 通过 https://docs.astral.sh/uv/getting-started/installation/ 安装 uv
uv venv --python=3.12 .venv
uv sync --all-extras
source .venv/bin/activate

4. 构建前端：

首先确保已安装 Node.js：

# 安装 nvm 来安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install node

然后安装前端：

cd frontend
npm install -g gatsby-cli
npm install --global yarn
yarn install
yarn build

5. 像往常一样运行 Magentic-UI：

magentic-ui --port 8081

从源代码运行 UI

如果您正在对 UI 的源代码进行修改，可以以开发模式运行前端，这样在您进行更改时，前端会自动更新，从而加快开发速度。

1. 打开另一个终端，并切换到前端目录：

cd frontend

2. 创建 .env.development 文件。

cp .env.default .env.development

3. 启动前端服务器：

npm run start

4. 然后运行 UI：

magentic-ui --port 8081

来自源代码的前端将在 http://localhost:8000 提供服务，而编译后的前端将在 http://localhost:8081 提供服务。

故障排除

如果您未能成功运行 Magentic-UI，请不要担心！第一步是确保您已按照上述步骤操作，尤其是 先决条件。

有关常见问题及其解决方案，请参阅此仓库中的 TROUBLESHOOTING.md 文件。如果您未在此处找到您的问题，请提交一个 GitHub Issue。

贡献

本项目欢迎贡献和建议。有关如何为 Magentic-UI 做出贡献的信息，请参阅我们的 CONTRIBUTING.md 指南，其中包含当前待解决的问题和其他贡献方式。

本项目已采用 Microsoft 开源行为准则。如需更多信息，请参阅 行为准则常见问题解答 或发送电子邮件至 opencode@microsoft.com 以获取更多疑问或意见。

引用

如果您在研究中使用了我们的工作，请引用我们的论文：

@article{mozannar2025magentic,
  title={Magentic-UI: Towards Human-in-the-loop Agentic Systems},
  author={Mozannar, Hussein and Bansal, Gagan and Tan, Cheng and Fourney, Adam and Dibia, Victor and Chen, Jingya and Gerrits, Jack and Payne, Tyler and Maldaner, Matheus Kunzler and Grunde-McLaughlin, Madeleine and others},
  journal={arXiv preprint arXiv:2507.22358},
  year={2025}
}

许可证

微软及任何贡献者根据 MIT 许可证 授予您对仓库中任何代码的使用许可。请参阅 LICENSE 文件。

文档中提及的 Microsoft、Windows、Microsoft Azure 及其他 Microsoft 产品和服务可能是 Microsoft 在美国或其他国家的商标或注册商标。 本项目的许可证并不授予您使用任何 Microsoft 名称、徽标或商标的权利。 Microsoft 的一般商标指南可在 http://go.microsoft.com/fwlink/?LinkID=254653 找到。

任何第三方商标或徽标的使用均受其各自政策的约束。

隐私信息可在 https://go.microsoft.com/fwlink/?LinkId=521839 查找。

微软及任何贡献者保留所有其他权利，无论这些权利是否基于各自的版权、专利或商标，无论是通过暗示、禁止反言或其他方式。

Magentic-UI 快速上手指南

Magentic-UI 是一个以人为中心的 AI 代理研究原型，旨在自动化复杂的网页操作和编程任务。与黑盒代理不同，它会在执行前展示计划，允许用户引导操作，并在敏感操作时请求批准，实现“人在回路”的控制体验。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：
  • Linux / macOS：原生支持。
  • Windows：强烈建议使用 WSL2 (Windows Subsystem for Linux) 以获得最佳的 Docker 兼容性和文件路径支持。
• Python 版本：3.10, 3.11, 3.12 或 3.13。
• 核心依赖：必须安装并运行 Docker。
  • Windows/Mac 用户推荐安装 Docker Desktop。
  • Linux 用户推荐安装 Docker Engine。
  • 注意：若使用 Docker Desktop，请在设置中启用 WSL2 集成 (Settings > Resources > WSL Integration)。
• API Key：默认需要 OpenAI API Key (OPENAI_API_KEY)。如需使用 Azure OpenAI 或本地模型 (Ollama)，可在后续配置中调整。

安装步骤

推荐使用 Python 虚拟环境进行安装，以避免依赖冲突。

1. 创建并激活虚拟环境

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

(Windows PowerShell 用户使用 .venv\Scripts\Activate.ps1)

2. 安装 Magentic-UI

从 PyPI 安装最新稳定版：

pip install magentic-ui --upgrade

提示：如果您使用 uv 进行包管理，可以使用以下命令加速安装：

uv venv --python=3.12 .venv
source .venv/bin/activate
uv pip install magentic-ui

3. 配置 API Key

设置您的 OpenAI API Key 环境变量：

export OPENAI_API_KEY="your-api-key-here"

基本使用

启动服务

确保 Docker 正在运行，然后执行以下命令启动 Magentic-UI 服务器：

magentic-ui --port 8081

注意：首次运行时，系统会自动拉取所需的 Docker 镜像，这可能需要几分钟时间。如果拉取失败，可手动进入 docker 目录运行 sh build-all.sh 构建镜像。

访问界面

在浏览器中打开以下地址即可开始交互：

http://localhost:8081

核心功能概览

进入界面后，您可以体验以下核心功能：

• 协同规划 (Co-Planning)：通过聊天或计划编辑器，与 AI 共同制定并审批逐步执行计划。
• 协同任务 (Co-Tasking)：在任务执行过程中随时介入，通过浏览器直接操作或聊天进行指导。
• 安全守卫 (Action Guards)：敏感操作（如支付、删除文件）需经您明确批准后方可执行。
• 长期监控：支持跨分钟至数天的长时间监控任务（"Tell me When" 功能）。

其他运行模式

• 无 Docker 模式（功能受限，不支持代码执行）：

  magentic-ui --run-without-docker --port 8081
  

• 命令行模式：

  magentic-cli --work-dir PATH/TO/STORE/DATA