Blue

January 15, 2026

Introduction to Mini-Agent Framework

Mini-Agent is a minimalist yet professional AI Agent development framework open-sourced by MiniMax, designed to demonstrate best practices for building intelligent agents using the MiniMax M2.1 model. Unlike complex frameworks like LangChain, Mini-Agent adopts a lightweight design that allows developers to reach the essence of Agents and understand their core working principles.

Core Features

Mini-Agent’s design philosophy is Lightweight, Simple, and Extensible. It avoids over-encapsulation and clearly presents the core logic of Agents to developers, helping learners truly understand how Agents work, rather than just learning how to use a framework’s API.

Key Capabilities

Complete Agent Execution Loop

MiniAgent implements a complete Agent execution loop: Perception → Thinking → Action → Feedback. It makes decisions through LLM, calls tools to execute tasks, and feeds execution results back to the LLM, forming a closed-loop intelligent decision system.

Persistent Memory

The built-in Session Note Tool ensures that the Agent can retain key information across multiple sessions, achieving cross-session memory persistence and giving the Agent the ability to “remember”.

Intelligent Context Management

Uses an automatic summarization mechanism to handle long conversation scenarios. When the context approaches the Token limit, the system automatically calls the LLM to compress and summarize historical conversations, supporting unlimited task execution.

Rich Tool Ecosystem

Basic Tool Set: File read/write, Shell command execution, and other basic capabilities
Claude Skills Integration: Built-in 15 professional skills covering document processing, design, testing, and development
MCP Tool Support: Native support for Model Context Protocol (MCP), easily integrating external tools like knowledge graphs and web search

Multiple API Compatibility

Compatible with Anthropic and OpenAI API interfaces, supporting LLM API integration from different model providers.

Mini-Agent Architecture

A complete system consists of three core components:

LLM (Brain) - Responsible for Understanding and Decision-Making

# mini_agent/llm/base.py
class LLMClientBase(ABC):
    async def generate(
        self,
        messages: list[Message],
        tools: list[Any] | None = None,
    ) -> LLMResponse:
        """Generate LLM response, including content, thinking process, and tool calls"""
        pass

LLMClientBase is the base class for LLM, defining the LLM interface. In the Mini-Agent project, based on LLMClientBase, both Anthropic and OpenAI LLM integration methods are provided.

Tools - Capabilities for Executing Specific Tasks

# mini_agent/tools/base.py
class Tool:
    @property
    def name(self) -> str: ...        # Tool name
    
    @property
    def description(self) -> str: ... # Tool description (for LLM)
    
    @property
    def parameters(self) -> dict: ... # Parameter definition (JSON Schema)
    
    async def execute(self, **kwargs) -> ToolResult:
        """Execute tool and return result"""
        pass

Tools are the “hands and feet” of the Agent. The Mini-Agent project provides several basic tools:

BashTool: Execute Shell commands
FileReadTool / FileWriteTool: File read/write
SessionNoteTool: Session notes (persistent memory)

Memory - Conversation History and Context Management

# mini_agent/schema/schema.py
class Message(BaseModel):
    role: str  # "system", "user", "assistant", "tool"
    content: str | list[dict]
    thinking: str | None = None      # Extended thinking content
    tool_calls: list[ToolCall] | None = None

Memory manages conversation history. Mini-Agent uses an intelligent summarization mechanism to handle long conversation scenarios:

# Call LLM to generate summary
summary_prompt = f"""Please summarize the following Agent execution process concisely:
{summary_content}
Requirements: Focus on what tasks were completed, which tools were called, and retain key results"""

response = await self.llm.generate(messages=[
    Message(role="system", content="You are an assistant skilled at summarizing Agent execution processes"),
    Message(role="user", content=summary_prompt)
])

Mini-Agent Loop Mechanism

Core Loop: Perception → Thinking → Action → Feedback The core execution logic of Mini-Agent is in the run() method of agent.py:

async def run(self) -> str:
    step = 0
    while step < self.max_steps:
        # 1. Check and summarize message history (prevent context overflow)
        await self._summarize_messages()
        
        # 2. Call LLM to get response (thinking)
        response = await self.llm.generate(
            messages=self.messages,
            tools=tool_list
        )
        
        # 3. If no tool calls, task is complete
        if not response.tool_calls:
            return response.content
        
        # 4. Execute tool calls (action)
        for tool_call in response.tool_calls:
            tool = self.tools[tool_call.function.name]
            result = await tool.execute(**arguments)
            # Add result to message history (feedback)
            self.messages.append(tool_msg)
        
        step += 1

Loop Decision Process:

Receive Input

LLM receives message history and available tool list

