基于 LangGraph General-Use Multi-Agent Framework 构建的本地多智能体工作台：Supervisor–Worker 编排 + 现代 Web GUI，Windows 单机运行。
- 可视化配置 —— 在浏览器里创建 / 编辑 / 删除 multi-agent 配置；每份配置是一个 JSON 文件，并与一个 PostgreSQL checkpoint 库绑定。常用配置可保存为默认模板。
- Supervisor–Worker 架构 —— 主 agent 负责理解、拆解与汇总，把任务委派给子 agent；每个子 agent 都是带 checkpointer 的子图，在线程内跨调用保持记忆。
- 子 agent 即工具 —— 每个子 agent 以「工具」的形式暴露给主 agent（名字 + 描述）；一次可并行调度多个子 agent，并回收它们的报告。
- MCP 工具接入 —— 子 agent 可挂载 http / stdio 两种 MCP 工具源，配置页提供连通性检测。
- 让主 agent 直接操作浏览器 —— 内置
browser_agent，主 agent 可驱动本机 Chrome/Edge 完成导航、点击、输入、拖动、滚动与多标签页管理；面向纯文本 LLM（无需多模态 / 视觉）。 - 省 token 的 DOM 呈现 —— 首帧给完整 DOM 基线，之后每次互动只回传新增 / 变化的内容；以地标 + 缩进树 + 语义标签（
<可点击元素 eN>/<可输入元素 eN>/<可拖动元素 eN>/<可滚动元素 eN>）呈现，标题保留层级。 - 整页与双向滚动 —— 文档级滚动条暴露为可滚动元素；滚动用
scroll_delta指定方向（正数向下、负数向上，单位为步）。 - 拟人交互 —— 真实鼠标 / 键盘事件轨迹（非直接调用元素接口），React / Vue 受控输入有原生 setter 兜底。
- 提示接管开关 —— 输入区可实时预览当前聚焦标签页的只读 DOM，发送消息时自动附着，发送后自动关闭。
- 全局急停 —— 桌面级始终置顶的「停止 / 继续」悬浮球（跨应用可见），浏览器关闭后自动隐藏并复位。
- 敏感信息脱敏 —— LLM 填写时用
<名称>占位，工具调用时按全局「敏感信息表单」替换为真实值，真实隐私不进入模型上下文。
- 官方 provider —— 内置 openai / anthropic / deepseek / google_genai，直接以
provider:model选择。 - 任意 OpenAI 兼容模型 —— 填写模型名 + base_url 即可接入第三方端点。
- 精细采样参数 —— temperature / top_k / top_p / max_tokens / repetition_penalty 逐项可选。
- DeepSeek 思考模式修复 —— 一键开启 reasoning_content 回填，规避思考模式 + 工具调用下的间歇性 400。
- 语义记忆 —— BGE-M3 embedding + PostgreSQL（pgvector）向量检索。
- 自动记忆吸附 —— 每条用户消息发送前自动检索相关记忆并附加上下文（条数可配）。
- 记忆读写工具 —— 主 agent 可主动写入 / 检索长期记忆。
- 模型下载进度 —— 首次使用自动下载 embedding 模型，界面与托盘实时显示进度。
- 逐 token 流式输出 —— 基于 WebSocket 实时渲染主 / 子 agent 输出。
- 思考过程 —— 推理内容独立成块，与正文按真实顺序交错显示。
- 工具调用可视化 —— 工具调用与结果内联展示并自动去重。
- 并行子 agent 分区 —— 多个子 agent 并行时按轮次分区，可下拉切换查看各自输出。
- 细粒度状态栏 —— 实时显示「谁 · 在做什么」（思考中 / 回答中 / 调取工具 / 等待工具 / 加载模型）。
- Markdown + 公式 —— markdown-it 渲染、代码高亮、KaTeX 公式，另可选「裸公式识别 / 激进公式渲染」。
- 阅读友好 —— 正文与思考独立缩放、发送后自动跟随最新输出、可拖动的固定到底部按钮、回复完成提示音、发送 / 换行键可自定义。
- 图中途确认 —— 需要用户拍板时弹出应用内确认框（子 agent 使用区分样式）。
- 未发送草稿持久化 —— 输入框内容按 agent 落盘，退出会话 / 关闭浏览器 / 退出托盘程序后仍可恢复；跨 agent 流转可配。
- 会话持久化 —— 列出 / 继续 / 删除会话；只建了名字、尚未发言的空会话也会保留。
- 历史 Markdown 浏览 —— 主 / 子 agent 历史以 Markdown 只读呈现，并统计消息数与 token 用量。
- 消息目录 —— 下拉目录按用户消息展开，点击标题即可跳转。
- 历史消息编辑 —— 进入编辑模式后可按行修改历史消息（可选任意时间、任意类型），逐条提交并即时生效。
- 编辑失败可读报错 —— 编辑提交按「加载模型 / 写入」分阶段超时，写入失败时以右上角持久化提示条给出可关闭的原因，且失败即停。
- 快照 —— 每次全量清空前自动保存主 / 子 agent 历史快照，可只读回看或删除。
- 隐藏会话 —— 按 agent 独立隐藏 / 显示会话。
- 阶段性总结 —— token 达到阈值时自动总结，不打断对话。
- 自动全量清空 —— 达到更高阈值时先快照、再总结、再清空（可保留最近若干轮）。
- 主动全量总结 —— 手动触发主 agent 或指定子 agent 的全量总结。
- 自研文件工具 —— read（分页 + 行号）/ edit（字符串级中段修改）/ write / search，以及目录、复制、移动、删除；所有操作限定在根目录内。
- 富格式读取 —— PDF / Word / PPT / Excel / EPUB / HTML 等自动转 Markdown；PDF 额外用 pdfminer 抽正文、pdfplumber 按框线抽表格；读取时在同目录生成可编辑的
.md副本。 - HTML 报告 —— 可选在回复后生成 HTML 报告并自动打开。
- 导出 —— 一键把单条回复导出为可打印 HTML（A4 优化）或 Markdown 文件。
- 全局设置 —— 记忆吸附、导出路径、历史折叠、编辑模式、公式识别等集中配置，支持中 / 英双语切换。
- 一键部署 ——
setup.bat自动创建虚拟环境、安装依赖并打包MultiAgentStudio.exe；Windows 托盘常驻，浏览器自动打开。 - pgvector 一键安装 —— 自动识别 PostgreSQL 与编译环境，优先从官方源码编译，失败回退预编译包。
- 连接串输入 —— PostgreSQL 连接支持「分步填写」或直接粘贴完整连接串。
- 卡片外观与隐藏 —— multi-agent 卡片列表的按钮配色 / 样式、角落绶带、卡片背景可配（本机偏好）；支持隐藏配置并用「显示隐藏」开关查看。
Supervisor（主 agent） Workers（子 agent）
├─ 文件工具 ├─ MCP 工具（http / stdio）
├─ 记忆工具（写 / 读） └─ checkpointer=True 的子图
├─ 子 agent 工具（作为 tool 呈现）
├─ 浏览器工具（接管 Chrome/Edge）
└─ 总结 / 清空历史
- 主 agent 是负责调度规划的 Supervisor；每个子 agent 是一个
checkpointer=True编译的子图，作为节点挂载，在线程内跨调用保持记忆。 - 主图与各子图共享
subagents_reports_submit/instructions_for_subagents（故意同名）用于报告 / 指令穿透，而各自的消息通道键必须唯一。
- 安装 Python 3.13：到 https://www.python.org/downloads/ 下载并安装，安装时请勾选「Add python.exe to PATH」。
- 安装 PostgreSQL：程序用它保存会话历史和长期记忆。
- 打开本仓库页面，点右侧 Releases，在最新版本下点击 Source code (zip) 下载。
- 把 zip 解压到任意位置，得到一个
multi-agent-studio-*文件夹。
- 双击点进去，一直点到能看到
setup.bat、build_exe.bat的那一层。
- 双击
setup.bat（或在文件夹空白处右键 →「在终端中打开」→ 输入setup.bat回车）。 - 首次会弹出「用户账户控制」，点「是」——这是为了启用 Windows 长路径支持，防止安装时报「路径过长」。
- 脚本会自动：创建虚拟环境 → 安装全部依赖（首次约几分钟）→ 询问是否一键安装 pgvector → 打包出
MultiAgentStudio.exe。 - 看到「安装完成！已生成 MultiAgentStudio.exe」，则exe运行文件打包成功。
安装脚本会自动启用 Windows 长路径，因此项目解压到任意目录都能正常安装，不必特意放到 C 盘根目录。
- 安装 pgvector 扩展（PostgreSQL 不自带，必须单独安装）：安装 PostgreSQL 后，双击项目里的
install_pgvector.bat即可一键安装（或者在3.中选择一键安装pgvector）——它会自动识别 PostgreSQL 目录、自动寻找 Visual Studio 编译环境并从官方源码编译；若没有编译环境，会提示是否使用社区预编译包（会有风险提示）。装好后无需打开 psql、也无需手动执行CREATE EXTENSION，程序会在首次聊天时自动创建。
没有安装 Visual Studio 也不影响：
install_pgvector.bat会自动回退到预编译包，并明确提示相关风险。
- 双击项目文件夹里的
MultiAgentStudio.exe。 - 浏览器会自动打开界面，同时右下角出现托盘图标（右键图标可「打开 / 查看状态 / 退出」）。
从源码运行（开发用）：
python run.py --console（前台，自动开浏览器 + 控制台日志）。
- 点「＋ 新建 multi-agent」填表单（API key、system prompt、子 agent、MCP、PostgreSQL 库）。
- 先在 pgAdmin 建好 checkpoint 库（表单会提醒并做连通预检）。
- 打开某个 agent → 选 / 建线程 → 开始流式对话。
每个 multi-agent 的身份绑定
checkpoint_database。创建后子 agent 不可增删 / 改名，但其 prompt / description / MCP 工具 / 模型仍可改。
升级时只需保留少数「你的数据」，其余代码文件全部覆盖为新版本即可。PostgreSQL 里的会话历史与长期记忆（checkpoint 库 / store 库）存在数据库里、不在此文件夹中，覆盖文件不会影响它们。
⚠️ 重要：升级后务必重新运行setup.bat生成新的MultiAgentStudio.exe。不要直接沿用旧版的MultiAgentStudio.exe——部分版本更迭中，旧 exe 因打包的前端/后端代码与新版不匹配，会出现错误行为。
| 文件 / 目录 | 说明 |
|---|---|
configs/ |
所有 multi-agent 配置（<agent_id>.json、default.json）与全局设置（settings.json）。含 API key、system prompt、数据库连接、阈值等。 |
snapshots/ |
全量总结前自动保存的会话快照（若生成过）。 |
.env |
本地 MCP 服务器读取的 token 等环境变量。 |
.chrome-profile/ |
浏览器接管使用的自动化 Chrome profile（用过浏览器接管才有）。保留可复用网站登录态；不保留则需重新登录。 |
app/、browser_agent/、run.py、tray.py、launcher.py、scripts/、folder_of_MCPs/、md2print/（源码）、requirements.txt、setup.bat、setup.ps1、build_exe.py、build_exe.bat、icon.ico、.env.example、README.md、LICENSE 等。
venv/（setup.bat 重建）、MultiAgentStudio.exe / dist/ / build/（打包生成）、logs/（服务日志）、__pycache__/ 等缓存。
- 备份
configs/、snapshots/、.env。 - 用新版本覆盖其余文件（或把上述三个复制进新解压的文件夹）。
- 务必运行
setup.bat重新安装依赖并打包，生成新的MultiAgentStudio.exe（不要沿用旧 exe）。 - 双击新生成的
MultiAgentStudio.exe，确认历史会话、记忆与快照都还在。
folder_of_MCPs/ 是独立的 FastMCP 服务器（彩云天气、高德地图）。单独启动后，在子 agent 的 mcp_servers 里以 http 或 stdio 方式引用；token 从环境变量读取，见 .env.example。
A local multi-agent workbench built on the LangGraph General-Use Multi-Agent Framework: Supervisor–Worker orchestration with a modern web GUI, running locally on Windows.
- Features
- Screenshots
- Architecture
- Quick Start
- Version migration (upgrading)
- Local MCP servers
- License
- Visual configuration — create / edit / delete multi-agent configs in the browser; each config is a JSON file bound to a PostgreSQL checkpoint database. Save any config as the default template.
- Supervisor–Worker architecture — the main agent plans, delegates, and summarizes; each sub-agent is a subgraph compiled with
checkpointer=True, keeping memory across calls within a thread. - Sub-agents as tools — each sub-agent is exposed to the main agent as a tool (name + description); several sub-agents can be dispatched in parallel in one turn and their reports collected.
- MCP tools — attach
http/stdioMCP servers per sub-agent, with a connectivity check in the config page.
- Let the main agent drive a browser — a built-in
browser_agentlets the main agent operate the local Chrome/Edge: navigation, clicking, typing, dragging, scrolling and multi-tab management; designed for a text-only LLM (no multimodality / vision required). - Token-friendly DOM — the first frame returns a full DOM baseline; each later interaction returns only the new/changed content, rendered as landmarks + an indented tree with semantic tags (
<可点击元素 eN>/<可输入元素 eN>/<可拖动元素 eN>/<可滚动元素 eN>), keeping heading levels. - Whole-page & bidirectional scrolling — the document-level scrollbar is exposed as a scrollable element; scrolling uses
scroll_deltafor direction (positive = down, negative = up, unit = step). - Human-like interaction — real mouse/keyboard event paths (not direct element API calls); controlled React/Vue inputs fall back to the native setter.
- Takeover-hint toggle — the input area can show a live read-only preview of the focused tab's DOM, auto-attached to the message on send and closed after a successful send.
- Global stop — a desktop-level always-on-top "Stop / Continue" floating ball (visible across apps); it auto-hides and resets when the browser closes.
- Sensitive-info desensitization — the LLM uses
<name>placeholders when filling; on tool call they are replaced with real values from the global "sensitive info form", keeping real secrets out of the model context.
- Built-in providers — openai / anthropic / deepseek / google_genai via a
provider:modelprefix. - Any OpenAI-compatible model — enter a model name + base_url to use third-party endpoints.
- Fine-grained sampling — opt in per parameter: temperature / top_k / top_p / max_tokens / repetition_penalty.
- DeepSeek thinking-mode fix — one toggle to back-fill
reasoning_content, avoiding intermittent 400s in thinking mode with tool calls.
- Semantic memory — BGE-M3 embeddings + PostgreSQL (pgvector) retrieval.
- Automatic memory attachment — before each user message, relevant memories are retrieved and attached as context (count configurable).
- Memory tools — the main agent can write / search long-term memory on its own.
- Model download progress — the embedding model is downloaded on first use, with live progress in the UI and tray.
- Token-by-token streaming — main / sub-agent output rendered live over WebSocket.
- Reasoning display — thinking is shown in its own collapsible block, interleaved with the body in true order.
- Tool-call visualization — tool calls and results are shown inline and de-duplicated.
- Parallel sub-agent partitions — when several sub-agents run in parallel, output is split per round with a dropdown to switch between them.
- Granular status bar — shows who is doing what in real time (thinking / answering / fetching tools / waiting for tools / loading model).
- Markdown + math — markdown-it rendering, syntax highlighting, KaTeX math, plus optional bare-formula / aggressive formula detection.
- Reading comfort — independent body / reasoning zoom, auto-follow on send, a draggable pin-to-bottom button, a reply-completed chime, and customizable send / newline keys.
- In-graph confirmation — when the graph needs your decision, an in-app confirm dialog appears (sub-agent dialogs use a distinct style).
- Unsent draft persistence — the input box is persisted per agent and survives leaving a thread, closing the browser, or quitting the tray app; cross-agent flow is configurable.
- Persistent threads — list / resume / delete conversations; named-but-unused threads survive reloads too.
- Markdown history — main / sub-agent history is shown read-only as Markdown, with message counts and token usage.
- Message directory — a drawer lists user messages and expands each reply's headings for jump-to navigation.
- History editing — enter edit mode to edit historical messages line by line (optionally any time / any type), submitted sequentially and applied instantly.
- Readable edit failures — edit submission times out per stage (loading model / writing); on failure a persistent, dismissible reason is shown in the top-right, and submission stops.
- Snapshots — before every full flush, main / sub-agent history is snapshotted automatically; browse read-only or delete.
- Hide threads — hide / show conversations independently per agent.
- Staged summarization — automatic summaries once a token threshold is reached, without interrupting the conversation.
- Automatic full flush — at a higher threshold: snapshot, summarize, then clear (keeping a configurable number of recent turns).
- Proactive full summary — manually trigger a full summary for the main agent or a chosen sub-agent.
- Custom file tools — read (pagination + line numbers) / edit (precise mid-string edits) / write / search, plus directory, copy, move, delete; everything is sandboxed to the root directory.
- Rich-format reading — PDF / Word / PPT / Excel / EPUB / HTML are converted to Markdown; PDFs additionally use pdfminer for text and pdfplumber for ruled-line tables, and a same-named editable
.mdcopy is created on read. - HTML report — optionally generate an HTML report after a reply and open it automatically.
- Export — one-click export of a single reply to a printable HTML (A4-optimized) or Markdown file.
- Global settings — memory attachment, export paths, history folding, edit mode, formula detection, and more, with a zh / EN language switch.
- One-click deploy —
setup.batcreates the venv, installs dependencies, and packagesMultiAgentStudio.exe; the app lives in the Windows tray and opens the browser automatically. - One-click pgvector install — auto-detects PostgreSQL and a C++ toolchain, builds from official source first and falls back to a prebuilt package.
- Connection-string input — fill PostgreSQL in steps or paste a full connection string.
- Card appearance & hiding — configure the multi-agent card list's button colors/styles, corner ribbon and card background (local preference); configs can be hidden and revealed via a "show hidden" toggle.
Supervisor (main agent) Workers (sub-agents)
├─ file tools ├─ MCP tools (http / stdio)
├─ memory tools (write/read) └─ subgraph with checkpointer=True
├─ sub-agent tools (as tools)
├─ browser tools (take over Chrome/Edge)
└─ summarization / history flush
- The main agent is a Supervisor that plans and delegates; each sub-agent is a subgraph compiled with
checkpointer=Trueand mounted as a node, keeping memory across calls within a thread. - The main graph and each subgraph share
subagents_reports_submit/instructions_for_subagentschannels (intentionally same-named) for passing reports / instructions, while their message channels must be unique.
- Install Python 3.13 from https://www.python.org/downloads/ — please check "Add python.exe to PATH".
- Install PostgreSQL (for checkpoints and long-term memory).
- Open the Releases page and download the latest Source code (zip).
- Extract the zip anywhere — you'll get a
multi-agent-studio-*folder.
- Drill down until you see
setup.batandbuild_exe.bat.
- Double-click
setup.bat(or right-click an empty area → Open in Terminal → runsetup.bat). - On the first UAC prompt, click Yes — this enables Windows long-path support so torch installs without the "path too long" error.
- The script creates the venv, installs all dependencies (a few minutes the first time), offers to install pgvector, and builds
MultiAgentStudio.exe. - Wait for "安装完成！已生成 MultiAgentStudio.exe".
The installer enables Windows long paths automatically, so the project can be extracted anywhere.
- Install the pgvector extension (PostgreSQL does not bundle it). After installing PostgreSQL, double-click
install_pgvector.batin the project (or confirm installing pgvector in 3.) — it auto-detects your PostgreSQL directory, finds the Visual Studio C++ toolchain, and builds pgvector from the official source. If no compiler is found, it offers to use a community prebuilt package (with an explicit risk warning). No need to open psql or runCREATE EXTENSIONmanually — the app creates it automatically on first chat.
Visual Studio is optional:
install_pgvector.batfalls back to a prebuilt package and clearly warns about the associated risk.
- Double-click
MultiAgentStudio.exe. - The browser opens automatically, and a tray icon appears (right-click for Open / Status / Quit).
Running from source (development):
python run.py --console(foreground — auto-opens browser + console logs).
- Click ＋ New multi-agent and fill in the form (API key, system prompts, sub-agents, MCP servers, PostgreSQL databases).
- Create the checkpoint database in pgAdmin first (the form reminds you and pre-checks connectivity).
- Open an agent → pick/create a thread → chat with streaming Markdown.
Each multi-agent's identity is bound to
checkpoint_database. After creation, sub-agents cannot be added / removed / renamed, but their prompts / description / MCP tools / models can still be edited.
When upgrading, keep only a handful of "your data" items and overwrite everything else with the new version. Conversation history and long-term memory (checkpoint / store databases) live in PostgreSQL, not in this folder, so overwriting files does not affect them.
⚠️ Important: after upgrading, you must re-runsetup.batto generate a newMultiAgentStudio.exe. Do not keep using the oldMultiAgentStudio.exe— on some upgrades the old exe misbehaves because its bundled frontend/backend code is out of sync with the new version.
| File / directory | Notes |
|---|---|
configs/ |
All multi-agent configs (<agent_id>.json, default.json) and global settings (settings.json). Contains API keys, system prompts, DB connections, thresholds, etc. |
snapshots/ |
Conversation snapshots saved automatically before a full summary (if any were generated). |
.env |
Environment variables (e.g. tokens) read by the local MCP servers. |
.chrome-profile/ |
The automation Chrome profile used by browser takeover (present only if you used it). Keep it to reuse website logins; otherwise you will need to sign in again. |
app/, browser_agent/, run.py, tray.py, launcher.py, scripts/, folder_of_MCPs/, md2print/ (source), requirements.txt, setup.bat, setup.ps1, build_exe.py, build_exe.bat, icon.ico, .env.example, README.md, LICENSE, etc.
venv/ (rebuilt by setup.bat), MultiAgentStudio.exe / dist/ / build/ (built during packaging), logs/ (server logs), __pycache__/ and other caches.
- Back up
configs/,snapshots/, and.env. - Overwrite the remaining files with the new version (or copy the three items above into the freshly extracted folder).
- Must run
setup.batto reinstall dependencies and rebuild a newMultiAgentStudio.exe(do not reuse the old exe). - Double-click the newly built
MultiAgentStudio.exeand confirm history, memory, and snapshots are all intact.
folder_of_MCPs/ contains standalone FastMCP servers (Caiyun weather, AMap). Run them separately and reference them in a sub-agent's mcp_servers via http or stdio transport. Their tokens are read from environment variables — see .env.example.