Mini-Agent

Agent 的本质，只有 40 行。

当你打开一个生产级 Agent（比如 Claude Code、OpenAI Codex、Hermes）的源码，面对的是 40,000+ 行代码——凭证池、降级链、上下文压缩、MCP 协议、插件系统、流式看门狗……

但你有没有想过：Agent 到底在做什么？

剥开所有工程外壳，Agent 的全部逻辑浓缩成一句话：

调用 LLM → 如果它想用工具就执行 → 把结果喂回去 → 再调用 LLM → 重复，直到它不再调用工具。

这就是 Mini-Agent 存在的意义。

我们从 Hermes Agent 的 40,000 行生产代码中，提炼出构成 Agent 的 7 个最小必要组件，用 510 行 实现了一个完整可运行的 Agent——能对话、能执行命令、能读写文件、能搜索代码，支持流式输出，兼容任何 OpenAI 接口。

如果你正在学习 Agent 开发，这里就是最好的起点。

---

Agent 的 7 个核心组件

#	组件	作用
1	LLM 客户端	调用语言模型
2	系统提示词	定义 Agent 行为
3	工具 Schema	描述可用工具给 LLM
4	工具处理函数	实际执行操作
5	工具分发表	路由工具名称到处理函数
6	对话循环	LLM 调用 → 工具执行 → 循环
7	消息历史	维护对话上下文

内置工具

工具	功能
run_command	执行 Shell 命令，返回 stdout/stderr/exit code
read_file	读取文件内容（带行号、分页）
write_file	写入文件（自动创建目录）
search_files	按正则搜索文件内容或按 glob 搜索文件名

快速开始

1. 安装依赖

pip install openai

2. 配置

cp .env.example .env

编辑 .env，填入你的 API Key：

OPENAI_API_KEY=sk-your-api-key-here

3. 运行

python mini_agent.py

使用不同模型

Mini-Agent 兼容任何 OpenAI-compatible API。只需在 .env 中修改配置：

DeepSeek：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.deepseek.com
MINI_AGENT_MODEL=deepseek-chat

通义千问：

OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MINI_AGENT_MODEL=qwen-plus

本地 Ollama：

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
MINI_AGENT_MODEL=llama3

OpenAI 官方：

OPENAI_API_KEY=sk-xxx

也可以通过命令行参数覆盖 .env 配置：

python mini_agent.py --model gpt-4o --base-url https://api.openai.com/v1

运行效果

Mini-Agent (model: deepseek-chat)
Working dir: /home/user/project
--------------------------------------------------

> 帮我看看当前目录下有什么文件

  [tool: run_command]
├── src/
│   ├── main.py
│   └── utils.py
├── tests/
│   └── test_main.py
├── README.md
└── pyproject.toml

当前目录下有以下内容：
- `src/` 目录包含主要源码（main.py 和 utils.py）
- `tests/` 目录包含测试文件
- 根目录还有 README.md 和 pyproject.toml

> 把 main.py 里用了哪些模块列出来

  [tool: read_file]
  [tool: search_files]
main.py 中导入了以下模块：
1. `os` — 系统操作
2. `json` — JSON 处理
3. `pathlib.Path` — 路径操作

架构原理

Agent 的核心骨架只有 ~40 行：

def run(self, user_message: str) -> str:
    self.messages.append({"role": "user", "content": user_message})

    for iteration in range(self.max_iterations):
        response = self._stream_api_call(messages, tools)
        assistant_msg = response.choices[0].message

        if not assistant_msg.tool_calls:          # 无工具调用 → 任务完成
            return assistant_msg.content

        for tc in assistant_msg.tool_calls:        # 有工具调用 → 执行工具
            result = self._dispatch_tool(tc)       # 追加结果到消息历史
            self.messages.append(result)
        # 循环回去，让 LLM 继续处理工具结果

这就是 Agent 的全部本质：LLM 调用 → 工具执行 → 循环。其余所有生产级功能（重试降级、凭证池、上下文压缩、插件系统等）都是让这个循环更可靠。

Skill、MCP、记忆、编排是基本功能吗？

不是。 它们是核心循环之上的增强层，而非 Agent 的必要组件。

从 Agent 循环的视角看，这四者有一个共同特点——它们都是工具：

Agent 核心循环（不可变）
    │
    ├── 内置工具: run_command, read_file, write_file, search_files
    │
    └── 增强工具（本质相同，只是更复杂）:
         ├── skill_view     → Skill 系统
         ├── mcp_tool_*     → MCP 协议
         ├── memory_save    → 记忆系统
         └── delegate_task  → 多 Agent 编排

Agent 循环看到的永远是同一套协议：tool_call(name, args) → result。不管背后是执行一条命令、调用一个 MCP 服务器、保存一段记忆、还是 spawn 一个子 Agent，对循环来说没有任何区别。

能力	本质	为什么不是基本功能
Skill（技能）	提示词工程	本质是预置的知识模板注入 system prompt，不是新机制
MCP（协议）	工具注册标准化	内置工具和 MCP 工具对循环来说没有区别，都是 name→handler
记忆（Memory）	特殊的读写工具	memory_save/memory_recall 与 write_file/read_file 等价
编排（Orchestration）	在工具层模拟	delegate_task 就是一个工具，内部 spawn 子 Agent 返回结果

所以 Mini-Agent 的 510 行已经覆盖了 Agent 的完整基本功能。这些增强能力可以不断叠加，每一层都不改变核心循环的结构——只是往工具字典里多加几个 handler 而已。

项目结构

mini-agent/
├── mini_agent.py    # Agent 完整实现（510 行）
├── .env.example     # 环境变量配置模板
└── README.md        # 本文件

命令行参数

参数	环境变量	默认值	说明
--model	MINI_AGENT_MODEL	gpt-4o	模型名称
--base-url	OPENAI_BASE_URL	OpenAI 官方	API 地址
--api-key	OPENAI_API_KEY	—	API Key（必填）
--max-iterations	—	20	最大循环次数

优先级：命令行参数 > 环境变量 > .env 文件。

许可证

MIT