学 Agent 先别学框架，这条路反而更快

8 月 28 日傍晚，Hacker News 上有个项目悄悄爬到 111 分。

它没有发新模型，没有把上下文窗口再拉长一截，也没有拿跑分表来压人。项目名甚至朴素得像学校机房里的文件夹，AI Engineer Notebooks，33 个可以直接丢进 Colab 运行的笔记本。

我点进去时，仓库是 426 个 Star、25 个 Fork。这个量级离爆库还早，但 README 里的一个词把我钉住了。

Framework-free，刻意不用框架。

好家伙，别人做 AI 工程课，恨不得把 LangChain、LlamaIndex、LangGraph、MCP、向量数据库全塞进第一章，生怕简历关键词少一行。它反过来，让你先用原始 API 写结构化输出、工具调用、RAG、评估和 Agent 循环，等手里真有了那几十行代码，再问自己要不要框架。

看起来像绕远路。

我觉得，恰好是近路。

不是因为框架不好，而是 AI 系统最容易翻车的地方，通常都藏在框架帮你省掉的那些代码里。上下文怎么拼，工具结果怎么塞回去，循环什么时候停，失败以后重试几次，模型说完成时谁来验收。平时我做的很多工作，就是给模型搭这一层脚手架。harness 这个词不太好翻，用人话讲，就是让模型真正能干活、还能被管住的那圈工程。

这套笔记最值钱的，也正是把那一圈重新摊开给你看。

四十行代码，把 Agent 的魔法打回 while 循环

现在聊 Agent，很容易被产品演示带歪。

屏幕上一个小球转几圈，模型打开网页、读文件、写报告、发消息，像是突然长出了手脚。于是大家开始找框架，选 orchestration，画多 Agent 架构图。图上十几个方块互相连线，厉害了，PPT 已经先实现 AGI。

但在这套笔记的 Agent loop from scratch 里，Agent 被压回了约 40 行 Python。

模型发起工具调用，程序执行普通函数，把结果作为 tool message 塞回 messages，再调用一次模型。模型还要工具，就继续；模型返回最终文本，或者碰到 max_turns，循环结束。

就这。

它只有四个零件，能请求工具的模型、带名字和 JSON Schema 的函数、一个 while 循环、几条停止条件。LangGraph、CrewAI、OpenAI Agents SDK、Claude 的工具运行器，底下都绕不开这副骨架。

亲手写一遍以后，很多生产问题会突然从玄学变成代码问题。

把 Agent 拆开，能看到的只是消息、工具、循环与闸门。

比如模型 API 是无状态的。Agent 所谓的记忆，往往就是你的 messages 列表。第五轮请求会把前四轮历史重新发一遍，工具吐回来的大文件也跟着一遍遍重传。轮数越长，输入 token 越涨，延迟和账单一起往上拱。

再比如 max_turns 不是装饰。一个不设上限的循环，遇到失败工具、模糊任务或模型执念，账单就没有上限。模型连续两次用同一参数调用同一工具，也不该继续假装一切顺利，系统应该识别它正在原地打转。

框架当然能帮忙。它可以保存 checkpoint，提供 trace，处理限流与重试，让运行中断后恢复，还能把多个循环接起来。可你得先知道自己在买哪一种能力。 不然碰到问题，只会从 LangChain 换到 LangGraph，再从 LangGraph 换到下一个热门仓库。依赖装了一轮，故障还在原地等你。

不是哥们，换壳不算修 bug。

它把评估塞在 RAG 前面，这一下有点子牛逼

多数课程的顺序，是先让你做出一个会聊天的东西。

接 API，做 RAG，塞向量库，加 Agent。Demo 终于回答对一个问题，截图，收工。评估通常放在靠后的高级章节里，像一道有空再点的配菜。

这个仓库没有。

它在模型 API 后面、RAG 前面，就放了一章 Evals I。任务小得不能再小，把客服邮件抽成结构化工单。先写一组可信的 golden set，也就是人工确认过的标准样本，再看输出结构是否合法、字段是否正确，用同一批样本比较 prompt v1 和 v2。

这一步看着不性感，却直接改掉一个危险习惯。

你不再问「改完感觉是不是更好」，而会问「同一批样本上，哪个数字动了」。一个规则救了两条输入，却弄坏另外三条，肉眼试一次很难发现，回归评估会把它揪出来。

这也是我觉得它不像资源合集、更像工程训练的原因。后面的 RAG、Agent、微调、运维没有各自开一条新故事线，评估会反复回来。检索改了 chunk size，要测；换了 reranker，要测；Agent 工具描述变了，不只看最终答案，还要看轨迹；模型升级了，要在 CI 里跑回归。

模型输出有概率，工程不能靠祈祷。

到了 Harness Engineering，它又补上三块容易被忽略的活。

