《12-Factor Agents》构建可靠LLM应用：从循环到工程化的实践指南（建议收藏）

前言

–

❝

在构建生产级AI Agent的过程中，许多开发者都会遇到同样的问题：使用现有框架可以快速达到70-80%的质量标准，但要突破这个瓶颈并实现真正的生产可用性，往往需要深度定制甚至重新构建。

本文基于《12-Factor Agents》理念，总结了构建可靠LLM应用的核心原则，帮助开发者避开常见陷阱，构建真正可用的AI系统,欢迎关注阿东玩AI。

本文目录：

核心理念：从循环到工程

传统Agent的困境

这里的实现是：你可以减少软件编写量，只需将图的“边”交给 LLM，让它自己找出节点即可。你可以从错误中恢复，减少代码编写量。

大多数Agent框架采用的是简单的循环模式：

initial_event = {"message": "..."} context = [initial_event] whileTrue: next_step = await llm.determine_next_step(context) context.append(next_step) if (next_step.intent === "done"): return next_step.final_answer result = await execute_step(next_step) context.append(result)

这种方法的问题在于：

• 控制流不可预测：完全依赖LLM决策
• 错误处理困难：缺乏结构化的异常处理
• 状态管理混乱：执行状态与业务状态混合
• 可观测性差：难以调试和监控

12-Factor方法论

真正优秀的Agent不是"给LLM一堆工具让它自由发挥"，而是大部分由确定性代码构成，在关键决策点巧妙地融入LLM能力。

我们没有给智能体提供大量的工具或任务。LLM 的主要价值在于解析人类的纯文本反馈并提出更新的行动方案。我们尽可能地隔离任务和上下文，以使 LLM 专注于一个 5-10 步的小型工作流程。

那么Agent到底是什么？

• 提示- 告诉 LLM 如何操作，以及它有哪些可用的“工具”。提示的输出是一个 JSON 对象，它描述了工作流程的下一步（“工具调用”或“函数调用”）。
• switch 语句- 根据 LLM 返回的 JSON，决定如何处理它。
• 累积上下文- 存储已发生的步骤及其结果的列表
• for 循环- 直到 LLM 发出某种“终端”工具调用（或纯文本响应），将 switch 语句的结果添加到上下文窗口并要求 LLM 选择下一步。

12个核心原则

1. 自然语言到工具调用 (Natural Language to Tool Calls)

原则：将自然语言输入转换为结构化的工具调用，而非直接文本输出。

// ❌ 错误方式 - 依赖文本解析 const response = await llm.complete("帮我发送邮件给张三") // 需要解析："我将为您发送邮件..." // ✅ 正确方式 - 结构化输出 const toolCall = await llm.generateToolCall(prompt, tools) // 返回：{ tool: "send_email", params: { to: "张三", ... } }

2. 拥有你的提示词 (Own Your Prompts)

原则：将提示词作为代码资产管理，而非隐藏在框架中。

• 提示词应该版本化管理
• 支持A/B测试和灰度发布
• 提供清晰的提示词模板系统

3. 拥有你的上下文窗口 (Own Your Context Window)

原则：主动管理上下文内容，而非被动累积。

您不一定需要使用基于标准消息的格式来向 LLM 传达上下文。

❝

在任何特定时刻，你向代理机构的 LLM 提供的输入都是“这是目前为止发生的事情，下一步是什么”

一切都与上下文工程有关。LLM是无状态函数，它将输入转化为输出。为了获得最佳输出，你需要为它们提供最佳输入。

创造良好的环境意味着：

• 你给模特的提示和指示
• 您检索的任何文档或外部数据（例如 RAG）
• 任何过去的状态、工具调用、结果或其他历史记录
• 任何来自相关但独立的历史/对话的过去信息或事件（记忆）
• 关于输出什么类型的结构化数据的说明

