https://github.com/humanlayer/12-factor-agents

image.png

要素序号 要素名称 核心定义与解决的问题 实践价值
1 Natural Language to Tool Calls（自然语言到工具调用） 智能体的核心能力：将人类自然语言指令，转化为可执行的工具调用指令（如调用 API、数据库查询、第三方服务），而非直接生成自然语言回答。解决问题：避免智能体 “空谈”，确保其能落地执行实际任务。 明确智能体的 “行动导向” 定位，让能力可量化、可验证（如 “查询天气” 需调用天气 API，而非仅描述天气）。
2 Own your prompts（拥有你的提示词） 提示词（Prompt）是智能体的 “逻辑核心”，需将其视为代码资产进行管理（版本控制、可追溯、可修改），而非依赖第三方平台的黑盒提示或临时编写的文本。解决问题：避免提示词失控（如第三方平台修改规则导致智能体失效）、无法复现问题。 让提示词成为 “可维护的代码”，支持迭代优化、回滚，适配不同大模型（如从 GPT 切换到 Claude 时可复用核心提示逻辑）。
3 Own your context window（拥有你的上下文窗口） 上下文窗口（Context Window）是智能体存储 “对话历史、任务状态、工具结果” 的核心载体，需自主掌控其内容、长度与生命周期，而非完全依赖大模型的内置上下文。解决问题：避免大模型上下文长度限制导致的 “记忆丢失”，或上下文内容不可控（如冗余信息占用额度）。 支持 “长任务拆分”（如分步骤处理复杂需求）、“上下文压缩”（仅保留关键信息），降低大模型调用成本。
4 Tools are just structured outputs（工具即结构化输出） 智能体调用的 “工具” 本质是结构化的数据输出（如 JSON、XML 格式的指令），而非非结构化文本。工具的定义需标准化（输入参数、输出格式、错误码）。解决问题：避免工具调用结果无法解析（如自然语言描述的 “查询失败” 无法被程序处理）、工具间无法协同。 实现 “工具解耦”（智能体可调用任意符合标准的工具）、“结果自动化处理”（结构化输出可直接作为下一个工具的输入）。
5 Unify execution state and business state（统一执行状态与业务状态） 智能体的 “执行状态”（如 “正在调用工具”“等待用户输入”）与 “业务状态”（如 “用户订单号”“任务进度”）需存储在同一个可访问的载体中（如数据库、缓存），而非分散在代码变量或大模型上下文中。解决问题：避免状态丢失（如服务重启后任务中断）、状态不一致（执行状态与业务数据不匹配）。 支持任务的 “断点续跑”、状态的实时监控与回溯，适配分布式部署场景。
6 Launch/Pause/Resume with simple APIs（通过简单 API 实现启停 / 续跑） 智能体的生命周期（启动任务、暂停任务、恢复任务）需通过标准化的 API 控制，而非依赖手动操作或硬编码逻辑。解决问题：避免任务无法干预（如长时间运行的任务需紧急暂停）、无法集成到自动化运维系统。 支持与外部系统协同（如通过 CI/CD 触发智能体任务）、人工干预紧急场景（如发现错误时暂停任务）。
7 Contact humans with tool calls（通过工具调用联系人类） 当智能体遇到无法独立解决的问题（如信息缺失、权限不足）时，需将 “联系人类” 视为一种 “工具”—— 通过标准化工具调用触发通知（如邮件、Slack 消息、工单），而非硬编码通知逻辑。解决问题：避免人机协作碎片化（如部分场景用邮件、部分用短信）、无法追踪 “人类干预记录”。 统一人机协作入口，将人类反馈作为 “工具结果” 重新输入智能体，形成 “智能体→人类→智能体” 的闭环。
8 Own your control flow（拥有你的控制流） 智能体的任务流程（如 “先调用工具 A，再根据结果决定调用工具 B 或 C”）需由开发者自主定义（如通过代码、规则引擎），而非完全依赖大模型的 “黑盒决策”。解决问题：避免流程不可控（如大模型突然偏离预设逻辑）、难以调试（无法定位流程中断点）。 平衡 “AI 动态决策” 与 “工程确定性”，核心流程可固定（如合规校验步骤），非核心流程可交给 AI 优化。
9 Compact Errors into Context Window（将错误压缩到上下文窗口） 智能体运行中产生的错误（如工具调用失败、参数错误）需被压缩为结构化的精简信息（如 “工具 X 调用失败：API 超时（错误码 504）”），并存入上下文窗口，而非直接丢弃或返回冗长日志。解决问题：避免错误信息占用过多上下文额度，或智能体无法基于错误调整后续行为（如 “不知道之前失败原因，重复调用错误工具”）。 支持智能体的 “自我纠错”（基于上下文的错误信息重新尝试），同时降低大模型处理错误的成本。
10 Small, Focused Agents（小型、聚焦的智能体） 智能体应遵循 “单一职责原则”，每个智能体仅解决一个特定领域的问题（如 “订单查询智能体”“物流跟踪智能体”），而非设计 “全能型智能体”。解决问题：避免大型智能体逻辑复杂（难以维护）、功能耦合（修改一个功能影响其他功能）。 支持智能体的 “模块化组合”（如 “用户咨询智能体” 调用 “订单查询” 和 “物流跟踪” 两个子智能体），提升复用性与迭代效率。
11 Trigger from anywhere, meet users where they are（多触发源，贴近用户场景） 智能体的触发方式应多样化（如 API 调用、用户消息、定时任务、事件通知），且能在用户常用的渠道（如 Slack、邮件、APP、网页）提供服务，而非局限于单一入口。解决问题：避免智能体 “触达壁垒”（用户需切换到特定平台使用）、无法融入现有业务流程。 提升用户体验（在熟悉的场景中使用智能体），扩大智能体的应用范围（如电商场景中，订单支付后自动触发 “物流跟踪智能体”）。
12 Make your agent a stateless reducer（让智能体成为无状态归约器） 智能体的核心逻辑应设计为 “无状态”：每次执行仅依赖 “输入的上下文状态” 和 “工具结果”，输出 “新的上下文状态”，如同函数式编程中的 “归约器（Reducer）”，不依赖本地存储的临时状态。解决问题：避免状态耦合（多个实例共享本地状态导致冲突）、难以水平扩展（无法多实例并行处理任务）。 支持智能体的 “水平扩展”（增加实例即可提升吞吐量）、“可追溯性”（每个状态变更都可通过输入输出复现）。