MS-Agent: Lightweight Framework for Empowering Agents with Autonomous Exploration

MCP Playground | Paper | Documentation | 中文文档

中文

Introduction

MS-Agent is a lightweight framework designed to empower agents with autonomous exploration capabilities. It provides a flexible and extensible architecture that allows developers to create agents capable of performing complex tasks, such as code generation, data analysis, and tool calling for general purposes with MCP (Model Calling Protocol) support.

Features

• Multi-Agent for general purpose: Chat with agent with tool-calling capabilities based on MCP.
• Deep Research: To enable advanced capabilities for autonomous exploration and complex task execution.
• Code Generation: Supports code generation tasks with artifacts.
• Short Video Generation：Support video generation of about 5 minutes.
• Agent Skills: Knowledge-driven skill system — skills provide reusable procedural knowledge that guides the model via standard tool integration, with multi-source loading, progressive disclosure, and runtime self-evolution. See Agent Skills.
• WebUI: Local React Router and FastAPI workspace with SSE-streamed agent interaction.
• Lightweight and Extensible: Easy to extend and customize for various applications.

[WARNING] For historical archive versions, please refer to: https://github.com/modelscope/ms-agent/tree/0.8.0

Discord Group	WeChat Group

🎉 News

• 🚀 Jul 13, 2026: Support Agent Hub — manage agent workspace files across your local machine and remote ModelScope repositories via the ms-agent agent command: upload/download, background sync (watch), cross-framework conversion, status, backups and restore across qoder, qwenpaw, openclaw, hermes, nanobot, openhuman and ms-agent.

• 🏆 Apr 09, 2026: Agentic Insight v2 is now #2 Open-Source (#5 Overall) on DeepResearch Bench — scoring 55.31 with the submitted version (Qwen3.5-Plus + GPT 5.2). Leaderboard | Agentic Insight v2.

• 🚀 Mar 23, 2026: Release MS-Agent v1.6.0, which includes the following updates:

  • Context Compression: Added context compression mechanism with token usage monitoring, overflow detection, and automatic context compaction via pruning historical tool outputs and LLM-based summarization.
  • Agentic Insight v2 Enhancements: Major architecture and performance improvements to the deep research system; achieves 55.43 on DeepResearch Bench with GPT5 and Qwen3.5-plus/flash. See Agentic Insight v2.
  • Knowledge Search: Integrated Sirchmunk for intelligent retrieval over local codebases and documentation during agent conversations. See Config Docs.
  • Multimodal Model Input: Support image, video, and other multimodal inputs. See Multimodal Docs.

• 🚀 Feb 06, 2026: Release MS-Agent v1.6.0rc1, which includes the following updates:

  • Agentic Insight v2: A fully refactored deep-research system with better performance, scalability, and trustworthiness, available in the legacy WebUI (the current WebUI has no dedicated Deep Research view — run it from the CLI). See Agentic Insight v2.

• 🚀 Feb 04, 2026: Release MS-Agent v1.6.0rc0, which includes the following updates:

  • Code Genesis for complex code generation tasks, refer to Code Genesis
  • Singularity Cinema for animated video generation workflow, refactored version, refer to Singularity Cinema
  • Agent Skills v2: Knowledge-driven skill system — skills as procedural knowledge with progressive disclosure, multi-source loading, and standard tool integration. Refer to Agent Skills.
  • WebUI: A new WebUI has been added, featuring agentic chatting capabilities, complex code generation and video generation workflow. (Superseded — see the current WebUI guide.)

• 🎬 Nov 13, 2025: Release Singularity Cinema, to support short video generation for complex scenarios, check here

• 🚀 Nov 12, 2025: Release MS-Agent v1.5.0, which includes the following updates:

  • 🔥 We present FinResearch, a multi-agent workflow tailored for financial research
  • Support financial data collection via Akshare and Baostock
  • Support DagWorkflow for workflow orchestration
  • Optimize the DeepResearch workflow for stability and efficiency
  • FinResearch official documentation: FinResearch Doc
  • DEMO: FinResearchStudio
  • Examples: FinResearchExamples

