Skip to content

README_ZH.md

Latest commit

 

History

History
420 lines (268 loc) · 26.7 KB

README_ZH.md

File metadata and controls

420 lines (268 loc) · 26.7 KB
Raw

MS-Agent: 赋能智能体自主探索的轻量级框架


MS-Agent

Homepage | MCP Playground | Paper | Documentation | 中文文档

Documentation Status

modelscope%2Fmodelscope-agent | Trendshift

English

👋 简介

MS-Agent 是一个模块化、可扩展的开源智能体框架，专为复杂任务的长程执行打造。 支持自由组合模型、工具、技能与子智能体，通过可定制的 Harness 统筹任务规划、上下文管理、权限控制与执行反馈，并结合项目记忆与自主调度，打造能够持续推进复杂任务的专属生产力助手。

框架以 Python SDK 为基础，为 CLI、TUI 和 WebUI 提供统一的执行与管理能力，支持从终端、浏览器工作台到业务系统的能力复用，减少多端适配与维护成本。

核心特性 · 安装 · 应用项目 · 文档

社区交流与反馈：Discord · GitHub Issues

微信群与 Discord 二维码
Discord 微信群
Discord 社区二维码 微信群二维码

旧版体验与文档：ModelScope-Agent 0.8.0 及更早版本。

🎉 新闻

  • 🚀 2026年7月13日：支持 Agent Hub —— 通过 ms-agent agent 命令在本地与远端 ModelScope 仓库之间管理 agent 工作区文件：上传/下载、后台同步（watch）、跨框架转换、状态查看、备份与恢复，覆盖 qoder、qwenpaw、openclaw、hermes、nanobot、openhuman 与 ms-agent。

  • 🏆 2026年4月9日：Agentic Insight v2 在 DeepResearch Bench 上位列开源方案 #2（总榜 #5）——提交版本得分 55.31（Qwen3.5-Plus + GPT 5.2）。排行榜 | Agentic Insight v2。

  • 🚀 2026年3月23日：发布 MS-Agent v1.6.0，主要更新内容如下：

    • 上下文压缩：新增上下文压缩机制，支持 Token 用量监控与溢出检测，通过裁剪历史工具输出和 LLM 摘要自动压缩对话上下文。
    • Agentic Insight v2 增强：深度研究系统架构与性能大幅优化，基于 GPT5、Qwen3.5-plus/flash 模型组合在 DeepResearch Bench 上的评分达到 55.43 分。详情请参考 Agentic Insight v2。
    • 知识库搜索：集成 Sirchmunk 智能检索，支持在 Agent 对话中自动检索本地代码库与文档，详情请参考配置文档。
    • 多模态模型输入：支持图片、视频等多模态输入，详情请参考多模态文档。

  • 🚀 2026年2月6日：发布 MS-Agent v1.6.0rc1，主要更新内容如下：

    • Agentic Insight v2：完整重构的深度研究系统，性能更优、可扩展性更强、可信度更高，提供了 WebUI 入口，详情请参考 Agentic Insight v2

  • 🚀 2026年2月4日：发布 MS-Agent v1.6.0rc0，主要更新内容如下：

    • Code Genesis：针对复杂代码生成任务的专项功能，详情请参考 Code Genesis
    • Singularity Cinema：动画视频生成工作流的重构版本，详情请参考 Singularity Cinema
    • 全新技能框架 (Skills Framework)：全新设计的技能系统，显著增强了系统的健壮性与可扩展性。详情请参考 MS-Agent Skills
    • WebUI：新增 Web 交互界面，支持智能体对话、复杂代码生成以及视频生成工作流。