class ContextBuilder { buildContext(userMessage: string, taskState: TaskState): Message[] { return [ this.buildSystemPrompt(taskState), ...this.selectRelevantHistory(userMessage, taskState), this.buildCurrentTask(taskState), { role: "user", content: userMessage } ] } selectRelevantHistory(query: string, state: TaskState): Message[] { // 基于相似度或重要性选择历史消息 returnthis.vectorSearch(query, state.messageHistory) .slice(0, this.maxHistoryTokens) } }

拥有上下文窗口的主要好处：

1. 信息密度：以最大化 LLM 理解的方式构建信息
2. 错误处理：以有助于 LLM 恢复的格式包含错误信息。考虑在错误和失败的调用解决后将其从上下文窗口中隐藏。
3. 安全性：控制传递给 LLM 的信息，过滤掉敏感数据
4. 灵活性：根据你的使用情况调整格式
5. 令牌效率：优化上下文格式以提高令牌效率和 LLM 理解

上下文包括：Prompt、说明、RAG 文档、历史记录、工具调用、记忆

请记住：上下文窗口是您与 LLM 的主要界面。掌控信息的组织和呈现方式可以显著提升代理的性能。

示例 - 信息密度 - 相同的消息，更少的标记：

4. 工具即结构化输出 (Tools are Structured Outputs)

原则：将工具调用视为结构化数据生成，而非函数执行。

工具定义应该：

• 明确输入输出schema
• 提供详细的描述和示例
• 支持参数验证

例如，假设您有两个工具CreateIssue和SearchIssues。要求LLM“使用几种工具中的一种”实际上就是要求它输出JSON，我们可以将其解析为表示这些工具的对象。

classIssue: title: str description: str team_id: str assignee_id: str classCreateIssue: intent: "create_issue" issue: Issue classSearchIssues: intent: "search_issues" query: str what_youre_looking_for: str

模式很简单：

• LLM 输出结构化 JSON
• 确定性代码执行适当的操作（如调用外部 API）
• 捕获结果并反馈到上下文中

这样就将 LLM 的决策和应用程序的操作清晰地区分开来。LLM 决定做什么，而你的代码控制如何执行。LLM 被称为工具并不意味着你必须每次都以相同的方式执行特定的对应函数。

5. 统一执行状态和业务状态 (Unify Execution State)

原则：将Agent的执行状态与业务逻辑状态统一管理。

interface UnifiedState { // 业务状态 user: User currentTask: Task businessData: any // 执行状态 step: number lastAction: string errors: Error[] // 上下文状态 messageHistory: Message[] availableTools: Tool[] }

你可能有一些内容无法放入上下文窗口，例如会话 ID、密码上下文等等，但你的目标应该是尽量减少这些内容。通过采用你可以控制实际进入 LLM 的内容。

这种方法有几个好处：

1. 简单：所有状态的真相来源
2. 序列化：线程可以轻松序列化/反序列化
3. 调试：整个历史记录在一个地方可见
4. 灵活性：只需添加新的事件类型即可轻松添加新状态
5. 恢复：只需加载线程即可从任何点恢复
6. 分叉：可以通过将线程的某些子集复制到新的上下文/状态 ID 中来随时分叉线程
7. 人机界面和可观察性：将线程转换为人类可读的 Markdown 或丰富的 Web 应用程序 UI

6. 启动/暂停/恢复的简单API (Launch/Pause/Resume)

原则：支持长时间运行任务的暂停和恢复。

interface AgentController { launch(initialState: State): Promise<AgentExecution> pause(executionId: string): Promise<void> resume(executionId: string, additionalInput?: any): Promise<void> getStatus(executionId: string): Promise<ExecutionStatus> }

用户、应用程序、管道和其他代理应该能够轻松地使用简单的 API 启动代理。

当需要长时间运行的操作时，代理及其协调确定性代码应该能够暂停代理。

像 webhook 这样的外部触发器应该允许代理从中断的地方恢复，而无需与代理编排器进行深度集成。

7. 通过工具调用联系人类 (Contact Humans with Tool Calls)

原则：人机交互也应该通过结构化的工具调用实现。

const tools = [ { name: "request_human_approval", description: "请求人类审核和批准", parameters: { type: "object", properties: { request_type: { type: "string", enum: ["approval", "input", "clarification"] }, message: { type: "string" }, context: { type: "object" }, urgency: { type: "string", enum: ["low", "medium", "high"] } } } } ]

好处：

1. 清晰的指示：针对不同类型的人际交往的工具允许 LLM 提供更多具体性
2. 内循环 vs 外循环：在传统的 ChatGPT 风格界面之外启用代理工作流程，其中控制流和上下文初始化可能不是Agent->Human（Human->Agent想想由 cron 或事件启动的代理）
3. 多人访问：可以通过结构化事件轻松跟踪和协调来自不同人的输入
4. 多代理：简单的抽象可以轻松扩展以支持Agent->Agent请求和响应
5. 持久性：结合因素 6（使用简单的 API 启动/暂停/恢复），打造持久、可靠且可自省的多人工作流程

8. 拥有你的控制流 (Own Your Control Flow)

原则：不要让LLM完全控制程序流程，而是在预定义的流程中让LLM做决策。

class TaskOrchestrator { async executeTask(task: Task, state: State): Promise<State> { // 预定义的步骤序列 const steps = [ this.validateInput, this.gatherContext, this.makeDecision, // 这里使用LLM this.executeAction, this.validateResult ] for (const step of steps) { state = await step(task, state) if (state.shouldPause) { return state } } return state } }

构建适合您特定用例的控制结构。具体来说，某些类型的工具调用可能需要跳出循环，等待人工或其他长时间运行的任务（例如训练管道）的响应。您可能还希望包含以下自定义实现：

• 工具调用结果的汇总或缓存
• 结构化输出的LLM
• 上下文窗口压缩或其他内存管理
• 日志记录、跟踪和指标
• 客户端速率限制
• 持久睡眠/暂停/“等待事件”

9. 将错误压缩到上下文窗口 (Compact Errors)

原则：错误信息应该结构化并适合上下文窗口。

class ErrorCompactor { compactError(error: Error, context: ExecutionContext): CompactError { return { type: error.constructor.name, summary: this.summarizeError(error), relevantStack: this.extractRelevantStack(error, context), suggestedActions: this.suggestRecoveryActions(error), timestamp: new Date().toISOString() } } }

这点比较短，但值得一提。代理的优点之一是“自我修复”——对于短任务，LLM 可能会调用失败的工具。优秀的 LLM 能够很好地读取错误消息或堆栈跟踪，并确定在后续工具调用中需要更改的内容。

好处：

1. 自我修复：LLM 可以读取错误消息并找出在后续工具调用中需要更改的内容
2. 持久：即使一个工具调用失败，代理仍可继续运行

我确信你会发现，如果你这样做太多次，你的经纪人就会开始失控，并可能一遍又一遍地重复同样的错误。所以需要第10步。

10. 小而专注的Agent (Small, Focused Agents)

原则：构建多个专门化的小Agent，而非一个万能大Agent。

// ❌ 避免大而全的Agent class MegaAgent { handleEmail() { /* 处理邮件 */ } handleCalendar() { /* 处理日历 */ } handleDocuments() { /* 处理文档 */ } handleCustomers() { /* 处理客户 */ } } // ✅ 推荐：专门化的小Agent class EmailAgent { /* 专注邮件处理 */ } class CalendarAgent { /* 专注日历管理 */ } class DocumentAgent { /* 专注文档处理 */ }

小型、专注Agent的优势：

1. 可管理上下文：上下文窗口越小，LLM 性能越好
2. 职责明确：每个代理都有明确的范围和目的
3. 更高的可靠性：减少在复杂的工作流程中迷失的机会
4. 更容易测试：更简单地测试和验证特定功能
5. 改进的调试：更容易识别和修复发生的问题

11. 随处触发，满足用户需求 (Trigger from Anywhere)

原则：Agent应该能从多种渠道触发，满足用户在不同场景的需求。

支持的触发方式：

• API调用
• Webhook
• 定时任务
• 消息队列
• 用户界面

12. 让Agent成为无状态Reducer (Stateless Reducer)

原则：Agent的核心逻辑应该是纯函数，便于测试和水平扩展。

type AgentReducer = (currentState: State, event: Event) =>Promise<State> const agentReducer: AgentReducer = async (state, event) => { // 纯函数逻辑，不依赖外部状态 switch (event.type) { case'USER_MESSAGE': returnawait handleUserMessage(state, event) case'TOOL_RESULT': returnawait handleToolResult(state, event) default: return state } }

实践建议

渐进式采用

不要一次性重写整个系统，而是逐步引入这些原则：

1. 从Factor 1开始：先实现结构化输出
2. 管理提示词：将提示词从代码中分离
3. 优化上下文管理：实现智能的上下文选择
4. 添加状态管理：统一业务和执行状态
5. 增强控制流：预定义关键流程步骤

工具选择

推荐的技术栈：

• 结构化输出：OpenAI Function Calling、Anthropic Tool Use
• 提示词管理：BAML、LangSmith
• 状态管理：Redux模式、状态机
• 监控观测：LangSmith、Weights & Biases

质量保证

• 单元测试：对每个Factor进行测试
• 集成测试：测试完整的Agent流程
• A/B测试：比较不同实现方案
• 监控告警：实时监控Agent性能

总结

–

12-Factor Agents提供了一套经过实践验证的原则，帮助开发者构建真正可用的LLM应用。关键在于：

1. 不要让LLM控制一切：在结构化的框架内使用LLM能力
2. 拥有核心组件：主动管理提示词、上下文和控制流
3. 渐进式优化：从简单开始，逐步完善
4. 重视工程实践：测试、监控、版本管理一样不能少

通过遵循这些原则，你可以构建出既强大又可靠的AI Agent，真正满足生产环境的需求。

❝

本文基于Dex Horthy的《12-Factor Agents》整理而成。更多技术细节请参考原始文档：https://github.com/humanlayer/12-factor-agents

普通人如何抓住AI大模型的风口？

领取方式在文末

为什么要学习大模型？

目前AI大模型的技术岗位与能力培养随着人工智能技术的迅速发展和应用 ， 大模型作为其中的重要组成部分 ， 正逐渐成为推动人工智能发展的重要引擎 。大模型以其强大的数据处理和模式识别能力， 广泛应用于自然语言处理 、计算机视觉 、 智能推荐等领域 ，为各行各业带来了革命性的改变和机遇 。

目前，开源人工智能大模型已应用于医疗、政务、法律、汽车、娱乐、金融、互联网、教育、制造业、企业服务等多个场景，其中，应用于金融、企业服务、制造业和法律领域的大模型在本次调研中占比超过30%。

随着AI大模型技术的迅速发展，相关岗位的需求也日益增加。大模型产业链催生了一批高薪新职业：

人工智能大潮已来，不加入就可能被淘汰。如果你是技术人，尤其是互联网从业者，现在就开始学习AI大模型技术，真的是给你的人生一个重要建议！

最后

只要你真心想学习AI大模型技术，这份精心整理的学习资料我愿意无偿分享给你，但是想学技术去乱搞的人别来找我！

在当前这个人工智能高速发展的时代，AI大模型正在深刻改变各行各业。我国对高水平AI人才的需求也日益增长，真正懂技术、能落地的人才依旧紧缺。我也希望通过这份资料，能够帮助更多有志于AI领域的朋友入门并深入学习。

真诚无偿分享！！！
vx扫描下方二维码即可
加上后会一个个给大家发

大模型全套学习资料展示

自我们与MoPaaS魔泊云合作以来，我们不断打磨课程体系与技术内容，在细节上精益求精，同时在技术层面也新增了许多前沿且实用的内容，力求为大家带来更系统、更实战、更落地的大模型学习体验。

希望这份系统、实用的大模型学习路径，能够帮助你从零入门，进阶到实战，真正掌握AI时代的核心技能！

01教学内容

• 从零到精通完整闭环：【基础理论 →RAG开发 → Agent设计 → 模型微调与私有化部署调→热门技术】5大模块，内容比传统教材更贴近企业实战！

• 大量真实项目案例：带你亲自上手搞数据清洗、模型调优这些硬核操作，把课本知识变成真本事‌！

02适学人群

应届毕业生‌：无工作经验但想要系统学习AI大模型技术，期待通过实战项目掌握核心技术。

零基础转型‌：非技术背景但关注AI应用场景，计划通过低代码工具实现“AI+行业”跨界‌。

业务赋能突破瓶颈：传统开发者（Java/前端等）学习Transformer架构与LangChain框架，向AI全栈工程师转型‌。

vx扫描下方二维码即可

本教程比较珍贵，仅限大家自行学习，不要传播！更严禁商用！

03入门到进阶学习路线图

大模型学习路线图，整体分为5个大的阶段：

04视频和书籍PDF合集

从0到掌握主流大模型技术视频教程（涵盖模型训练、微调、RAG、LangChain、Agent开发等实战方向）

新手必备的大模型学习PDF书单来了！全是硬核知识，帮你少走弯路（不吹牛，真有用）

05行业报告+白皮书合集

收集70+报告与白皮书，了解行业最新动态！

0690+份面试题/经验

AI大模型岗位面试经验总结（谁学技术不是为了赚$呢，找个好的岗位很重要）

07 deepseek部署包+技巧大全

由于篇幅有限

只展示部分资料

并且还在持续更新中…

真诚无偿分享！！！
vx扫描下方二维码即可
加上后会一个个给大家发