English | 中文

Mini Agent is a minimal yet professional demo project that showcases the best practices for building agents with the MiniMax M2 model. Leveraging an Anthropic-compatible API, it fully supports interleaved thinking to unlock M2's powerful reasoning capabilities for long, complex tasks.

This project comes packed with features designed for a robust and intelligent agent development experience:

• ✅ Full Agent Execution Loop: A complete and reliable foundation with a basic toolset for file system and shell operations.
• ✅ Persistent Memory: An active Session Note Tool ensures the agent retains key information across multiple sessions.
• ✅ Intelligent Context Management: Automatically summarizes conversation history to handle contexts up to a configurable token limit, enabling infinitely long tasks.
• ✅ Claude Skills Integration: Comes with 15 professional skills for documents, design, testing, and development.
• ✅ MCP Tool Integration: Natively supports MCP for tools like knowledge graph access and web search.
• ✅ Comprehensive Logging: Detailed logs for every request, response, and tool execution for easy debugging.
• ✅ Clean & Simple Design: A beautiful CLI and a codebase that is easy to understand, making it the perfect starting point for building advanced agents.

• Mini Agent
  • Table of Contents
  • Quick Start
    • 1. Get API Key
    • 2. Choose Your Usage Mode
      • 🚀 Quick Start Mode (Recommended for Beginners)
      • 🔧 Development Mode
  • Usage Examples
    • Task Execution
    • Using a Claude Skill (e.g., PDF Generation)
    • Web Search & Summarization (MCP Tool)
  • Testing
    • Quick Run
    • Test Coverage
  • Related Documentation
  • Contributing
  • License
  • References

MiniMax provides both domestic (China) and overseas platforms. Choose based on your network environment:

Steps to get API Key:

1. Visit the corresponding platform to register and login
2. Go to Account Management > API Keys
3. Click "Create New Key"
4. Copy and save it securely (key is only shown once)

💡 Tip: Remember the API Base address corresponding to your chosen platform, you'll need it for configuration

Prerequisites: Install pipx

Both usage modes require pipx. If you don't have it installed:

# macOS
brew install pipx
pipx ensurepath

# Linux
sudo apt install pipx  # Debian/Ubuntu
pipx ensurepath

# After installation, restart your terminal or run:
source ~/.bashrc  # or ~/.zshrc

We offer two usage modes - choose based on your needs:

Perfect for users who want to quickly try Mini Agent without cloning the repository or modifying code.

Installation:

# 1. Install directly from GitHub
pipx install git+https://github.com/MiniMax-AI/Mini-Agent.git

# 2. Run setup script (automatically creates config files)
curl -fsSL https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.sh | bash

💡 Tip: If you want to develop locally or modify code, use "Development Mode" below

Configuration:

The setup script creates config files in ~/.mini-agent/config/. Edit the config file:

# Edit config file
nano ~/.mini-agent/config/config.yaml

Fill in your API Key and corresponding API Base:

api_key: "YOUR_API_KEY_HERE"          # API Key from step 1
api_base: "https://api.minimaxi.com/anthropic"  # Domestic (China)
# api_base: "https://api.minimax.io/anthropic"  # Overseas (uncomment if using overseas platform)
model: "MiniMax-M2"

Start Using:

mini-agent                                    # Use current directory as workspace
mini-agent --workspace /path/to/your/project  # Specify workspace directory
mini-agent --version                          # Check version

For developers who need to modify code, add features, or debug.

Installation & Configuration:

# 1. Clone the repository
git clone https://github.com/MiniMax-AI/Mini-Agent.git
cd Mini-Agent

# 2. Install uv (if you haven't)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Sync dependencies
uv sync

# 4. Copy config template
cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml

# 5. Edit config file
vim mini_agent/config/config.yaml  # Or use your preferred editor

Fill in your API Key and corresponding API Base:

api_key: "YOUR_API_KEY_HERE"          # API Key from step 1
api_base: "https://api.minimaxi.com/anthropic"  # Domestic (China)
# api_base: "https://api.minimax.io/anthropic"  # Overseas (uncomment if using overseas platform)
model: "MiniMax-M2"
max_steps: 100
workspace_dir: "./workspace"

📖 Full configuration guide: See config-example.yaml

Run Methods:

Choose your preferred run method:

# Method 1: Run as module directly (good for debugging)
uv run python -m mini_agent.cli

# Method 2: Install in editable mode (recommended)
pipx install -e .
# After installation, run from anywhere and code changes take effect immediately
mini-agent
mini-agent --workspace /path/to/your/project

📖 For more development guidance, see Development Guide

📖 For more production deployment guidance, see Production Guide

Here are a few examples of what Mini Agent can do.

In this demo, the agent is asked to create a simple, beautiful webpage and display it in the browser, showcasing the basic tool-use loop.

Here, the agent leverages a Claude Skill to create a professional document (like a PDF or DOCX) based on the user's request, demonstrating its advanced capabilities.

This demo shows the agent using its web search tool to find up-to-date information online and summarize it for the user.

The project includes comprehensive test cases covering unit tests, functional tests, and integration tests.

# Run all tests
pytest tests/ -v

# Run core functionality tests
pytest tests/test_agent.py tests/test_note_tool.py -v

• ✅ Unit Tests - Tool classes, LLM client
• ✅ Functional Tests - Session Note Tool, MCP loading
• ✅ Integration Tests - Agent end-to-end execution
• ✅ External Services - Git MCP Server loading

• Development Guide - Detailed development and configuration guidance
• Production Guide - Best practices for production deployment

Issues and Pull Requests are welcome!

• Contributing Guide - How to contribute
• Code of Conduct - Community guidelines

This project is licensed under the MIT License.

• MiniMax API: https://platform.minimaxi.com/document
• MiniMax-M2: https://github.com/MiniMax-AI/MiniMax-M2
• Anthropic API: https://docs.anthropic.com/claude/reference
• Claude Skills: https://github.com/anthropics/skills
• MCP Servers: https://github.com/modelcontextprotocol/servers

⭐ If this project helps you, please give it a Star!