---
# System prepended metadata

title: '[AI] Agents / Mini-Agent -- 概念'
tags: [tools, AI, Mini-Agent, AI / Tools / Agents /, agents]

---

[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 %}