Decision Making

LLM determines whether to call tools and outputs structured tool_calls

Execute Tools

Agent parses tool_calls and executes corresponding tools

Feedback Results

Tool execution results are added to history as tool role messages

Loop Iteration

Loop continues until LLM considers the task complete (no more tool calls)

Integrating MiniMax-M2.1

Step 1: Download Project

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

# 2. Install uv (if not already installed)
# 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

Step 2: Configuration File

Copy config-example.yaml and rename it to config.yaml

Step 3: Key Configuration

Required Configuration:

api_key: Enter your MiniMax API Key

# ===== Key Settings =====
api_key: "YOUR_API_KEY_HERE"  # [Required] Enter MiniMax API Key
api_base: "https://api.minimax.io"  # International users use this address
# api_base: "https://api.minimaxi.com"  # Users in China use this address
model: "MiniMax-M2.1"
provider: "anthropic"  # LLM provider: "anthropic" or "openai"

Step 4: Other Configuration (Optional)

# ===== Retry Configuration =====
retry:
  enabled: true           # Enable retry mechanism
  max_retries: 3          # Maximum retry attempts
  initial_delay: 1.0      # Initial delay time (seconds)
  max_delay: 60.0         # Maximum delay time (seconds)
  exponential_base: 2.0   # Exponential backoff base

# ===== Agent Configuration =====
max_steps: 100  # Maximum execution steps
workspace_dir: "./workspace"  # Working directory
system_prompt_path: "system_prompt.md"  # System prompt file

# ===== Tool Configuration =====
tools:
  # Basic tool switches
  enable_file_tools: true  # File read/write/edit tools
  enable_bash: true        # Bash command execution tool
  enable_note: true        # Session note tool

  # Claude Skills
  enable_skills: true      # Enable skills
  skills_dir: "./skills"   # Skills directory path

  # MCP Tools
  enable_mcp: true         # Enable MCP tools
  mcp_config_path: "mcp.json"  # MCP configuration file

Step 5: Start Using

# Run directly as module (suitable for debugging)
uv run python -m mini_agent.cli

After running, you will see the Mini-Agent interactive interface: Mini-Agent startup interface

Let’s have it complete a task of making a product introduction of “Notion”: Mini-Agent interactive interface

Mini-Agent successfully completes the task: Mini-Agent execution result

Summary

The essence of an Agent is a decision loop, including four types of behaviors: Perception, Thinking, Execution, and Feedback
Memory is the Agent’s memory capability, essentially context management, including compression, storage, and retrieval of context
Tools are the basic interface for Agents to interact with external systems and extend capabilities; MCP, Claude Skills, and other capabilities proposed by the industry can be seen as further abstractions of Tools

MiniMax M2.1

Detailed Introduction

Mini-Agent GitHub

Framework Source Code & Documentation

MiniMax Platform

Get API Key

Cookbook

Mini-Agent: Build Your First Intelligent Assistant

Introduction to Mini-Agent Framework

Core Features

Key Capabilities

Mini-Agent Architecture

LLM (Brain) - Responsible for Understanding and Decision-Making

Tools - Capabilities for Executing Specific Tasks

Memory - Conversation History and Context Management

Mini-Agent Loop Mechanism

Integrating MiniMax-M2.1

Step 1: Download Project

Step 2: Configuration File

Step 3: Key Configuration

Step 4: Other Configuration (Optional)

Step 5: Start Using

Summary

MiniMax M2.1

Mini-Agent GitHub

MiniMax Platform

Cookbook

​Introduction to Mini-Agent Framework

​Core Features

​Key Capabilities

​Mini-Agent Architecture

​LLM (Brain) - Responsible for Understanding and Decision-Making

​Tools - Capabilities for Executing Specific Tasks

​Memory - Conversation History and Context Management

​Mini-Agent Loop Mechanism

​Integrating MiniMax-M2.1

​Step 1: Download Project

​Step 2: Configuration File

​Step 3: Key Configuration

​Step 4: Other Configuration (Optional)

​Step 5: Start Using

​Summary

​Related Resources

MiniMax M2.1

Mini-Agent GitHub

MiniMax Platform

Introduction to Mini-Agent Framework

Core Features

Key Capabilities

Mini-Agent Architecture

LLM (Brain) - Responsible for Understanding and Decision-Making

Tools - Capabilities for Executing Specific Tasks

Memory - Conversation History and Context Management

Mini-Agent Loop Mechanism

Integrating MiniMax-M2.1

Step 1: Download Project

Step 2: Configuration File

Step 3: Key Configuration

Step 4: Other Configuration (Optional)

Step 5: Start Using

Summary

Related Resources