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 global and China 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 uv

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

# macOS/Linux/WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
python -m pip install --user pipx
python -m pipx ensurepath
# Restart PowerShell after installation

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

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
uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git

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

# Windows (PowerShell):
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/scripts/setup-config.ps1" -OutFile "$env:TEMP\setup-config.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\setup-config.ps1"

💡 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.minimax.io/anthropic"  # Global
# api_base: "https://api.minimaxi.com/anthropic"  # China
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

# Management commands
uv tool upgrade mini-agent                    # Upgrade to latest version
uv tool uninstall mini-agent                  # Uninstall if needed
uv tool list                                  # View all installed tools

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)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal after installation

# 3. Sync dependencies
uv sync

# Alternative: Install dependencies manually (if not using uv)
# pip install -r requirements.txt
# Or install required packages:
# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp

# 4. Initialize Claude Skills (Optional)
git submodule update --init --recursive

# 5. Copy config template

macOS/Linux:

cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml

Windows:

Copy-Item mini_agent\config\config-example.yaml mini_agent\config\config.yaml

# 6. 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.minimax.io/anthropic"  # Global
# api_base: "https://api.minimaxi.com/anthropic"  # China
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)
uv tool 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

If you encounter [SSL: CERTIFICATE_VERIFY_FAILED] error:

Quick fix for testing (modify mini_agent/llm.py):

# Line 50: Add verify=False to AsyncClient
async with httpx.AsyncClient(timeout=120.0, verify=False) as client:

Production solution:

# Update certificates
pip install --upgrade certifi

# Or configure system proxy/certificates

Make sure you're running from the project directory:

cd Mini-Agent
python -m mini_agent.cli

• 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!