2025 及更早

  • 🎬 2025.11.13: 发布了“奇点放映室”，用于进行知识类文档的复杂场景短视频制作，具体查看这里

  • 🚀 2025.11.12：发布MS-Agent v1.5.0，包含以下更新：

  • 🚀 2025.11.07：发布MS-Agent v1.4.0，包含以下更新：

  • 🚀 2025.9.22：发布MS-Agent v1.3.0，包含以下更新：

    • 🔥 支持Code Scratch
    • 支持Memory用于构建具有长期和短期记忆的智能体
    • 增强DeepResearch工作流
    • 支持RAY加速文档信息提取
    • 支持LLMs的Anthropic API格式

  • 🚀 2025.8.28：发布MS-Agent v1.2.0，包含以下更新：

    • DocResearch现在支持推送到ModelScope、HuggingFace、GitHub以便于分享研究报告。详情请参考Doc Research。
    • DocResearch现在支持将Markdown报告导出为HTML、PDF、PPTX和DOCX格式，详情请参考Doc Research。
    • DocResearch现在支持TXT文件处理和文件预处理，详情请参考Doc Research。

  • 🚀 2025.7.31：发布MS-Agent v1.1.0，包含以下更新：

  • 🔥 支持文档研究，演示：DocResearchStudio - 为智能洞察（DeepResearch）添加通用网络搜索引擎
    • 为Agent与MCP聊天添加最大连续运行次数。

  • 🚀 2025.7.18：发布MS-Agent v1.0.0，改进Agent与MCP聊天的体验，并更新智能洞察的说明文档。

  • 🚀 2025.7.16：发布MS-Agent v1.0.0rc0，包含以下更新：

  • 🔥🔥🔥2024年8月8日：Modelscope-Agent发布了一个新的基于图的代码生成工具CodexGraph，它已被证明在各种代码相关任务上有效且通用，请查看示例。

  • 🔥🔥2024年8月1日：一个高效可靠的数据科学助手正在Modelscope-Agent上运行，请在示例中查看详情。

  • 🔥2024年7月17日：Modelscope-Agent-Server上的并行工具调用，请在文档中查看详情。

  • 🔥2024年6月17日：基于LLama-index升级RAG流程，允许用户通过不同策略和模态混合搜索知识，请在文档中查看详情。

  • 🔥2024年6月6日：通过 Modelscope-Agent-Server，Qwen2 可以通过 OpenAI SDK 使用工具调用能力，详情请查看文档。

  • 🔥2024年6月4日：Modelscope-Agent 支持 Mobile-Agent-V2arxiv，基于 Android Adb 环境，请在应用中查看。

  • 🔥2024年5月17日：Modelscope-Agent 在 gradio 中支持多角色房间聊天。

  • 2024年5月14日：Modelscope-Agent 在 RolePlay 智能体中支持图像输入，使用最新的 OpenAI 模型 GPT-4o。开发者可以通过指定 image_url 参数来体验此功能。

  • 2024年5月10日：Modelscope-Agent 推出了用户友好的 Assistant API，并提供了在隔离、安全容器中执行实用程序的 Tools API，请查看文档

  • 2024年4月12日：多智能体解决方案的 Ray 版本已在 modelscope-agent 上线，请查看文档

  • 2024年3月15日：Modelscope-Agent 和 AgentFabric（GPTs 的开源版本）正在 modelscope studio 的生产环境中运行。

  • 2024年2月10日：在中国新年期间，我们将modelscope agent升级到v0.3版本，以便开发者通过编码更方便地定制各种类型的智能体，并使多智能体演示更容易实现。更多详情，您可以参考#267和#293。

  • 2023年11月26日：AgentFabric现在支持在ModelScope的创作空间中协作使用，允许在创作空间中分享自定义应用程序。此次更新还包括最新的GTE文本嵌入集成。

  • 2023年11月17日：AgentFabric发布，这是一个交互式框架，旨在促进创建针对各种现实世界应用的智能体。

  • 2023年10月30日：Facechain Agent发布了可以在本地运行的Facechain Agent本地版本。详细使用说明请参考Facechain Agent。

  • 2023年10月25日：Story Agent发布了用于生成故事书插图的Story Agent本地版本。它可以在本地运行。详细使用说明请参考Story Agent。

  • 2023年9月20日：ModelScope GPT通过gradio提供了可以在本地运行的本地版本。您可以导航到demo/msgpt/目录并执行bash run_msgpt.sh。

  • 2023年9月4日：新增了三个演示，demo_qwen、demo_retrieval_agent 和 demo_register_tool，并提供了详细的教程。

  • 2023年9月2日：发布了与该项目相关的预印本论文。

  • 2023年8月22日：支持使用 ModelScope 令牌访问各种 AI 模型 API。

  • 2023年8月7日：发布了 modelscope-agent 仓库的初始版本。

✨ 核心特性

🧩 可定制的 Agent Harness

将工具执行、权限确认与过程反馈组织成可扩展的运行机制。通过生命周期回调与 Hooks 接入业务规则、计划检查和结果验证，让开发者能够定制智能体如何行动、何时接受人工干预，以及怎样利用执行反馈继续工作。

🧠 面向长任务的上下文与记忆

将会话历史、当前上下文与项目记忆分层管理：保留完整记录，按需裁剪工具输出、压缩历史内容，并在后续任务中利用项目记忆。配合 Cron 的定时、周期与单次任务调度，支持需要反复推进的研究、巡检和维护工作。

🤝 自主协作与显式工作流编排

开放式任务可以由主智能体动态委派给专用子智能体；阶段和依赖明确的任务，则可使用链式或 DAG 工作流编排。为不同角色选择模型、工具与技能，从自主探索到分步交付，按任务需要组织协作。

