Mini-Agent

Mini Agent

English | 中文

Mini Agent is a minimal yet professional demo project that showcases the best practices for building agents with the MiniMax M2.5 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.

Table of Contents

• Mini Agent
  • Table of Contents
  • Quick Start
    • 1. Get API Key
    • 2. Choose Your Usage Mode
      • Quick Start Mode (Recommended for Beginners)
      • Development Mode
  • ACP & Zed Editor Integration(optional)
  • Usage Examples
    • Task Execution
    • Using a Claude Skill (e.g., PDF Generation)
    • Web Search & Summarization (MCP Tool)
  • Testing
    • Quick Run
    • Test Coverage
  • Troubleshooting
    • SSL Certificate Error
    • Module Not Found Error
  • Related Documentation
  • Community
  • Contributing
  • License
  • References

Quick Start

1. Get API Key

MiniMax provides both global and China platforms. Choose based on your network environment:

Version Platform API Base Global https://platform.minimax.io https://api.minimax.io China https://platform.minimaxi.com https://api.minimaxi.com

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

2. Choose Your Usage Mode

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:

Quick Start Mode (Recommended for Beginners)

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"  # Global
# api_base: "https://api.minimaxi.com"  # China
model: "MiniMax-M2.5"

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

Development Mode

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

Installation & Configuration:

…

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"  # Global
# api_base: "https://api.minimaxi.com"  # China
model: "MiniMax-M2.5"
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

ACP & Zed Editor Integration(optional)

Mini Agent supports the Agent Communication Protocol (ACP) for integration with code editors like Zed.

Setup in Zed Editor:

1. Install Mini Agent in development mode or as a tool
2. Add to your Zed settings.json:

{
  "agent_servers": {
    "mini-agent": {
      "command": "/path/to/mini-agent-acp"
    }
  }
}

The command path should be:

• If installed via uv tool install: Use the output of which mini-agent-acp
• If in development mode: ./mini_agent/acp/server.py

Usage:

• Open Zed's agent panel with Ctrl+Shift+P → "Agent: Toggle Panel"
• Select "mini-agent" from the agent dropdown
• Start conversations with Mini Agent directly in your editor

Usage Examples

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

Task Execution

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.

Using a Claude Skill (e.g., PDF Generation)

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.

Web Search & Summarization (MCP Tool)

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

Testing

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

Quick Run

# Run all tests
pytest tests/ -v

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

Test Coverage

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

Troubleshooting

SSL Certificate Error

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

Module Not Found Error

Make sure you're running from the project directory:

cd Mini-Agent
python -m mini_agent.cli

Related Documentation

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

Community

Join the MiniMax official community to get help, share ideas, and stay updated:

• WeChat Group: Scan the QR code on Contact Us page to join

Contributing

Issues and Pull Requests are welcome!

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

License

This project is licensed under the MIT License.

References

• MiniMax API: https://platform.minimax.io/docs
• 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!