> ## Documentation Index
> Fetch the complete documentation index at: https://platform.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Mini-Agent: Build Your First Intelligent Assistant
> This tutorial will guide you through the core architecture of Mini-Agent and show you how to integrate with the MiniMax M2.1 model to build your own intelligent Agent.
B
Blue
January 15, 2026
Download from GitHub
# 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
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.
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".
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.
* **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
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
```python theme={null}
# 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
```python theme={null}
# 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
```python theme={null}
# 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:
```python theme={null}
# 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`:
```python theme={null}
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:**
LLM receives message history and available tool list
LLM determines whether to call tools and outputs structured `tool_calls`
Agent parses `tool_calls` and executes corresponding tools
Tool execution results are added to history as `tool` role messages
Loop continues until LLM considers the task complete (no more tool calls)
***
## Integrating MiniMax-M2.1
### Step 1: Download Project
```bash theme={null}
# 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
```yaml theme={null}
# ===== 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)
```yaml theme={null}
# ===== 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
```bash theme={null}
# Run directly as module (suitable for debugging)
uv run python -m mini_agent.cli
```
**After running, you will see the Mini-Agent interactive interface:**
**Let's have it complete a task of making a product introduction of "Notion":**
**Mini-Agent successfully completes the task:**
***
## 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
***
## Related Resources
Detailed Introduction
Framework Source Code & Documentation
Get API Key
**Let's have it complete a task of making a product introduction of "Notion":**
**Mini-Agent successfully completes the task:**
***
## 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
***
## Related Resources