📈 可复用、可评测的 Agent Skills

将领域知识与操作方法组织为按需加载的技能，供不同任务复用。独立的 Skill Evolution 工作流进一步利用执行轨迹和评测反馈修订技能，通过验证集筛选更新，为经验积累与能力改进提供可检验的依据。

🔌 开放生态与跨框架资产复用

接入多家模型服务，通过 MCP 连接外部工具，通过 ACP / A2A 对接编辑器与其他智能体，并利用插件组合扩展能力。Agent Hub 支持跨框架转换、合并和同步指令、技能与记忆，让已有积累可以随工作环境迁移；应用也可作为 MCP 服务供外部智能体调用。

🎯 从框架能力到专业应用

从深度研究、软件开发到金融分析与内容创作，内置应用将模型、工具和多智能体协作组织为完整工作流。既可直接用于专业任务，也可作为二次开发的起点，复用已有的设计与领域经验。探索应用项目

🚀 安装

选择适合你的入口。推荐先从 WebUI 体验项目、会话与工具协作；也可以直接使用终端界面，或将 SDK 集成到 Python 应用中。

使用入口 适合的场景
🖥️ WebUI 在浏览器中处理本地项目、查看执行过程与成果
⌨️ TUI 在终端持续对话、管理和恢复会话
🛠️ CLI 执行单次任务，或与脚本配合使用
🐍 Python SDK 自定义智能体并集成到应用

项目支持使用默认的 ModelScope 服务商，可在访问令牌页面获取 API Key。

🖥️ WebUI

MS-Agent WebUI 是面向本地项目的智能体工作台。你可以在浏览器中与模型对话、查看工具执行过程、配置技能和 MCP 工具，并直接浏览或编辑项目文件。

WebUI 演示：活动资料整理与简报生成。 查看任务规划、写入确认与成果检查的实际过程。

webui-demo.mp4

Important

新版 WebUI 请优先从源码安装。 需要 Git、Python 3.12+、Node.js 22.22.0+、pnpm 10.17.1 和 uv 0.5+。

首次配置环境，请先完成 环境准备。已有 Python 和 Node.js 时，用 python3 --version、node --version 确认版本；如果尚未创建 Python 环境，可在准备存放项目的目录执行：

python3 -m venv ms-agent-env
source ms-agent-env/bin/activate

创建前请确认 python3 为 3.12+。已有虚拟环境或 Conda 环境的用户直接激活即可。然后在同一终端中安装并启动：

npm install --global pnpm@10.17.1
git clone https://github.com/modelscope/ms-agent.git
cd ms-agent
pip install uv
pip install -e .
ms-agent ui

首次启动会通过 uv 准备后端环境、安装前端依赖并构建页面和样式，需要保持网络连接。就绪后浏览器会打开终端显示的地址，通常是 **http://127.0.0.1:8000**。在 设置 → 模型设置 选择服务商，点击 编辑 保存 API Key，再通过 添加模型 填写模型 ID。返回对话页，在输入框下方选中该模型即可开始使用。按 Ctrl-C 停止服务。

ms-agent ui --port 8080    # 指定访问端口
ms-agent ui --no-browser  # 不自动打开浏览器

虚拟环境准备、开发、Docker 和配置说明见 WebUI 完整指南。

⌨️ 终端与 SDK

TUI、CLI 和 Python SDK 需要 Python 3.10+，无需安装 Node.js 或 pnpm。还没有合适的 Python 时，可用 uv 准备 Python 环境。已有 Python 时，先用 python3 --version 确认版本，再创建并激活环境：

python3 -m venv ms-agent-env
source ms-agent-env/bin/activate

已有虚拟环境或 Conda 环境的用户直接激活即可。已完成 WebUI 安装的用户，可跳过环境创建和源码安装，直接在同一环境中配置 API Key。其余用户继续执行：

git clone https://github.com/modelscope/ms-agent.git
cd ms-agent
pip install -e .

以下示例默认使用 ModelScope 推理服务，在运行命令或 Python 程序的终端中设置：

export MODELSCOPE_API_KEY="your_modelscope_api_key"

首次使用默认智能体时，会按需安装本地代码执行所需的额外依赖。请保持网络连接，等待出现输入提示或任务结果。

⌨️ TUI

启动终端交互界面，输入任务即可开始。使用 /help 查看会话管理等命令，使用 /quit 退出：

ms-agent tui

🛠️ CLI

直接执行一个任务；不传 --query 时进入交互模式：

ms-agent run --query "介绍一下 MS-Agent 的应用场景"

🐍 Python SDK

将下面的代码保存为 quickstart.py，在已配置 API Key 的同一终端中运行 python quickstart.py：