一块是上下文组装。长任务不能任由历史膨胀，超过阈值以后要压缩中间部分，同时保住原始任务、最近几轮，以及模型已经答应过的约束。直接砍最旧消息很省事，也可能顺手砍掉第十五轮仍然必须遵守的条件。

一块是工具结果整形。工具返回 50KB 文件，不要整坨喂回模型，可以保留头尾，加一句明确的「中间省略 N 个字符」。报错也别只回一个 None 或几十行堆栈，要告诉模型文件不存在，并建议先调用 list_files。错误可行动，模型才有机会恢复。

还有一块是验证循环。模型说「我已经把总额写进 summary.md」，只是一个声明，不是交付。程序能算出的真值，就让程序验。金额不一致，把具体差值塞回去修复，并给修复次数设上限。该失败时干净失败，比拿一个看着顺眼的答案糊弄过去强得多。

坦率讲，这三块没有一块能在发布会里当高潮。可无人值守的 Agent 能不能过夜跑，靠的就是这些不太上镜的东西。

最扎心的一课，是劝你少用 Agent

如果一套课从头教 Agent，结尾大概率会鼓励你把所有东西 Agent 化。

这个仓库偏不。

它专门做了一个 合同抽取的 pipeline 与 Agent 对决。任务固定，从每份合同里抽取签约方、生效日期、年度金额和终止通知天数。

Agent 版本可以自由调用工具，自己决定下一步。听起来很聪明。pipeline 版本只做一次模型调用，要求固定 schema，再确定性解析。两边共用同一组答案和 token 计数，直接比较准确率与成本。

结果的判断并不复杂。四个字段每次都一样，步骤早就知道，模型根本不需要决定下一步。 给它自由，只是多买了轮数波动、历史重发、调试困难和结果不确定。

步骤固定时，绕更多圈不会让结果更聪明，只会让成本更难预测。

仓库里有个形容很损，很多所谓 Agent，只是「穿着风衣的 pipeline」。我看到这句笑了一下，嘶，确实戳中不少项目。

那什么时候真该用 Agent？

当下一步取决于上一轮发现。读一条线上报错，再决定查日志、配置、数据库还是网络；做开放式研究，拿到一个证据后再选择下一条搜索路径；面对无法提前枚举的工具组合。这些任务的分支不是你懒得写，而是真的要等结果回来才知道。

即便如此，也不必把整条业务都包进一个巨型循环。更稳的做法经常是固定 pipeline 扛住主干，只把那个真的会分叉的步骤提升成一个有预算、有超时、有验证的 bounded agent。

先 pipeline，证据足够再升级。

反过来，把已经上线的巨型 Agent 一点点拆回可预测流程，那个疼法，做过 on-call 的朋友大概能想象。

真要学，别把 33 个绿勾当毕业证

这个仓库最大的诱惑，是免费。

Colab 能跑，主要练习用 Groq 免费 API，不用信用卡。LoRA 和自托管推理这种免费 API 扛不了的部分，作者做成概念讲解加可选 GPU 附录，并说已经在 Colab T4 上验证。对想从后端或全栈转到 Applied AI 的人，进入门槛确实压得很低。

但别急着从 00 一路点运行到 12，然后宣布棒棒的，课程通关。

更有用的跑法，是每一段都故意弄坏一次。

在 Evals I 里加一条明显错误的规则，确认分数真的会掉。给 golden set 塞进含糊、短文本和中英混合样本，看评估能不能抓住你害怕的边界。

在 Agent loop 里把工具描述改烂，连续跑三次，看模型会不会放弃计算器、开始自己心算。把每轮 prompt_tokens 打出来，亲眼看历史怎样越滚越大。

到了 Guardrails & Budgets，让任务故意超过三轮，让工具故意重复失败，让破坏性操作撞上确认门。系统能优雅停下，才算你拥有它。只在 happy path 上跑绿，没有太大意义。

再挑一个自己的小任务，做两版。固定 pipeline 一版，bounded agent 一版，记录准确率、token、P95 延迟、失败类型和恢复次数。等你能用这些数字解释为什么选其中一个，简历上的 LangGraph 才不只是关键词。

免费额度也有边界。评估会按样本发请求，很容易碰到每分钟或每日 token 限制。仓库建议换一个还有余量的免费模型继续验证，因为这里要练的是方法，不是某一次分数。这个提醒挺朴素，也很重要。

我始终觉得，学 AI 工程最危险的状态，不是不会框架，而是只会框架。

框架会更新，API 会换形状，今天的最佳实践过几个月可能就进迁移指南。可 golden set、预算、超时、可行动错误、上下文压缩、工具结果整形、代码验证，这些东西没那么容易过期。

所以 Framework-free 不是终点。

它只是把船壳暂时拆开，让你看清水从哪里进来。等你重新装回 LangGraph 或别的框架，手里不只有一张会跑的 Demo 截图，还有罗盘、舱底泵和一份知道该查哪层的故障手册。

这才是快。