Mini Agent

英语 | 中文

Mini Agent 是一个极简但专业的演示项目，展示了使用 MiniMax M2.5 模型构建智能体的最佳实践。它基于与 Anthropic 兼容的 API，完全支持交错式思维，从而为长而复杂的任务释放 M2 的强大推理能力。

该项目包含丰富的功能，旨在提供健壮且智能的智能体开发体验：

• ✅ 完整的智能体执行循环：具备基础文件系统和 Shell 操作工具集的完整可靠框架。
• ✅ 持久化记忆：通过活跃的 会话笔记工具，确保智能体在多次会话中保留关键信息。
• ✅ 智能上下文管理：自动总结对话历史，以处理最多可配置的 token 数量的上下文，从而实现无限长度的任务。
• ✅ Claude 技能集成：内置 15 种专业技能，适用于文档、设计、测试和开发等领域。
• ✅ MCP 工具集成：原生支持 MCP，可用于知识图谱访问和网页搜索等工具。
• ✅ 全面的日志记录：对每次请求、响应和工具执行进行详细记录，便于调试。
• ✅ 简洁明了的设计：美观的命令行界面和易于理解的代码库，使其成为构建高级智能体的理想起点。

目录

• Mini Agent
  • 目录
  • 快速入门
    • 1. 获取 API 密钥
    • 2. 选择使用模式
      • 🚀 快速入门模式（推荐初学者）
      • 🔧 开发模式
  • ACP & Zed 编辑器集成（可选）
  • 使用示例
    • 任务执行
    • 使用 Claude 技能（例如 PDF 生成）
    • 网页搜索与摘要（MCP 工具）
  • 测试
    • 快速运行
    • 测试覆盖率
  • 故障排除
    • SSL 证书错误
    • 模块未找到错误
  • 相关文档
  • 社区
  • 贡献
  • 许可证
  • 参考文献

快速入门

1. 获取 API 密钥

MiniMax 提供全球版和中国版平台，请根据您的网络环境选择：

版本	平台	API 基础地址
全球	https://platform.minimax.io	https://api.minimax.io
中国	https://platform.minimaxi.com	https://api.minimaxi.com

获取 API 密钥的步骤：

1. 访问相应平台进行注册并登录
2. 进入 账户管理 > API 密钥
3. 点击 “创建新密钥”
4. 复制并妥善保存（密钥仅显示一次）

💡 提示：请记住您所选平台对应的 API 基础地址，配置时需要用到。

2. 选择使用模式

先决条件：安装 uv

两种使用模式均需使用 uv。如果您尚未安装：

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

# Windows (PowerShell)
python -m pip install --user pipx
python -m pipx ensurepath
# 安装后重启 PowerShell

# 安装完成后，重启终端或运行：
source ~/.bashrc  # 或 ~/.zshrc (macOS/Linux)

我们提供两种使用模式，您可以根据需求选择：

🚀 快速入门模式（推荐初学者）

非常适合希望快速试用 Mini Agent 而无需克隆仓库或修改代码的用户。

安装：

# 1. 直接从 GitHub 安装
uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git

# 2. 运行设置脚本（自动创建配置文件）
# 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"

💡 提示：如果您想在本地开发或修改代码，请使用下方的“开发模式”。

配置：

设置脚本会在 ~/.mini-agent/config/ 中创建配置文件。编辑配置文件：

# 编辑配置文件
nano ~/.mini-agent/config/config.yaml

填写您的 API 密钥和对应的 API 基础地址：

api_key: "YOUR_API_KEY_HERE"          # 第一步获取的 API 密钥
api_base: "https://api.minimax.io"  # 全球
# api_base: "https://api.minimaxi.com"  # 中国
model: "MiniMax-M2.5"

开始使用：

mini-agent                                    # 使用当前目录作为工作空间
mini-agent --workspace /path/to/your/project  # 指定工作空间目录
mini-agent --version                          # 查看版本

# 管理命令
uv tool upgrade mini-agent                    # 升级到最新版本
uv tool uninstall mini-agent                  # 如有需要可卸载
uv tool list                                  # 查看所有已安装工具