import asyncio
from ms_agent import LLMAgent

async def main():
    agent = LLMAgent()
    await agent.run("介绍一下 MS-Agent 的应用场景")

asyncio.run(main())
可选依赖与已发布版本

在源码仓库根目录、已激活的 Python 环境中，可以按需安装扩展依赖：

# 向量 / 混合技能检索
pip install -e '.[retrieval]'

# 深度研究 / 文档解析
pip install -e '.[research]'

# 视频生成
pip install -e '.[cinema]'

# 全部运行时扩展（包含 WebUI，需 Python 3.12+）
pip install -e '.[all]'

完整列表见安装指南。这些命令中的引号需要保留，避免 macOS 默认的 zsh 将方括号作为文件匹配表达式。

PyPI 已发布版本目前为 1.6.0，使用旧版 WebUI 和依赖组合，不包含当前源码的 TUI，也没有 retrieval、cinema extras。新环境请使用上面的源码安装；版本差异与已知安装问题见安装指南。

重新打开终端后，需要再次激活 Python 环境。WebUI 用户运行 ms-agent ui 即可；终端与 SDK 用户还需重新设置 API Key，或按配置文档将其保存在 .env 文件中。

⚙️ 配置与扩展

完成首次对话后，可以按需更换模型、接入 MCP 工具或加载技能。WebUI 可在设置中管理这些配置；终端与 SDK 的用法见模型与配置参考、工具与 MCP和Agent Skills。也可以在 MCP Playground 在线体验工具调用。

定时任务 ms-agent cron、Agent Hub ms-agent agent 及更多命令见 CLI 参考。

🎯 应用项目

这些应用将框架用于完整的专业任务，也提供可供二次开发的智能体编排、工具与工作流。你可以按场景选择应用，或借鉴其中的设计构建自己的系统。各项目的模型、依赖与运行方式见对应使用指南。

🔎 Agentic Insight · 从研究问题到证据驱动的报告

围绕开放式研究问题，Researcher 编排 Searcher 与 Reporter 迭代开展检索、证据整理和报告撰写。v2 将结构化中间产物保存在文件系统中，并将报告论述显式绑定到证据，便于追溯来源、检查研究过程与继续任务。

2026 年 4 月 9 日，Agentic Insight v2 在 DeepResearch Bench 获得 55.31 分（Qwen3.5-Plus + GPT 5.2），当时位列开源方案第 2、总榜第 5。

v2 使用指南 · 报告演示 · 评测结果 · v1 基础与扩展工作流

💻 CodeGenesis · 从自然语言需求到软件项目

将需求分析、架构设计、文件规划、编码与修正组织为多智能体开发流程。按文件依赖关系安排生成顺序，结合 LSP 诊断与运行反馈迭代代码；提供七阶段标准流程和四阶段简化流程，适配需要详细设计的项目与快速原型。

设计与使用指南 · 项目源码 · 工作流示意

📊 FinResearch · 结合金融数据与市场信息的研究

由五个专用智能体协作完成任务拆解、数据采集、量化分析、舆情研究与报告汇总。结合 AkShare / BaoStock 的结构化金融数据和互联网公开信息，将数据分析、可视化与定性研究整合为图文报告。

使用指南 · 在线体验 · 报告样例 · 视频演示

📑 DocResearch · 将多份资料整理为图文报告

面向论文阅读与资料研究，接收多份文档或 URL，提取关键信息并生成包含图表的研究报告。支持 PDF、TXT、PPT、DOCX 等输入，以及 PDF、PPTX、DOCX、HTML 报告导出，便于将研究成果用于阅读、汇报和分享。

使用指南 · 在线体验

🎬 Singularity Cinema · 奇点放映室

从主题或纯文本资料出发，编排台本、分镜、配音、画面生成与视频合成，将知识内容转化为短视频。面向科普、技术原理与经济类讲解，可组合图片、字幕和生成视频等素材，定制自己的创作流程。

使用指南与更多作品 · 点击下方预览观看「如何部署大语言模型」：

奇点放映室作品：如何部署大语言模型

🧬 Skill Evolution · 用任务反馈改进技能

面向可自动评测的任务，运行当前技能、收集轨迹与得分，再由反思和技能管理智能体提炼经验、创建或修订技能。候选更新经过验证集筛选，只有表现提升才被接受；内置 SearchQA 基线，便于研究技能如何从任务经验中持续改进。

工作流与运行指南

📚 文档

  • 用户文档：快速开始、核心组件、能力扩展与配置参考。
  • 贡献指南：参与框架与应用开发。

📄 许可证

本项目采用 Apache License 2.0。

⭐ Star 历史

Star History Chart