Mini Box Agent

English | 中文

Mini Box Agent is a minimal yet professional AI agent with Python sandbox capabilities for data analysis. It supports multiple LLM providers (Anthropic, OpenAI) and features interleaved thinking for powerful reasoning on 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.
• ✅ Python Sandbox: Secure Jupyter-based Python execution with pandas, numpy, matplotlib support. Includes timeout, memory limits, and dangerous command blocking.
• ✅ 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 Box 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. Install

Prerequisites: Install uv

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

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal after installation

Install Mini Box Agent:

# Install in editable mode
cd /path/to/Mini-Agent_opencode
uv tool install -e .

# Or install from PyPI (when published)
uv tool install mini-box-agent

2. Run - Interactive Setup

Simply run:

mini-box

On first run, you'll be guided through interactive setup:

1. Select LLM Provider (Anthropic or OpenAI)
2. Enter API Base URL (defaults provided for official APIs)
3. Select Model (common options provided)
4. Enter API Key
5. API Key will be validated automatically

Usage:

mini-box                                    # Use current directory as workspace
mini-box --workspace /path/to/project      # Specify workspace directory
mini-box --task "analyze data.csv"        # Run task non-interactively
mini-box --validate                        # Validate existing API key
mini-box --version                         # Check version
mini-box log                               # View logs

# Management
uv tool upgrade mini-box                   # Upgrade
uv tool uninstall mini-box                 # Uninstall

3. Configuration

Configuration is stored in ~/.mini-box-agent/config/config.yaml.

Manual configuration:

api_key: "YOUR_API_KEY_HERE"
provider: "anthropic"  # or "openai"
api_base: "https://api.anthropic.com"  # or your custom endpoint
model: "claude-3-5-sonnet"  # or your chosen model

Development Mode

For developers who need to modify code:

# Clone and install
git clone https://github.com/your-repo/Mini-Agent.git
cd Mini-Agent
uv sync

# Run directly
uv run python -m mini_box_agent.cli

# Or install in editable mode
uv tool install -e .

📖 For more development guidance, see Development Guide

ACP & Zed Editor Integration(optional)

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

Setup in Zed Editor:

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

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

The command path should be:

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

Usage:

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

Usage Examples

Here are a few examples of what Mini Box 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.

Python Sandbox

Mini Box Agent includes a secure Jupyter-based Python execution sandbox for data analysis and visualization tasks.

Features:

• Secure Execution: Blocks dangerous commands (os, subprocess, eval, exec)
• Timeout Control: 300 second timeout per execution prevents infinite loops
• Memory Limits: Detects and prevents memory-intensive operations
• Persistent State: Variables persist within a session
• Rich Libraries: pandas, numpy, matplotlib, scipy pre-installed

Usage:

mini-box --sandbox    # Enable sandbox (default)
mini-box --no-sandbox # Disable sandbox

# In chat, use execute_code tool:
# > Analyze this CSV file and create a visualization

Example Code Execution:

>>> import pandas as pd
>>> df = pd.read_csv('data.csv')
>>> df.describe()

Security:

• Blocked: import os, subprocess, eval(), exec(), sys.exit()
• Blocked: Absolute file paths like open('/etc/passwd')
• Sandboxed: Each session runs in isolated directory

Multi-Sandbox for Parallel Analysis

For analyzing multiple files simultaneously, use the multi_sandbox tool:

# Create two isolated sessions
multi_sandbox(action="create")  # Returns session_id_1
multi_sandbox(action="create")  # Returns session_id_2

# Execute in parallel
multi_sandbox(action="execute", session_id=session_id_1, code="import pandas as pd; df1 = pd.read_csv('file1.csv')")
multi_sandbox(action="execute", session_id=session_id_2, code="import pandas as pd; df2 = pd.read_csv('file2.csv')")

# List active sessions
multi_sandbox(action="list")

# Clean up
multi_sandbox(action="close", session_id=session_id_1)
multi_sandbox(action="close_all")

Use cases:

• Parallel data analysis on multiple files
• Isolated analysis to prevent interference
• Long-running tasks that don't block each other

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
• ✅ Sandbox Tests - Security blocking, timeout, interrupt, kernel management, multi-sandbox isolation
• ✅ 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_box_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_box_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

• Anthropic API: https://docs.anthropic.com/claude/reference
• OpenAI API: https://platform.openai.com/docs
• Claude Skills: https://github.com/anthropics/skills
• MCP Servers: https://github.com/modelcontextprotocol/servers

---

Release Process

Build and Publish to PyPI

1. Set PyPI Token

   export UV_PUBLISH_TOKEN="your-pypi-token"
   

2. Clean and Build

   rm -rf dist
   uv build
   

3. Publish to PyPI

   uv publish
   

4. Verify

   pip install mini-box-agent
   

TestPyPI (before production)

# Publish to TestPyPI first
uv publish --repository testpypi

# Test installation
pip install --index-url https://test.pypi.org/simple/ mini-box-agent

Version Bump

Edit pyproject.toml:

[project]
version = "0.2.0"  # Update version

---

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