12-Factor Agents 2 万星了：Demo 跑通之前，先看这四条

GitHub 上有个项目叫 12-Factor Agents，已经 20350 个 star、1541 个 fork。

它讲的不是怎么写一个漂亮 demo。

它讲的是另一件更难的事：Agent 怎么从“能跑一次”，变成“真能交给用户用”。

现在做 Agent demo 太容易了。接个模型，绑几个工具，写几段 prompt，录个视频，效果看起来很猛。

一进真实业务就露馅。

上下文越塞越乱，工具调用偶尔成功偶尔装死，报错以后不知道卡在哪一步，用户等半天，最后拿到一句“抱歉，我没能完成”。

12-Factor Agents 最有价值的地方，是把这些坑变成了一套工程检查表。

Demo 负责让人看到可能性，工程负责让它真的跑下去。

上下文不是垃圾桶

很多 Agent 一开始就会犯这个错：什么都往上下文里塞。

聊天记录、用户资料、工具返回、历史任务、中间状态，全都塞进去。

短期看，好像信息更全。跑久了，模型注意力会散，旧信息还会污染后面的判断。

真正能用的 Agent，得把上下文分层。

当前任务必须用的，才放进推理窗口。

长期记忆、历史记录、知识库，放到外部系统里。

工具返回的脏数据，要清洗、摘要、截断，再交给模型。

上下文更像操作台，不是仓库。台面上东西越少，手越稳。

工具调用不能靠运气

Agent 调工具最容易翻车。

参数少一个字段，JSON 格式不对，接口超时，返回内容和预期不一致，整个流程就断了。

很多人调 prompt 调半天，其实问题不在 prompt，在工具契约太松。

工具要有清晰 schema，要有超时，要有重试，要有失败后的降级路径。

模型传错参数，系统要能拦住。

工具返回异常，Agent 要知道下一步怎么收场。

一个能上线的 Agent，不能靠“模型这次刚好写对了”活着。

没有 trace，就别谈上线

普通软件出问题，你可以看日志。

Agent 出问题，如果没有 trace，基本只能猜。

它到底是理解错了用户需求，还是工具返回错了？

是上下文里旧信息污染了判断，还是某一步重试把状态搞乱了？

这些东西不记录，后面没人修得动。

12-Factor Agents 很强调可观测：每一次模型调用、每一次工具调用、每一次状态变化，都要能回放。

这不是工程洁癖，是 Agent 进入真实业务的门票。

人工接管不是丢人

再强的 Agent，也会遇到搞不定的事。

权限不够，数据冲突，用户需求越界，工具连续失败，流程卡死。

这时候最怕它硬撑。

硬撑的结果通常是错得更远，还把现场弄脏。

成熟一点的 Agent，要会停下来。

已经做了什么，卡在哪一步，需要人确认什么，清清楚楚交出来。

人工接管不丢人。真正丢人的是明明不会，还继续往下编。

这四条可以直接拿去自查

如果你正在做 Codex skill、浏览器自动化、客服机器人、内容流水线，先拿这四个问题扫一遍。

上下文有没有分层，还是一路乱塞？

工具有没有契约，还是全靠模型临场发挥？

过程有没有 trace，出问题能不能复盘？

失败后能不能交给人，还是只能装死？

这四条过不了，demo 再漂亮也很难稳定。

后面 Agent 拼的不只是模型，更是系统能力。

模型负责聪明，工程负责可靠。能把这两件事接起来，Agent 才有资格进入真正的工作流。

关注我，及时了解更多 AI 资讯和先进 AI 技术。大小项目开发和方案咨询，也可以私信。