• 🚀 Nov 07, 2025: Release MS-Agent v1.4.0, which includes the following updates:

  • 🔥 We present MS-Agent Skills, an Implementation of Anthropic-Agent-Skills Protocol.
  • 🔥 Add Docs and 中文文档
  • 🔥 Support Sandbox Framework ms-enclave

• 🚀 Sep 22, 2025: Release MS-Agent v1.3.0, which includes the following updates:

  • 🔥 Support Code Scratch
  • Support Memory for building agents with long-term and short-term memory
  • Enhance the DeepResearch workflow
  • Support RAY for accelerating document information extraction
  • Support Anthropic API format for LLMs

• 🚀 Aug 28, 2025: Release MS-Agent v1.2.0, which includes the following updates:

  • DocResearch now supports pushing to ModelScope、HuggingFace、GitHub for easy sharing of research reports. Refer to Doc Research for more details.
  • DocResearch now supports exporting the Markdown report to HTML、PDF、PPTX and DOCX formats, refer to Doc Research for more details.
  • DocResearch now supports TXT file processing and file preprocessing, refer to Doc Research for more details.

Installation

Install from PyPI

# For the basic functionalities
pip install ms-agent

# For the deep research functionalities
pip install 'ms-agent[research]'

Install from source

git clone https://github.com/modelscope/ms-agent.git

cd ms-agent
pip install -e .

[!WARNING] As the project has been renamed to ms-agent, for versions v0.8.0 or earlier, you can install using the following command:

pip install modelscope-agent<=0.8.0

To import relevant dependencies using modelscope_agent:

from modelscope_agent import ...

Quickstart

Agent Chat

This project supports interaction with models via the MCP (Model Context Protocol). Below is a complete example showing how to configure and run an LLMAgent with MCP support.

✅ Chat with agents using the MCP protocol: MCP Playground

By default, the agent uses ModelScope's API inference service. Before running the agent, make sure to set your ModelScope API key.

export MODELSCOPE_API_KEY={your_modelscope_api_key}

You can find or generate your API key at https://modelscope.cn/my/myaccesstoken.

import asyncio

from ms_agent import LLMAgent

# Configure MCP servers
mcp = {
  "mcpServers": {
    "fetch": {
      "type": "streamable_http",
      "url": "https://mcp.api-inference.modelscope.net/{your_mcp_uuid}/mcp"
    }
  }
}

async def main():
    # Use json to configure MCP
    llm_agent = LLMAgent(mcp_config=mcp)   # Run task
    await llm_agent.run('Introduce modelscope.cn')

if __name__ == '__main__':
    # Start
    asyncio.run(main())

💡 Tip: You can find available MCP server configurations at modelscope.cn/mcp.

For example: https://modelscope.cn/mcp/servers/@modelcontextprotocol/fetch. Replace the url in mcp["mcpServers"]["fetch"] with your own MCP server endpoint.

pip install mem0ai
export MODELSCOPE_API_KEY={your_modelscope_api_key}
export DASHSCOPE_API_KEY={your_dashscope_api_key}

import uuid
import asyncio
from omegaconf import OmegaConf
from ms_agent.agent.loader import AgentLoader


async def main():
    random_id = str(uuid.uuid4())
    default_memory = OmegaConf.create({
        'memory': [{
            'path': f'output/{random_id}',
            'user_id': 'awesome_me'
        }]
    })
    agent1 = AgentLoader.build(config_dir_or_id='ms-agent/simple_agent', config=default_memory)
    agent1.config.callbacks.remove('input_callback')  # Disable interactive input for direct output

    await agent1.run('I am a vegetarian and I drink coffee every morning.')
    del agent1
    print('========== Data preparation completed, starting test ===========')
    agent2 = AgentLoader.build(config_dir_or_id='ms-agent/simple_agent', config=default_memory)
    agent2.config.callbacks.remove('input_callback')  # Disable interactive input for direct output

    res = await agent2.run('Please help me plan tomorrow’s three meals.')
    print(res)
    assert 'vegan' in res[-1].content.lower() and 'coffee' in res[-1].content.lower()