🔧 开发模式

适用于需要修改代码、添加功能或进行调试的开发者。

安装与配置：

# 1. 克隆仓库
git clone https://github.com/MiniMax-AI/Mini-Agent.git
cd Mini-Agent

# 2. 安装 uv（如果尚未安装）
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
# 安装后重启终端

# 3. 同步依赖项
uv sync

# 替代方案：手动安装依赖项（如果不使用 uv）
# pip install -r requirements.txt
# 或者单独安装所需包：
# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp

# 4. 初始化 Claude 技能（可选）
git submodule update --init --recursive

# 5. 复制配置模板

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. 编辑配置文件
vim mini_agent/config/config.yaml  # 或使用您喜欢的编辑器

填写您的 API 密钥和对应的 API 基础地址：

api_key: "YOUR_API_KEY_HERE"          # 第一步获取的 API 密钥
api_base: "https://api.minimax.io"  # 全球

# api_base: "https://api.minimaxi.com"  # 中国
model: "MiniMax-M2.5"
max_steps: 100
workspace_dir: "./workspace"

📖 完整配置指南：请参阅 config-example.yaml

运行方式：

请选择您偏好的运行方式：

# 方法一：直接以模块形式运行（适合调试）
uv run python -m mini_agent.cli

# 方法二：以可编辑模式安装（推荐）
uv tool install -e .
# 安装完成后，可在任何位置运行，代码更改会立即生效
mini-agent
mini-agent --workspace /path/to/your/project

📖 更多开发指导，请参阅 开发指南

📖 更多生产部署指导，请参阅 生产指南

ACP 与 Zed 编辑器集成（可选）

Mini Agent 支持 Agent Communication Protocol (ACP)，以便与 Zed 等代码编辑器集成。

在 Zed 编辑器中设置：

1. 以开发模式或工具形式安装 Mini Agent
2. 在 Zed 的 settings.json 中添加以下内容：

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

命令路径应为：

• 如果通过 uv tool install 安装：使用 which mini-agent-acp 的输出
• 如果处于开发模式：./mini_agent/acp/server.py

使用方法：

• 使用 Ctrl+Shift+P 打开 Zed 的代理面板 → “Agent: Toggle Panel”
• 从代理下拉菜单中选择“mini-agent”
• 直接在编辑器中与 Mini Agent 展开对话

使用示例

以下是 Mini Agent 可以完成的一些示例。

任务执行

在此演示中，要求代理创建一个简单美观的网页并在浏览器中显示，展示了基本的工具使用循环。

使用 Claude 技能（例如生成 PDF）

在这里，代理利用 Claude 技能根据用户请求创建一份专业文档（如 PDF 或 DOCX），展示了其高级功能。

网络搜索与摘要（MCP 工具）

此演示展示了代理如何使用网络搜索工具获取最新在线信息，并将其摘要呈现给用户。

测试

该项目包含全面的测试用例，涵盖单元测试、功能测试和集成测试。

快速运行

# 运行所有测试
pytest tests/ -v

# 运行核心功能测试
pytest tests/test_agent.py tests/test_note_tool.py -v

测试覆盖率

• ✅ 单元测试 - 工具类、LLM 客户端
• ✅ 功能测试 - 会话笔记工具、MCP 加载
• ✅ 集成测试 - 代理端到端执行
• ✅ 外部服务 - Git MCP 服务器加载

故障排除

SSL 证书错误

如果您遇到 [SSL: CERTIFICATE_VERIFY_FAILED] 错误：

测试时的快速修复（修改 mini_agent/llm.py）：

# 第 50 行：在 AsyncClient 中添加 verify=False
async with httpx.AsyncClient(timeout=120.0, verify=False) as client:

生产环境解决方案：

# 更新证书
pip install --upgrade certifi

# 或者配置系统代理/证书

模块未找到错误

请确保您在项目目录下运行：

cd Mini-Agent
python -m mini_agent.cli

