来源：12-Factor Agents / Factor 1（Natural Language to Tool Calls）

一句话先懂

把“人话需求”翻译成“结构化动作”，让模型负责理解，让代码负责执行。

奶奶版先理解

你跟家里人说：

• “帮我交电费 500”

这句话要真正落地，必须变成明确单据：

• 任务：交电费
• 金额：500
• 账户：国家电网 xx 户号
• 截止时间：今晚 20:00

来源：12-Factor Agents / Factor 2（Own your prompts）

一句话先懂

提示词是你的核心业务逻辑之一，不要完全交给黑盒框架。

奶奶版理解

你请了一个能力很强的帮手，但你只说“你看着办”。

• 他有时做得很好
• 也可能把关键事情做错

如果你给的是明确说明书（步骤、边界、禁区、异常处理），稳定性就会高很多。

原文重点（不是反框架，而是反黑盒）

Factor 2 的意思不是“框架不能用”，而是：

来源：12-Factor Agents / Factor 3（Own your context window）

一句话先懂

模型是“无状态函数”，它只会基于你给的上下文做判断。上下文质量，直接决定输出质量。

奶奶版理解

看病时如果只说“我不舒服”，医生只能猜。
如果你给出病历、检查单、过敏史，诊断就会更准。

上下文窗口就是给模型的“病历袋”。

原文最关键的 3 个观点

1. 上下文不止是聊天记录，还包括：提示词、RAG 文档、工具结果、历史事件。
2. 不必死守标准 chat message 格式，可设计更高密度的自定义格式。
3. 目标是“对模型更友好”：高信息密度、低噪声、可控安全。

来源：12-Factor Agents / Factor 4（Tools are just structured outputs）

一句话先懂

工具调用不是魔法，本质是模型输出结构化数据，然后由确定性代码执行。

奶奶版理解

你在餐厅点菜时，给服务员的是“菜名+份数”的单子，不是自己进后厨炒。
“点菜单”是结构化输出，“后厨流程”是确定性执行。

原文核心观点

• 模型做“选择下一步动作”的决策。
• 你的系统做“如何执行动作”的编排。
• 一次工具调用可映射成一段复杂但可控的业务流程。

来源：12-Factor Agents / Factor 5（Unify execution state and business state）

一句话先懂

尽量用一条事件线程同时承载“业务发生了什么”和“流程走到哪”，减少双状态系统的复杂度。

奶奶版理解

做饭时你记一本流水账：

• 买菜
• 切菜
• 炒到一半停电

这本账既告诉你“饭做到哪步”，也告诉你“发生了什么事”。
不需要再单独维护一本“流程状态账”。

来源：12-Factor Agents / Factor 6（Launch/Pause/Resume with simple APIs）

一句话先懂

智能体要像标准任务系统一样可管理：启动、查询、暂停、恢复都要有清晰 API。

奶奶版理解

炖汤不是必须一直守着火。你可以：

• 先开火
• 中途关火
• 晚上继续炖

智能体也应支持这样“可中断、可续跑”的节奏。

原文关注点

来源：12-Factor Agents / Factor 7（Contact humans with tool calls）

一句话先懂

“请求人工介入”也要做成结构化工具调用，而不是模型随口说一句。

奶奶版理解

社区办事时，工作人员给你的不是“你看着办”，而是标准表单：

• 要你确认什么
• 什么时候回复
• 可选项有哪些

这就是结构化协作。

原文关键洞察

LLM 在“输出自然语言”还是“输出 JSON”之间，经常是一开始就做高风险选择。
一种可实验策略是：让模型尽量总是输出结构化对象，用 intent 区分不同动作。

来源：12-Factor Agents / Factor 8（Own your control flow）

一句话先懂

控制流（循环、分支、暂停、重试、升级）必须由确定性代码掌控，不能交给模型随意决定。

奶奶版理解

导航会建议“右转”，但方向盘和刹车必须在你手里。
遇到施工、堵车、危险路段，你得自己决定绕路还是停车。

原文核心观点

• 模型可以建议“下一步”。
• 程序必须决定“何时继续、何时中断、何时人工接管”。
• 尤其在高风险工具执行前，要允许人工审查。

来源：12-Factor Agents / Factor 9（Compact Errors into Context Window）

一句话先懂

把错误转成结构化、可行动的信息回灌给模型，促成自愈；同时严格限制重试，避免无限打转。

奶奶版理解

做菜失败了，不是直接放弃，而是记住“这次盐放多了”，下一次修正。
但连错三次就要请会做的人帮忙，而不是死磕。

原文核心思想

• agent 的优势之一是自恢复。
• 工具失败后，模型读到错误信息，常能修正下一步。
• 但必须配合控制策略，不然会 error spin（错误旋转）。

来源：12-Factor Agents / Factor 10（Small, Focused Agents）

一句话先懂

不要追求一个“全能大脑”，要建设一组“专科智能体”，每个只解决一个清晰问题。

奶奶版理解

看病时你不会找一个医生同时看牙、做眼科手术、做心脏手术。
专科分工更靠谱。

原文核心逻辑

任务越大、步骤越多、上下文越长，模型越容易迷失。
把任务边界收窄，通常能显著提高成功率和稳定性。

典型架构