Skip to content

Agent Harness 从零手写:运行循环、工具调用到 MCP 与记忆 ​

Agent 这个词被用得很泛。会调工具的、会规划的、能记住你的,都叫 Agent。但如果你问一句"它内部到底怎么转起来的",框架会把这个答案藏起来 —— 因为框架帮你把运行循环、工具分发、上下文管理都封好了。

所以我换个思路:不用框架,自己把每块零件写一遍。这个项目一共 29 个阶段,每个阶段一个可运行脚本加一份文档,git log 就是学习时间线。这个系列不逐个复述阶段,只讲其中真正有价值的部分:这篇是概览,讲为什么手写、项目全貌和怎么学;三篇专题各讲一块核心机制,按需读。

一、为什么要手写一遍,而不是直接用框架 ​

1.1 框架把心脏藏起来了 ​

用 LangChain 之类的框架,五行代码就能跑起一个 Agent。但一旦出问题,你会发现自己不知道从哪查起:工具为什么没被调用?上下文为什么丢了?模型为什么在同一个工具上反复打转?

手写一遍之后,这些问题的答案变得具体 —— 因为循环是你自己写的,你能一眼看出它停在哪一步。

1.2 项目的三条设计约定 ​

  • 每阶段一个可运行脚本:25 个脚本,每个 40~225 行,都能单独 python xxx.py 跑起来
  • 每阶段一份文档:stage/00 到 stage/29,写清这一阶段学什么、验收标准是什么
  • 不追求一次性做对:很多阶段是"发现上一阶段的缺陷,再修它",比如 Stage 26 就是嫌 Stage 21 的执行者不会调工具,才把 Executor 换成 ReAct

第三条是这套设计最有意思的地方:它保留了一个真实开发者的演进路径,而不是把最终答案直接摆出来。

1.3 能力演进路线图 ​

二、系列导读:三篇专题各讲什么 ​

篇目讲什么什么时候读
(一)运行循环与工具系统不到 20 行的运行循环、三个必踩的坑、工具的声明 — 分发 — 解析、报错变上下文先读这篇,后两篇都建立在它上面
(二)MCP 运行时发现与两层循环MCP 的 server / client / stdio、input_schema 一行桥接、Plan-and-Execute + ReAct想接现成工具,或者任务一复杂 Agent 就乱
(三)记忆、技能、沙箱与评测长期记忆、技能带工具、四层纵深防御、评测三件套准备让 Agent 长期跑、或者给别人用之前

三、做成产品:Harness 成了自己文档的入口 ​

29 个阶段的能力最终收在一个 FastAPI 服务里,配一个单页前端。这个界面本身就是"知识库问答 Agent"的落地形态 —— 检索的语料正是项目自己的 stage/ 文档,所以它回答的就是"这个项目里的概念":

知识库问答助手界面

界面副标题写着"RAG 语义检索 · 基于你的 stage 文档",示例问题正是「什么是运行循环?」「RAG 的三步是什么?」「怎么处理工具出错?」—— 文档写完之后,Harness 自己成了这套文档的入口。这是我做完整个项目后觉得最有意思的一个副产品。

四、29 个阶段怎么走:六条学习线 ​

不建议从 1 顺着做到 29,而是按学习线走,每条线都能单独成篇:

学习线路径
入门主线hello.py → chat.py → loop.py → agent.py
RAG 线rag.py → vector_rag.py → semantic_rag.py → kb_agent.py
MCP 线mcp_server.py / mcp_client.py → mcp_agent.py → planner_mcp.py
Agent 模式线reflect.py(反思)→ planner.py(规划)→ planner_react.py(ReAct 执行)
记忆线memory.py → memory_tool.py
技能线skill.py → skill_tool.py

每个脚本顶部的 docstring 都写明了这一阶段学什么,配合 stage/ 下的同名文档就是一份完整的预习与复习材料。

五、小结 ​

手写一遍之后,我对 Agent 的理解变成了这几句:

  1. 心脏就是一个循环 —— 发请求、执行工具、回传结果、再发请求,没有更多魔法
  2. 工具的安全边界在自己这边 —— 模型只负责"点菜",护栏必须由服务端独立设置
  3. 标准化带来解耦 —— MCP 那一行 input_schema 转 parameters,背后是"工具与 Agent 彻底解耦"的价值
  4. 演进比一步到位更真实 —— 项目里每一次重构(Executor 换成 ReAct、手写工具换成 MCP)都是发现上一阶段的缺陷之后才做的

项目已开源(MIT):https://github.com/zhaoxuejie/moqian-agent-harness

安全提醒:项目里的命令执行、文件读写工具都配了沙箱护栏,但它仍然是学习用途的代码。请始终在自己的机器、可控的目录里运行,不要把未经验证的 Agent 暴露到公网。

相关阅读:RAG 知识库从零搭建:文档解析、向量检索到生成回答

本文阅读--次|全站访问--次|访客--人