asyncio.run(main())

Agent Skills

The MS-Agent Skill Module is Implementation of Anthropic-Agent-Skills Protocol.

🔍 Intelligent Skill Retrieval

• Hybrid Search: Combines FAISS dense retrieval with BM25 sparse retrieval
• LLM-based Filtering: Uses LLM to filter and validate skill relevance
• Query Analysis: Automatically determines if skills are needed for a query

📊 DAG-based Execution

• Dependency Management: Builds execution DAG based on skill dependencies
• Parallel Execution: Runs independent skills concurrently
• Input/Output Linking: Automatically passes outputs between dependent skills

🧠 Progressive Skill Analysis

• Two-phase Analysis: Plan first, then load resources
• Incremental Loading: Only loads required scripts/references/resources
• Context Optimization: Minimizes token usage while maximizing understanding
• Auto Bug Fixing: Analyzes errors and attempts automatic fixes

🔒 Secure Execution Environment

• Docker Sandbox: Isolated execution using ms-enclave containers
• Local Execution: Controlled local execution with RCE prevention
• Security Checks: Pattern-based detection of dangerous code

🔄 Self-Reflection & Retry

• Error Analysis: LLM-based analysis of execution failures
• Auto-Fix: Attempts to fix code based on error messages
• Configurable Retries: Up to N retry attempts with fixes

For more details, please refer to MS-Agent Skills.

Agentic Insight (Deep Research)

- Lightweight, Efficient, and Extensible Multi-modal Deep Research Framework

This project provides a framework for Deep Research, enabling agents to autonomously explore and execute complex tasks.

🌟 Features

• Autonomous Exploration - Autonomous exploration for various complex tasks

• Multimodal - Capable of processing diverse data modalities and generating research reports rich in both text and images.

• Lightweight & Efficient - Support "search-then-execute" mode, completing complex research tasks within few minutes, significantly reducing token consumption.

🚀 Agentic Insight v2 (Recommended)

• Performance: #2 Open-Source (#5 Overall) on DeepResearch Bench — 55.31 with the submitted version (Qwen3.5-Plus + GPT 5.2).
• Deep Agents architecture: "Researcher + tool-augmented sub-agents (Searcher/Reporter)" for flexible task allocation and efficient concurrency.
• File system as context: Structured artifacts persisted to disk for low-loss context handoff and stable long-horizon runs (resume-friendly).
• Evidence-driven writing: Reports are grounded in an indexed evidence base, improving trustworthiness and traceability.
• Deep-research toolchain: Decoupled modules like todo list / evidence store / report generator for reuse and extensibility.

See Agentic Insight v2.

📺 Demonstration

Here is a demonstration of the Agentic Insight framework in action, showcasing its capabilities in handling complex research tasks efficiently.

• User query

• • Chinese:

在计算化学这个领域，我们通常使用Gaussian软件模拟各种情况下分子的结构和性质计算，比如在关键词中加入'field=x+100'代表了在x方向增加了电场。但是，当体系是经典的单原子催化剂时，它属于分子催化剂，在反应环境中分子的朝向是不确定的，那么理论模拟的x方向电场和实际电场是不一致的。

请问：通常情况下，理论计算是如何模拟外加电场存在的情况？

• • English:

In the field of computational chemistry, we often use Gaussian software to simulate the structure and properties of molecules under various conditions. For instance, adding 'field=x+100' to the keywords signifies an electric field applied along the x-direction. However, when dealing with a classical single-atom catalyst, which falls under molecular catalysis, the orientation of the molecule in the reaction environment is uncertain. This means the x-directional electric field in the theoretical simulation might not align with the actual electric field.

So, how are external electric fields typically simulated in theoretical calculations?

Report

https://github.com/user-attachments/assets/b1091dfc-9429-46ad-b7f8-7cbd1cf3209b

For more details, please refer to Deep Research.

Doc Research

This project provides a framework for Doc Research, enabling agents to autonomously explore and execute complex tasks related to document analysis and research.

Features

