examples/README.md

Mini Agent Examples

This directory contains a series of progressive examples to help you understand how to use the Mini Agent framework.

📚 Example List

01_basic_tools.py - Basic Tool Usage

Difficulty: ⭐ Beginner

Content:

• How to directly use ReadTool, WriteTool, EditTool, BashTool
• No Agent or LLM involved, pure tool call demonstrations
• Perfect for understanding each tool's basic functionality

Run:

python examples/01_basic_tools.py

Key Learnings:

• Tool input parameter formats
• ToolResult return structure
• Error handling approaches

---

02_simple_agent.py - Simple Agent Usage

Difficulty: ⭐⭐ Beginner-Intermediate

Content:

• Create the simplest Agent
• Have Agent perform file creation tasks
• Have Agent execute bash command tasks
• Understand Agent execution flow

Run:

# Requires API key configuration first
python examples/02_simple_agent.py

Key Learnings:

• Agent initialization process
• How to give tasks to Agent
• How Agent autonomously selects tools
• Task completion criteria

Prerequisites:

• API key configured in mini_agent/config/config.yaml

---

03_session_notes.py - Session Note Tool

Difficulty: ⭐⭐⭐ Intermediate

Content:

• Direct usage of Session Note tools (record_note, recall_notes)
• Agent using Session Notes to maintain cross-session memory
• Demonstrate how two Agent instances share memory

Run:

python examples/03_session_notes.py

Key Learnings:

• How Session Notes work
• Note categorization management (category)
• How to guide Agent to use notes in system prompt
• Cross-session memory implementation

Highlight: This is one of the core features of this project! Shows a lightweight but effective session memory management solution.

---

04_full_agent.py - Full-Featured Agent

Difficulty: ⭐⭐⭐⭐ Advanced

Content:

• Complete Agent setup with all features
• Integration of basic tools + Session Notes + MCP tools
• Full execution flow for complex tasks
• Multi-turn conversation examples

Run:

python examples/04_full_agent.py

Key Learnings:

• How to combine multiple tools
• MCP tool loading and usage
• Complex task decomposition and execution
• Production environment Agent configuration

Prerequisites:

• API key configured
• (Optional) MCP tools configured

---

🚀 Quick Start

1. Configure API Key

# Copy configuration template
cp mini_agent/config/config-example.yaml mini_agent/config/config.yaml

# Edit config file and fill in your MiniMax API Key
vim mini_agent/config/config.yaml

2. Run Your First Example

# Example that doesn't need API key
python examples/01_basic_tools.py

# Example that needs API key
python examples/02_simple_agent.py

3. Progressive Learning

Recommended to learn in numerical order:

1. 01_basic_tools.py - Understand tools
2. 02_simple_agent.py - Understand Agent
3. 03_session_notes.py - Understand memory management
4. 04_full_agent.py - Understand complete system

---

📖 Relationship with Test Cases

These examples are all refined from test cases in the tests/ directory:

Example	Based on Test	Description
01_basic_tools.py	tests/test_tools.py	Basic tool unit tests
02_simple_agent.py	tests/test_agent.py	Agent basic functionality tests
03_session_notes.py	tests/test_note_tool.py tests/test_integration.py	Session Note tool tests
04_full_agent.py	tests/test_integration.py	Complete integration tests

---

💡 Recommended Learning Paths

Path 1: Quick Start

1. Run 01_basic_tools.py - Learn about tools
2. Run 02_simple_agent.py - Run your first Agent
3. Go directly to interactive mode with mini-agent

Path 2: Deep Understanding

1. Read and run all examples (01 → 04)
2. Read corresponding test cases (tests/)
3. Read core implementation code (mini_agent/)
4. Try modifying examples to implement your own features

Path 3: Production Application

1. Understand all examples
2. Read Production Deployment Guide
3. Configure MCP tools and Skills
4. Extend tool set based on needs

---

🔧 Troubleshooting

API Key Error

❌ API key not configured in config.yaml

Solution: Ensure you've configured a valid MiniMax API Key in mini_agent/config/config.yaml

config.yaml Not Found

❌ config.yaml not found

Solution:

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

MCP Tools Loading Failed

⚠️ MCP tools not loaded: [error message]

Solution: MCP tools are optional and don't affect basic functionality. If you need them, refer to the MCP configuration section in the main README.

---

📚 More Resources

• Main Project README - Complete project documentation
• Test Cases - More usage examples
• Core Implementation - Source code
• Production Guide - Deployment guide

---

🤝 Contributing Examples

If you have good usage examples, PRs are welcome!

Suggested new example directions:

• Web search integration examples (using MiniMax Search MCP)
• Skills usage examples (document processing, design, etc.)
• Custom tool development examples
• Error handling and retry mechanism examples

---

⭐ If these examples help you, please give the project a Star!