相关文档

• 开发指南 - 详细的开发和配置指导
• 生产指南 - 生产部署的最佳实践

社区

加入 MiniMax 官方社区，获取帮助、分享想法并及时了解最新动态：

• 微信群：扫描 联系我们 页面上的二维码加入

贡献

欢迎提交问题和拉取请求！

• 贡献指南 - 如何参与贡献
• 行为准则 - 社区规范

许可证

本项目采用 MIT 许可证。

参考资料

• 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 技能：https://github.com/anthropics/skills
• MCP 服务器：https://github.com/modelcontextprotocol/servers

---

⭐ 如果这个项目对您有帮助，请为它点亮星标！

Mini-Agent 快速上手指南

Mini-Agent 是一个基于 MiniMax M2.5 模型的专业智能体（Agent）演示项目。它支持交错思维链（Interleaved Thinking），具备强大的长任务推理能力，并集成了文件操作、持久化记忆、上下文自动总结、Claude Skills 以及 MCP 工具等核心功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS, Linux, 或 Windows (WSL/PowerShell)
• Python 版本：推荐 Python 3.10+
• 前置依赖：本项目推荐使用 uv 进行包管理和环境构建。

安装 uv：

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

# Windows (PowerShell)
python -m pip install --user pipx
python -m pipx ensurepath
# 安装完成后请重启 PowerShell 终端

安装步骤

您可以根据需求选择快速启动模式（适合直接体验）或开发模式（适合二次开发）。

模式一：快速启动模式（推荐新手）

无需克隆代码库，直接通过 uv 安装并使用。

1. 安装工具

   uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git
   

2. 初始化配置 运行官方脚本自动生成配置文件目录。

   # 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"
   

3. 配置 API Key 编辑生成的配置文件 ~/.mini-agent/config/config.yaml：

   nano ~/.mini-agent/config/config.yaml
   

   填入您的 MiniMax API Key 和对应的接口地址（国内用户请使用中国平台）：

   api_key: "YOUR_API_KEY_HERE"          
   # 国内平台地址
   api_base: "https://api.minimaxi.com"  
   # 全球平台地址 (如需使用请取消下方注释)
   # api_base: "https://api.minimax.io"  
   model: "MiniMax-M2.5"
   

   获取 Key 指引：访问 MiniMax 中国平台 或 全球平台，在“账户管理 > API Keys”中创建新密钥。

模式二：开发模式

适合需要修改源码、添加功能或调试的开发者。

1. 克隆仓库

   git clone https://github.com/MiniMax-AI/Mini-Agent.git
   cd Mini-Agent
   

2. 同步依赖

   uv sync
   

3. 初始化子模块（可选） 如需使用 Claude Skills 功能，请执行：

   git submodule update --init --recursive
   

4. 配置项目 复制配置模板并编辑：

   # 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
   

   同样在 mini_agent/config/config.yaml 中填入 api_key 和 api_base。

5. 本地安装（可选） 为了方便在任何目录运行且实时生效：

   uv tool install -e .
   

基本使用

配置完成后，即可通过命令行启动 Mini-Agent。

1. 启动智能体

在当前目录启动（将当前文件夹作为工作空间）：

mini-agent

指定特定项目目录作为工作空间：

mini-agent --workspace /path/to/your/project

2. 交互示例

启动后，您将进入 CLI 交互界面。您可以直接输入自然语言指令，例如：

• 执行任务：

  "创建一个简单的 HTML 网页，包含标题和我的简介，并在浏览器中打开它。" (Agent 将自动调用文件系统工具创建文件并执行 shell 命令)

• 使用技能（如生成 PDF）：

  "使用文档技能将当前的 README 文件转换为 PDF 格式。"

• 联网搜索（需配置 MCP）：

  "搜索今天关于 AI 领域的最新新闻，并总结成三点。"

3. 常用管理命令

# 查看版本
mini-agent --version

# 升级到最新版本 (仅限快速启动模式)
uv tool upgrade mini-agent

# 卸载
uv tool uninstall mini-agent