• 🔍 Deep Document Research - Support deep analysis and summarization of documents
• 📝 Multiple Input Types - Support multi-file uploads and URL inputs
• 📊 Multimodal Reports - Support text and image reports in Markdown format
• 🚀 High Efficiency - Leverage powerful LLMs for fast and accurate research, leveraging key information extraction techniques to further optimize token usage
• ⚙️ Flexible Deployment - Support local run and ModelScope Studio
• 💰 Free Model Inference - Free LLM API inference calls for ModelScope users, refer to ModelScope API-Inference

Demo

1. ModelScope Studio DocResearchStudio

2. Local Gradio Application

• Research Report for UniME: Breaking the Modality Barrier: Universal Embedding Learning with Multimodal LLMs

Demo：UniME Research Report

For more details, refer to Doc Research

Code Genesis

Code Genesis is a production-ready multi-agent framework that orchestrates specialized AI agents to autonomously generate complete software projects from natural language requirements.

Features

• 🎯 End-to-End Project Generation - From requirement analysis to deployment-ready artifacts with minimal human intervention
• 🔧 Dual Workflow Modes - Standard 7-agent pipeline for production systems, or streamlined 4-agent mode for rapid prototyping
• 🏗️ Topology-Aware Code Generation - Dependency-driven scheduling eliminates hallucinated imports and enables parallel generation
• 📁 LSP-Integrated Validation - Real-time Language Server Protocol checks ensure syntactic correctness and import resolution
• 🔄 Self-Healing Refinement - Automated runtime verification and deployment

Demo

Homepage

Generate a complete homepage with the following command:

PYTHONPATH=. openai_api_key=your-api-key openai_base_url=your-api-url python ms_agent/cli/cli.py run --config projects/code_genesis --query 'Build a static site to display skills, projects, and contact info' --trust_remote_code true

Demo: Homepage

The generated code will be output to the output folder in the current directory.

Architecture Workflow:

• Standard Pipeline (7 agents): User Story → Architect → File Design → File Order → Install → Coding → Refine
• Simple Pipeline (4 agents): Orchestrator → Install → Coding → Refine

For more details, refer to Code Genesis.

FinResearch

The MS-Agent FinResearch project is a multi-agent workflow tailored for financial market research. It combines quantitative financial data analysis with deep research on online news/sentiment to automatically generate professional research reports.

Key Features

• 🤖 Multi-Agent Architecture: Orchestrates multiple specialized agents to handle task decomposition, data collection, quantitative analysis, sentiment research, and final report generation.

• 📁 Multi-Dimensional Analysis: Covers both financial indicators and public sentiment, enabling fusion analysis of structured and unstructured data.

• 💰 Financial Data Collection: Supports automatic retrieval of quotes, financial statements, macro indicators, and market data for A-share, Hong Kong, and U.S. markets.

• 🔍 In-Depth Sentiment Research: Deep research on multi-source information from news/media/communities.

• 📝 Professional Report Generation: Produces multi-chapter, well-structured, image-and-text reports following common methodologies (MECE, SWOT, Pyramid Principle, etc.).

• 🔒 Secure Code Execution: Runs data processing and analysis inside an isolated Docker sandbox to ensure security and reproducibility.

Quick Start

💡 Tips:

