每天学习一个Agent - 构建可信LLM应用的原则
目录
简介
项目地址：https://github.com/humanlayer/12-factor-agents
项目介绍：《12-Factor Agents》是一份面向生产级 LLM（大语言模型）应用的工程实践指南，作者 Dex 把自己与 100+ 位技术创始人、数百个 AI 项目的经验抽象成 12 条“因子”，对应传统软件里的“12-Factor App”。核心主张是：真正可靠的 AI Agent 应该“以软件为主”，而非把控制权完全交给 LLM 的黑盒循环。
核心观点提炼
现象
作者在与100+的SaaS应用构建者交流，发现了一些现象或者观点：
-
Agent框架可以很快做原型验证，但是想做好Agent必须要自己编码
市面常见框架（LangChain、CrewAI、LangGraph…）做原型很快，但做到 80%左右的成功率后，想再提升就必须抛弃框架自己编码实现
-
真正能用的产品不会完全交给LLM决策，只是关键节点调用LLM
-
成功的团队不会直接套用重量级框架，而是把Agent思维拆成可插拔的插件，嵌入到现有的代码和流程中
总结起来观点是：从实际的应用场景上来看，现在阶段完全交给LLM做任务不现实，更不用说号称完善的Agent框架了，更好的做法是用LLM思维重构现有应用
Agentic设计的原则
作者总结了12条Agentic应用设计的原则：
- Natural Language to Tool Calls：把用户自然语言转成结构化函数调用
- Own your prompts：完全控制你的Prompt，不要把Prompt交给框架定义，把 Prompt 当代码版本化、可测试、可回滚
- Own your context window：完全控制放进 LLM 上下文的内容，而不是让框架自动拼装
- Tools are just structured outputs： 完全控制你的控制流，LLM工具调用只是格式化输出，触发确定性代码
- Unify execution state and business state ：统一运行状态和业务状态，本质上是把执行状态如Tool的执行结果加入到对话中方便管理与断点续执行
- Launch/Pause/Resume with simple APIs ：通过简单 API 即可暂停等待控制Agent执行、暂停、恢复
- Contact humans with tool calls ：把“联系人类”也封装成一次工具调用，Agent 流程里无缝等待人工输入
- Own your control flow： 自己定义关键流程，比如判断当LLM要调用高危Tools的时候，先中断等待人工确认，保障流程的可控性
- Compact Errors into Context Window：如果执行出错，把错误放到对话上下文中，让LLM自修复
- Small, Focused Agents：与其做大而全的 Agent，不如拆成多个各司其职的小 Agent，把Agent作为更大更具确定性系统中的子块
- Trigger from anywhere, meet users where they are：支持 Slack、邮件、Webhook、定时任务等任意触发渠道通知人来介入
- Make your agent a stateless reducer：
newState = agentReducer(oldState, event)，根据状态和发生的事来让LLM决定下一步，不用存储任何状态，可重入可测试可扩展 - pre-fetch all the context you might need：尽可能预先把需要的内容加入到Context如Prompt里，不要让LLM先判断需要获取->调用工具获取->加入上下文，减少IO浪费等
核心设计逻辑
- “Agent” ≠ 让 LLM 无限制循环，而是可控的 DAG + 工具调用 + 人工介入点。
- 把 LLM 当“带有噪声的函数”，其余部分用经典软件工程手段（类型、单测、CI/CD、可观测性）加固。
- 框架可借鉴，但必须能 100% 透出 prompt、schema、状态，否则后期必踩坑。
- 质量瓶颈往往在最后 20%，需要可调试、可回滚、可灰度的工程体系，而非更花哨的模型。
落地建议
- 从现有系统最小切口开始：例如把一个手动审批流程改成“LLM 预填 + 人工确认”的 Factor 7。
- Prompt、schema、状态机全部放 Git，走 Code Review。
- 用轻量库（如 FastAPI + Pydantic + 自研状态机）即可落地，不必引入重量级 Agent 框架。
- 日志/跟踪必须细到每一步 LLM 的输入输出，方便后期“投喂”测试用例做回归。