NamiAgent
零基础入门 AI Agent 的基础教程
不只是教程，也是一个能在本地跑起来的 Agent，自带网页端，每一步都看得见
 |  |
| 写 hello.py 并运行：写文件、跑命令前弹窗确认 | 长期记忆：新会话里它还记得你是谁 |
Agent 没有什么神秘的，核心就是一个 while 循环：调模型、执行工具、把结果写回上下文，再调模型。
它是教程：从 100 行的最小循环开始，一课加一个能力：工具、权限、上下文管理、Skills、MCP、子 Agent、计划、记忆。最后拆解 Claude Code、Codex 等主流 Agent 是怎么做的。内容是我自己一步步学习、动手实践后整理出来的。
它也是一个能用的本地 Agent：在你指定的工作区里读写文件、执行命令、接入 MCP、记住你是谁；写文件、跑命令前都会先问你。python web/app.py 打开网页端，左边看它每一步怎么想、调了什么工具，右边看每次发给模型的完整上下文。
- 每课一个可运行的快照：
lessons/lesson-01到lesson-11，每个目录都是学完这一课时的完整代码，可以直接运行，也可以对比相邻两课的差异 - 不绑定厂商：使用 OpenAI 兼容接口，默认用 DeepSeek，换模型只需要改两个环境变量
- 测试不花钱：第 3 课起每课都有测试，第 11 课共 49 个，用假模型跑，不需要 API Key
- 只依赖
openai一个包：没有任何 Agent 框架 - 本地网页端：在浏览器里看每一步，上下文怎么变长、模型怎么想、调了什么工具，一目了然（见下文）
先学 NamiGPT 搞懂模型本身，再学 NamiAgent 搞懂模型外面那一圈。
课程目录
第一部分：手写核心
| 课 | 文章 | 代码 | 这一课新增 |
|---|---|---|---|
| 01 | 最小循环 | lesson-01 | agent.py：三个工具 + 一个 while 循环 |
| 02 | 工具系统 | lesson-02 | tools.py：注册表、统一执行器 |
| 03 | 权限 | lesson-03 | permissions.py：硬规则 → 风险分级 → 人工确认 |
| 04 | 上下文管理 | lesson-04 | context.py：截断 → 清理 → 摘要，会话持久化 |
| 05 | Skills | lesson-05 | skills.py：AGENTS.md 常驻，技能按需加载 |
| 06 | 接入聊天软件 | lesson-06 | telegram.py、bot.py：常驻、聊天确认、白名单 |
| 07 | 定时任务与心跳 | lesson-07 | scheduler.py：无人值守的预授权、心跳 |
第二部分：补上主流能力
| 课 | 文章 | 代码 | 这一课新增 |
|---|---|---|---|
| 08 | MCP | lesson-08 | mcp_client.py：stdio MCP 客户端 |
| 09 | 子 Agent 与多 Agent | lesson-09 | subagent.py：独立上下文，并行只读 |
| 10 | 计划 | lesson-10 | planning.py：待办清单、由代码强制只读的计划模式 |
| 11 | 记忆 | lesson-11 | memory.py：长期记忆（每条确认）、会话检索 |
第三部分：拆解主流 Agent（只有文章，没有新代码）
| 课 | 文章 |
|---|---|
| 12 | 拆解 Claude Code |
| 13 | 拆解 Codex |
| 14 | 拆解 Pi |
| 15 | 拆解 Grok Bot |
| 16 | 拆解 DeepSeek Harness |
| 17 | 拆解 OpenClaw 与 Hermes |
| 18 | 总对照表 |
第三部分写的是截至 2026 年 10 月的情况。这些产品更新很快，细节请以各自官方文档为准。
配套可视化
Agent 是怎么工作的：10 章逐格播放，看上下文每转一圈怎么变长、在哪里出问题，以及各种 Agent 技巧到底在上下文里做了什么。下面是其中第 3 章，配合第 1 课看效果最好：
快速开始
需要 Python 3.10+。
git clone https://github.com/aa1143/NamiAgent.git
cd NamiAgent
pip install -r requirements.txt
export API_KEY=你的模型密钥
# 默认用 DeepSeek；换其他 OpenAI 兼容模型：
# export BASE_URL=https://... MODEL=模型名
export NAMI_WORKSPACE=~/agent-workspace # 第 3 课起，Agent 只能操作这个目录
mkdir -p $NAMI_WORKSPACE
cd lessons/lesson-05
python agent.py跑测试（不需要 API Key）：
cd lessons/lesson-11 && pytest -q网页端：在浏览器里看 Agent 的每一步
页首的两张动图就是网页端的真实运行录屏。
python web/app.py --demo # 演示模式：脚本化的假模型，不需要 API Key，先看看效果
python web/app.py # 用真实模型，和命令行版一样读 API_KEY / BASE_URL / MODELmacOS 也可以直接双击 web/start.command：自动建虚拟环境、装依赖、让你粘贴 API Key（直接回车就是演示模式），然后打开浏览器。Agent 的工作区默认是 ~/agent-workspace。
然后打开 http://localhost:8765 ：
- 左边：每一次调用模型、模型的思考过程、调用了什么工具、工具返回了什么
- 右边：这一次发给模型的完整上下文。每一块是谁写的、大概占多少 token，转一圈就长一截
- 权限确认：写文件、跑命令这类有副作用的操作会弹窗，要你点头才执行（第 3 课的规则）
- 开头写
/plan让它先出计划，批准后再动手（第 10 课）
网页端直接导入 lessons/lesson-11 的 Agent，没有改课程代码，只换了三个接口：模型客户端（把每次发出去的上下文推给浏览器）、handle_call（把工具调用推给浏览器）、权限确认的 ask（终端 input() 换成弹窗）。只用 Python 标准库，不需要装 Web 框架。
DeepSeek 默认开启思考模式，模型返回的思考过程（reasoning_content）会单独显示。带工具调用时，这段思考要原样放回上下文再发给 API，右边的上下文面板里也能看到它。界面里展示的思考只是模型写出来的文字，不等于模型内部真实的计算过程。
环境变量
| 变量 | 作用 | 默认值 |
|---|---|---|
API_KEY | 模型密钥 | 必填 |
BASE_URL | OpenAI 兼容接口地址 | https://api.deepseek.com |
MODEL | 模型名 | deepseek-flash |
NAMI_WORKSPACE | Agent 的工作区（第 3 课起） | 启动时所在的目录 |
NAMI_STATE_DIR | 会话记录、定时任务等状态（第 4 课起），放在工作区之外 | ~/.nami-agent |
第 6 课起的 bot.py 还需要 TG_BOT_TOKEN 和 TG_ALLOWED_USERS，见第 6 课。第 8 课起可以接入 MCP 服务器，配置放在 ~/.nami-agent/mcp.json，格式见第 8 课。
安全提醒
这是教学代码，Agent 会真的执行命令、读写文件。第 3 课的权限机制能挡住误操作和低成本的越界，挡不住有意的攻击（第 3 课第八节专门讲了它防不住什么）。
请在专门的工作区目录里运行，不要把工作区指向你的主目录。
这个仓库不是什么
NamiAgent 是一个看得懂的最小 Agent，不是生产级框架，也不打算和 Claude Code、Codex 比功能。目标是让你读完之后，再看任何 Agent 产品，都知道它在上下文里做了什么。
相关
- NamiGPT：从零手写 GPT-2
- 图解大模型：推理、训练、Agent 三部分逐格可视化
- 从零手写 Agent 图文版
License
代码采用 MIT，docs/ 下的文章采用 CC BY-NC 4.0。