1. Before running the examples below, set the OPENAI_API_KEY and OPENAI_BASE_URL environment variables to access the required model APIs. To run the full workflow, also configure the search engine variables EXA_API_KEY (https://exa.ai) or SERPAPI_API_KEY (https://serpapi.com).
2. FinResearch requires ms-agent version >= 1.5.0.

Usage:

Quickly launch the full FinResearch workflow for testing:

# Run at the ms-agent project root
PYTHONPATH=. python ms_agent/cli/cli.py run --config projects/fin_research --query 'Analyze CATL (300750.SZ) profitability over the past four quarters and compare it with key new-energy competitors (e.g., BYD, Gotion High-Tech, CALB); considering industry policies and lithium price volatility, forecast its performance for the next two quarters.' --trust_remote_code true

You can also run a minimal version without configuring a search engine by adjusting the workflow configuration as follows:

type: DagWorkflow

orchestrator:
  next:
    - collector
  agent_config: orchestrator.yaml

collector:
  next:
    - analyst
  agent_config: collector.yaml

analyst:
  next:
    - aggregator
  agent_config: analyst.yaml

aggregator:
  agent_config: aggregator.yaml

Result:

https://github.com/user-attachments/assets/a11db8d2-b559-4118-a2c0-2622d46840ef

References:

• README: FinResearch
• Documentation: MS-Agent Documentation

WebUI

MS-Agent provides a local agent workspace built with a React Router frontend and a FastAPI backend. Chat responses are streamed with Server-Sent Events (SSE).

Quick Start

The current launcher is intended for a source checkout. Install these tools first:

• uv
• Node.js 22.22.0 or newer
• pnpm 10.x (corepack prepare pnpm@10.17.1 --activate)

From the repository root, install MS-Agent in editable mode and start the WebUI:

pip install -e .
ms-agent ui

On the first run, the launcher creates the backend environment and installs the locked frontend dependencies. Later starts verify those local dependencies. The browser opens at http://127.0.0.1:7860.

Configure a model in Settings → Models before starting a real chat. Environment-variable bootstrap and manual development instructions are available in the WebUI guide.

Windows tip: If the console shows garbled text, use the UTF-8 PowerShell helper:

.\webui\scripts\start-webui.ps1

Examples:

# Use another public frontend port
ms-agent ui --port 8080

# Keep the browser closed
ms-agent ui --no-browser

See the complete WebUI guide for prerequisites, configuration precedence, all launcher options, Windows notes, and troubleshooting. This minimal launcher intentionally does not provide a production SSR mode.

Singularity Cinema

Singularity Cinema is an Agent-powered workflow for generating short videos, capable of producing high-quality complex short videos using either a single-sentence prompt or knowledge-based documents.

Core Features

• 🎬 Supports Both Simple and Complex Requirements: Can work with a single-sentence description or handle complex information files

• 🎹 Sophisticated Tables and Formulas: Can display and interpret formulas and charts within short videos that correspond to the script

• 🎮 End-to-End: From requirements to script to storyboard, from voiceover to charts to subtitles, and finally human feedback and video generation—the entire end-to-end process completed with a single command

• 🏁 High Configurability: Highly configurable with easy adjustments for voice, style, and materials through simple configuration

• 🚧 Customizable: Clear and simple workflow, suitable for secondary development

Quick Start

Usage Example:

OPENAI_API_KEY=xxx-xxx T2I_API_KEY=ms-xxx-xxx MANIM_TEST_API_KEY=xxx-xxx ms-agent run --config "projects/singularity_cinema" --query "Your custom topic" --load_cache true --trust_remote_code true

Results:

An introduction to Deepspeed ZeRO

A history of US GDP

References

• Complete Documentation

Interesting works

1. A news collection agent ms-agent/newspaper

Roadmap

We are committed to continuously improving and expanding the MS-Agent framework to push the boundaries of large models and AI agents. Our future roadmap includes:

• Anthropic Agent Skills - Full support for the Anthropic-Agent-Skills protocol, enabling agents to autonomously explore and execute complex tasks using predefined or custom "skills".
• FinResearch – A financial deep-research agent dedicated to in-depth analysis and research in the finance domain.
  • Long-term deep financial analysis report generation
  • Near real-time event-driven report generation
• Singularity Cinema
  • Support more complex scenarios
  • Improve stabilises
• Multimodal Agentic Search – Supporting large-scale multimodal document retrieval and generation of search results combining text and images.
• Enhanced Agent Skills – Providing a richer set of predefined skills and tools to expand agent capabilities and enabling multi-skill collaboration for complex task execution.
• Agent-Workstation - An unified WebUI with one-click local deployment support with combining all agent capabilities of MS-Agent, such as AgentChat, MCP, AgentSkills, DeepResearch, DocResearch, CodeGenesis, etc.

License

This project is licensed under the Apache License (Version 2.0).

Star History

❤️ Thanks for visiting ✨ MS-Agent !