[AI] Agents / Mini-Agent -- 概念 === ###### tags: `AI / Tools / Agents /` ###### tags: `AI`, `tools`, `agents`, `Mini-Agent` <br> [TOC] <br> ## 官網 > https://github.com/MiniMax-AI/Mini-Agent > Mini-Agent 的價值在於：**用很小的程式碼展示一個現代 Agent 應該有的骨架：LLM wrapper、tool calling、workspace、memory、context summary、MCP、Skills、CLI、logging**。 <br> --- ## 討論 ### 整理 Mini-Agent 功能 - #### gpt-5.4 (2026/04/09) ### Mini-Agent 是什麼？ **Mini-Agent** 是 MiniMax-AI 做的「單一 Agent 示範框架」，主要用來展示如何用 **MiniMax M2.5** 建立一個具備工具呼叫、上下文管理、記憶、MCP、Skills、CLI 的 agent。它比較像是「可學習、可改造的 agent starter kit」，不是完整商用平台。官方 README 明確說它是 minimal yet professional demo project，並透過 Anthropic-compatible API 支援 MiniMax M2.5 的 interleaved thinking。([GitHub][20260429-A-1]) --- ### 核心功能整理 | 類別 | 功能 | 說明 | | --- | ---- | ---- | | Agent 執行循環 | Full Agent Execution Loop | 有完整的「LLM 思考 → 工具呼叫 → 工具結果 → 下一輪」流程，並搭配檔案系統與 shell 操作工具。([GitHub][20260429-A-1]) | | 檔案操作 | Read / Write / Edit | 可在 workspace 內讀取、寫入、編輯檔案，適合做簡單程式碼修改或文件生成。官方設定檔也提供 `enable_file_tools` 開關。 | | Shell 操作 | Bash Tool | 可執行 bash 指令，並有 bash output / kill 輔助工具；CLI 初始化時會依設定載入 BashTool。 | | 持久記憶 | Session Note Tool | 透過 SessionNoteTool 把關鍵資訊保留下來，預設會在 workspace 中使用 `.agent_memory.json` 儲存。 | | 上下文管理 | 自動摘要歷史訊息 | 當 token 超過設定上限時，會把執行過程摘要化，保留 user message 與 agent 執行摘要，避免上下文爆掉。 | | Skills | Claude Skills 整合 | README 說內建 15 種專業 Skills，涵蓋文件、設計、測試、開發等。([GitHub][20260429-A-1]) | | MCP | MCP 工具整合 | 原生支援 MCP，可接知識圖譜、網頁搜尋等工具；設定檔有 `enable_mcp`、`mcp_config_path` 與 timeout 設定。 | | Web Search | 搜尋與摘要 | README 展示可透過 MCP tool 做 web search 與 summarization。([GitHub][20260429-A-1]) | | CLI | 互動式命令列 | 支援 `mini-agent`、`mini-agent --workspace`、`--task`，也有 `/help`、`/clear`、`/history`、`/stats`、`/log` 等互動命令。 | | ACP / Editor | Zed Editor 整合 | 支援 Agent Communication Protocol，可以接到 Zed Editor 的 agent panel。([GitHub][20260429-A-1]) | | Logging | 詳細紀錄 | README 說會記錄 request、response、tool execution，方便除錯。([GitHub][20260429-A-1]) | | Testing | 測試覆蓋 | 官方列出 unit tests、functional tests、integration tests、external services 測試。([GitHub][20260429-A-1]) | --- ### 技術特點 #### 1. 支援 Anthropic / OpenAI 兩種 API 風格 Mini-Agent 的 LLM wrapper 支援 `anthropic` 與 `openai` provider。對 MiniMax API 會自動根據 provider 加上 endpoint suffix：`/anthropic` 或 `/v1`；第三方 API 則使用原本的 `api_base`。 這代表它不是只能綁死 MiniMax API，架構上有做「多 provider wrapper」的抽象。 --- #### 2. 工具系統設計簡單，容易擴充 Tool 基底類別要求每個工具實作： | 屬性/方法 | 用途 | | -------------------- | ------------------------- | | `name` | 工具名稱 | | `description` | 給 LLM 理解工具用途 | | `parameters` | JSON Schema 參數定義 | | `execute()` | 實際執行邏輯 | | `to_schema()` | 轉成 Anthropic tool schema | | `to_openai_schema()` | 轉成 OpenAI function schema | 這點很適合拿來學「LLM tool calling 框架怎麼設計」。([GitHub][20260429-A-2]) --- #### 3. 有 workspace 邊界概念 Agent 初始化時會建立 workspace，並把 workspace 路徑注入 system prompt，讓相對路徑都以該 workspace 解析。這比直接讓 agent 在任意目錄操作安全一點，但仍不等於完整 sandbox。 --- #### 4. 可設定項目算完整 `config-example.yaml` 支援： ```yaml api_key api_base model provider: anthropic / openai retry: enabled max_retries initial_delay max_delay exponential_base max_steps workspace_dir system_prompt_path tools: enable_file_tools enable_bash enable_note enable_skills enable_mcp mcp_config_path ``` 也支援 MCP timeout：connect、execute、SSE read timeout。 --- ### 使用方式 #### 快速體驗 ```bash uv tool install git+https://github.com/MiniMax-AI/Mini-Agent.git ``` 接著執行設定腳本，填入 MiniMax API key、API base、model 後即可跑： ```bash mini-agent mini-agent --workspace /path/to/your/project mini-agent --version ``` README 有列出 quick start mode 與 development mode，前者適合直接試用，後者適合 clone repo 後修改程式碼。([GitHub][20260429-A-1]) --- ### 適合的使用情境 | 情境 | 適合度 | 原因 | | ------------------------- | --: | ---------------------------------------------- | | 學習 Agent execution loop | 高 | 程式碼結構單純，核心流程集中在 `agent.py`。 | | 做 MiniMax M2.5 agent demo | 高 | 官方就是以 MiniMax M2.5 為主要模型。 | | 建立自家 agent prototype | 高 | 已有工具系統、CLI、記憶、MCP、Skills、logging。 | | 研究 tool calling 架構 | 高 | Tool 抽象層簡單清楚。 | | 小型內部自動化工具 | 中 | 可用，但要補安全、權限、部署、觀測。 | | 直接上 production | 低 | 官方 production guide 明確說這是教學級 demo，正式環境還要補很多問題。 | --- ### 主要限制與注意事項 1. **官方自己定位為 demo，不是 production-ready 平台。** Production Guide 明確寫到此專案是「教學級 Demo」，正式環境要補進階上下文管理、模型回退、高可用、幻覺檢測、安全檢查、容器隔離、資源限制等。 2. **Shell / File tools 有安全風險。** 它能執行 bash、讀寫檔案，所以若要給多人或接企業環境，必須加 sandbox、權限控管、審計、allowlist/denylist。 3. **記憶機制偏簡單。** 預設 SessionNoteTool 是檔案式記憶；開發指南也提到可改成 PostgreSQL、Milvus 等後端，代表目前不是成熟的企業級 memory layer。 4. **上下文摘要是基礎策略。** 它會摘要歷史執行內容，但沒有完整 RAG、向量召回、任務狀態機、checkpoint rollback 等複雜機制。 5. **目前 GitHub 沒有正式 release。** Repo 頁面顯示 no releases published。([GitHub][20260429-A-1]) --- ### 一句話評價 **Mini-Agent 的價值在於：用很小的程式碼展示一個現代 Agent 應該有的骨架：LLM wrapper、tool calling、workspace、memory、context summary、MCP、Skills、CLI、logging。** 但它比較適合當作： > 「Agent 框架學習範例 / MiniMax M2.5 agent starter kit / prototype 基底」 不適合直接當作： > 「企業級 agent 平台 / 多使用者 SaaS agent runtime / 高安全 production executor」 [20260429-A-1]: https://github.com/MiniMax-AI/Mini-Agent "GitHub - MiniMax-AI/Mini-Agent: A minimal yet professional single agent demo project that showcases the core execution pipeline and production-grade features of agents. · GitHub" [20260429-A-2]: https://raw.githubusercontent.com/MiniMax-AI/Mini-Agent/main/mini_agent/tools/base.py "raw.githubusercontent.com" <br> {%hackmd vaaMgNRPS4KGJDSFG0ZE0w %}