15-Factor Agents：生产级智能体工程完整框架（扩展版）

01

简介 (Introduction)

在 GPT-4o 等大型语言模型（LLM）的推动下，智能体（Agent）正在从充满想象力的原型验证，迈向严谨可靠的生产落地。然而，构建一个能在真实世界稳定运行的智能体系统，远不止是编写几行 Prompt。它需要一个健壮的工程框架来应对成本、延迟、幻觉、安全性和可维护性等一系列挑战。

15-Factor Agents 融合了经典的「12-Factor App」思想与新兴的 Context Engineering（上下文工程） 精髓，进一步强调“如何高效准确地为 LLM 提供信息”与“如何节约宝贵的上下文窗口”。本框架分为四大模块、十五条核心工程实践，旨在为团队提供一份清晰的蓝图，用于指导构建高可用、可观测、易扩展的生产级智能体系统。

02

模块与原则 (Modules & Principles)

一. 输入与工具接口 (Input & Tool Interface)

该模块关注如何将非结构化的用户意图，转化为机器可执行、可预测的结构化操作。

1. Natural Language → Tool Calls（自然语言转工具调用）

将用户的文字或语音请求，自动解析为结构化的函数或 API 调用，彻底免除繁琐的正则表达式和脆弱的脚本胶水。

详细说明与示例：

LLM 的核心能力之一就是意图识别。我们应充分利用这一点，让模型直接输出符合预定义规范的 JSON 对象，从而调用后端工具。

用户输入：

“帮我跟进一下市场部的李华，约个会讨论下周三下午三点的 Q3 营销方案初稿。”

传统方式 (脆弱):

用关键词（如“会议”、“李华”）和正则表达式提取时间、人物，非常容易出错。

15-Factor 方式 (健壮):

LLM 直接生成工具调用指令：

JSON

后端服务接收这个 JSON 对象后，就能精准执行任务。如果 LLM 发现信息不明确（例如公司里有多个“李华”），它会被训练成追问：“您是指市场部的李华，还是技术部的李华？”

2. Own Your Prompts（掌控 Prompt）

像管理源代码一样管理你的 Prompt：进行版本控制、执行灰度发布、进行 A/B 测试监测关键指标，并建立指标恶化时的自动回滚机制。

详细说明与示例：

Prompt 是智能体的“灵魂”，微小的改动都可能导致行为剧变。

流量 A (使用 v1.0.0): 50% 的用户请求由旧版 Prompt 处理。

流量 B (使用 v1.1.0): 50% 的用户请求由新版 Prompt 处理。

版本控制: 将 Prompt 文本（尤其是 System Prompt）存储在 Git 仓库中。

A/B 测试:

监控与回滚:

持续监控 toolcallsuccessrate（工具调用成功率）、usersatisfaction_score（用户满意度评分）等指标。如果发现 v1.1.0 版本的 Prompt 导致工具调用失败率上升 5%，则自动将 100% 流量切回 v1.0.0，并触发告警。

3. Tools Are Structured Outputs（工具即结构化输出）

任何内部或外部工具，其返回值都必须是可预测、有模式（Schema）的 JSON 或对象。LLM 应该能直接解析返回的键值对，而无需再次依赖自然语言去理解工具的执行结果。

详细说明与示例：

让机器和机器之间用“机器的语言”沟通，可以极大提升系统的稳定性和解析效率。

不良实践 (返回自然语言):

search_file 工具返回一个字符串：

“找到了，文件名叫《2025年Q2季度销售报告.pdf》，存放于/shared/reports/下。”

LLM 需要再次解析这个句子，可能会出错。

最佳实践 (返回结构化 JSON):

search_file 工具返回定义好的 JSON 对象：

JSON

LLM 可以直接读取 data.file_path 并进行下一步操作（如总结或发送给用户），无需任何模糊的文本解析。如果失败，status 字段会是 error，并附带错误信息。

二. 上下文工程 ＋ Tool 辅助 (Context Engineering & Tool Assistance)

该模块是框架的核心，关注如何动态、经济、精准地构建 LLM 在单次推理中所需的上下文信息。

4. Own Your Context Window（管理上下文窗口）

精心挑选和组合对话历史、知识库检索片段、实时业务状态等信息，动态构建每一次请求的上下文。目标是既要防止因内容过长而溢出，也要避免因信息缺失而“失忆”。

详细说明与示例：

每一次 LLM 调用，其上下文窗口都应该是一个按需构建的“信息包”。

一个典型的上下文构建过程可能如下：

5. Context Schema & Source Registry（上下文架构与信息源登记）

为所有可能注入到上下文中的信息（如文档、数据库记录、API 返回）定义统一的字段和元数据（如来源、更新日期、重要性、敏感等级、引用ID）。

详细说明与示例：

这就像是为智能体的“记忆”建立了一个图书馆索引卡系统。

定义一个 ContextItem 的 Schema:

JSON

当构建上下文时，可以根据 importancescore 决定优先级，或根据 sensitivitylevel 决定是否需要脱敏。

6. Retrieval / Freshness & Tool Completion（检索、保鲜与 Tool 补全）

使用混合检索（向量+关键词）并根据信息的生命周期（TTL）进行滚动淘汰，确保信息新鲜度。

如果初步检索发现信息缺失或过时， 智能体应被设计成能自动调用外部工具 （如数据库查询、实时API、网络爬虫）来补足或更新上下文。

详细说明与示例：

这是一个“检索-验证-补全”的闭环。

用户提问: “最新的项目 Alpha 进展如何？”

步骤 1: 检索 (Retrieval): 系统从向量数据库中检索到一篇关于“项目 Alpha”的周报，但其元数据显示 last_updated: “2025-07-28″（一周前）。

步骤 2: 验证新鲜度 (Freshness Check): 智能体的内部逻辑（或由 LLM 判断）发现这个信息可能过时了。

步骤 3: 工具补全 (Tool Completion): 智能体自动触发一个工具调用。

JSON

步骤 4: 注入新上下文: JIRA 工具返回了最新的几个关键任务状态。智能体将这些新信息注入上下文，然后生成一个既包含周报总结、又包含最新动态的准确回答。

7. Budgeting / Compression & Tool Offloading（预算、压缩与 Tool 卸载）

为每一轮推理动态分配 Token 预算和优先级。

对超长文档或对话历史进行摘要压缩。

在必要时， 使用工具将大块信息（如整个文件）存入外部存储，仅在上下文中保留其摘要和引用ID ，这种技术称为 Offload Context 。

详细说明与示例：

把上下文窗口想象成一个登机箱，你不能把整个衣柜都塞进去，只能带必需品。

场景: 用户上传了一份 50 页的 PDF 并提问：“这份财报里，我们公司在亚太地区的同比增长是多少？”

错误做法: 将整个 PDF 文本塞入上下文，导致窗口溢出且成本高昂。

正确做法 (Offloading):

卸载: Agent 调用一个内部工具 documentparser.processand_store。

该工具：

a. 将 PDF 解析成文本。

b. 为其生成一个整体摘要和各章节摘要。

c. 将完整文本、摘要、以及向量化后的分块存入外部存储（如 S3 + Vector DB），并返回一个唯一的 documentid: “docfinancialreportq2_2025″。

引用: Agent 的上下文中只包含：

“用户上传了文件 documentid: “docfinancialreportq22025″。文件摘要：[此处是简短的摘要]。用户的问题是：‘亚太地区的同比增长是多少？’。你可以使用 vectorsearch.query(doc_id, …) 工具来查询此文件的具体内容。”

执行: LLM 据此调用 vector_search 工具，精准找到相关段落并回答问题。

8. Compact Errors into Context（错误压缩进上下文）

当工具调用失败或系统出现异常时，捕获错误信息，将其摘要并格式化后，重新写回 Prompt 的上下文中。这使得模型能够自我诊断问题、智能重试、或向用户输出一个可理解的、有帮助的错误提示。

详细说明与示例：

让智能体学会“看异常日志”。

Agent 意图: 调用 weather.get_forecast(“New York”)。

工具执行失败: API 返回 503 Service Unavailable 以及一长串 HTML 错误页面。

错误处理中间件: 捕获此异常，并将其压缩成一条简洁的错误信息。

注入新上下文: 下一轮推理的上下文中加入：

[PREVIOUS_CONTEXT]…

[TOOL_RESPONSE]

[USER_QUERY] “还没好吗？”

Agent 的智能响应:

“非常抱歉，我刚才尝试获取天气信息时，天气服务接口暂时无法连接。我会在几分钟后自动重试。您需要等待吗，还是想先处理其他事情？”

三. 流程与状态管理 (Flow & State Management)

该模块关注如何为智能体提供一个可追踪、可恢复、可扩展的执行骨架。

9. Unify Execution State & Business State（统一执行状态与业务状态）

将智能体的执行状态（如当前的调用栈、重试次数）与业务对象的状态（如订单信息、用户信息）存储在同一个持久化介质中（如数据库的同一张表或同一个文档）。这使得每一次交互都可追踪、可审计、可回放。

详细说明与示例：

一个典型的状态记录 (存储在 DynamoDB 或 PostgreSQL 的 JSONB 字段中):

JSON

通过 trace_id，你可以完整复现一次用户交互的全过程。

10. Launch / Pause / Resume with Simple APIs（简单 API 控制生命周期）

通过标准的 REST 或消息队列接口，实现对智能体任务生命周期的一键式控制：启动、挂起、恢复。这使得智能体可以轻松被容器化（Docker/Kubernetes）并进行弹性伸缩。

详细说明与示例：

定义一组 RESTful API 端点：

POST /v1/agent-runs: 启动一个新的智能体任务，请求体包含初始的业务状态和用户输入。返回 trace_id。

GET /v1/agent-runs/{trace_id}: 查看某个任务的当前状态。

POST /v1/agent-runs/{trace_id}/pause: 挂起一个正在运行的任务（例如，等待人工审批）。

POST /v1/agent-runs/{trace_id}/resume: 恢复一个已挂起的任务，请求体可以包含新信息（如审批结果）。

11. Own Your Control Flow（掌控控制流）

使用领域特定语言（DSL）、状态机或工作流引擎（如 AWS Step Functions, Temporal）来显式地编排任务的主流程。仅在流程中预定义的、需要灵活决策的“决策点”上，才授权 LLM 进行判断。

详细说明与示例：

不要让 LLM 成为整个业务流程的“独裁者”，而应让它成为流程中的“超级决策者”。

一个订单处理工作流（用状态机定义）：

LLM DECISION POINT: 如果支付失败，LLM 根据失败原因（如“余额不足” vs “接口超时”）生成不同的安抚和引导话术。

STATE: RECEIVE_ORDER (由 API 触发)

STATE: VALIDATE_INVENTORY (调用内部库存服务)

STATE: PROCESS_PAYMENT (调用支付网关)

STATE: CONFIRM_SHIPPING

STATE: NOTIFY_CUSTOMER (调用通知服务)

在这个流程中，LLM 的作用被严格限制在第 3 步的特定分支处理，而不是决定是否要去验证库存。

12. Make Your Agent a Stateless Reducer（无状态 Reducer Agent）

将所有可变的状态（如对话历史、业务数据）外置到事件流或数据库中。Agent 本身变成一个纯函数，其逻辑遵循 (oldstate, inputevent) → new_state 的模式。这种设计天然幂等，极易测试和水平扩展。

详细说明与示例：

这借鉴了前端框架（如 Redux）的核心思想，极大地增强了系统的可预测性。

伪代码实现：

Python

无论这个函数被调用多少次，只要输入的 currentstate 和 event 相同，输出的 newstate 永远相同。

13. Small, Focused Agents（小而专注的 Agent）

遵循单一职责原则。每个 Agent 只解决一个明确、有限的业务问题（如“预订 Agent”、“报告 Agent”）。通过一个上层“编排 Agent”（Orchestrator）来组合和调用这些小 Agent，而不是试图打造一个无所不能的“巨无霸” Agent。

详细说明与示例：

这等同于软件架构中的“微服务”理念。

Orchestrator Agent: 接收所有请求，判断用户意图，并将任务分发给下游 Agent。

Calendar Agent: 只负责会议相关的查询和操作。

CRM Agent: 只负责客户信息的增删改查。

HR Agent: 只负责假期查询、政策问答。

当用户说“帮我查下大客户A的联系人，并约个会”时，Orchestrator 会先调用 CRM Agent 拿到联系人信息，再将这些信息传递给 Calendar Agent 去完成后续的会议预订。

巨无霸模式 (反例): 一个 MegaAssistant Agent，其 Prompt 长达数千字，包含了处理日历、CRM、HR 系统等所有逻辑。难以维护和调试。

微智能体模式 (推荐):

四. 人机交互与触达 (Human-in-the-Loop & Reach)

该模块关注智能体如何与人协作，以及如何无缝地融入用户的工作流。

14. Contact Humans with Tool Calls（工具调用引入人类协作）

当智能体遇到低置信度的决策、需要审批的敏感操作、或无法处理的异常时，它不应“猜”，而应被设计成能自动“求助”。求助的方式就是调用一个“人类协作”工具，例如创建一张 JIRA 工单、在 Slack/Teams 频道中 @ 相关人员并等待按钮反馈。

详细说明与示例：

场景: 一个财务 Agent 在处理报销申请时，发现一张发票金额巨大（超过 5000 元），超出了它的自动审批权限。

Agent 行为: Agent 不会拒绝，也不会通过，而是调用一个工具：

JSON

结果: 财务经理在 Slack 中收到一条带“批准”和“拒绝”按钮的消息。点击后，其操作结果会通过 callback_id 回传给被挂起的智能体任务，使其能继续执行。

15. Trigger from Anywhere, Meet Users Where They Are（随处触发，直达用户）

同一个核心智能体服务，应该可以被多种不同的前端和入口触发调用。例如，网页聊天框、移动 App、企业微信/Slack 的斜杠指令、甚至是后台的定时任务（CRON Job）。让智能体无缝嵌入到用户已有的工作流程中。

详细说明与示例：

核心业务逻辑（例如上面提到的 bookingagentreducer）是独立的。不同的触发器只是调用它的不同“外壳”。

Web Chat: 一个 React 组件通过 WebSocket 与 Agent 服务通信。

Slack: 一个 Slack App 接收 /book-meeting 命令，解析参数，然后调用 Agent 服务的 REST API。

Email: 一个邮件服务器规则，当收到特定主题的邮件时，触发一个 Lambda/Cloud Function，解析邮件内容并启动 Agent。

CRON Job: 一个每晚执行的定时任务，查询数据库中所有“待确认”的预订，并为每一个启动一个 Agent 任务去发送提醒。

03

附录：落地步骤建议 (Appendix: Implementation Steps)

资产盘点 (Asset Inventory)

行动项: 创建一个共享文档或Wiki页面。

内容: 列出所有可作为 Agent 上下文的信息源（数据库表、API端点、文档库）。为每个信息源定义其 Context Schema（元数据结构），这是第5条原则的起点。

检索实验 (Retrieval Experiment)

行动项: 搭建一个简单的评估框架。

内容: 针对一小组典型用户问题，分别使用纯关键词搜索、纯向量搜索和混合搜索进行测试。评估返回结果的相关性（Precision@K）和覆盖率（Recall）。根据信息类型设定不同的 Freshness（保鲜）策略（如，公司政策文档每年更新一次，产品库存每分钟更新一次）。

窗口压测 (Window Stress Test)

行动项: 编写自动化测试脚本。

内容: 模拟用户进行长达 20-30 轮的复杂对话。监控上下文 Token 的增长情况。测试并调优你的 Budgeting（预算）和 Compression（压缩）策略，确保在长对话下系统不会崩溃或延迟飙升。

工作流集成 (Workflow Integration)

行动项: 选择一个对业务影响大但风险可控的核心流程（如售后支Agent 智能体持问答、内部 IT 求助）。

内容: 在该流程中，首先将 Context 管线（检索、补全、压缩）作为数据准备层嵌入。然后，将 Tool Calling 作为执行层，逐步替换掉原有的手动操作或旧脚本。

监控仪表盘 (Monitoring Dashboard)

成本与性能: llmapilatency (LLM API 延迟), totaltokensperturn (每轮 Token 消耗), toolcall_latency (工具调用延迟)。

质量与可靠性: toolcallsuccessrate (工具调用成功率), retrievalhitrate (检索命中率), humanhandoff_rate (人工介入率)。

业务效果: taskcompletionrate (任务完成率), usersatisfactionscore (用户满意度)。

行动项: 在你现有的监控系统（如 Datadog, Grafana, Prometheus）中建立一个专门的 Agent 监控仪表盘。

常驻监控指标:

04

结语 (Conclusion)

15-Factor Agents 框架并非一组需要全盘采纳的强制规定，而是一套经过实战检验的最佳实践集合。它将传统的软件工程纪律与大语言模型时代的独特挑战相结合，核心思想是将“信息供给”与“工程可维护性”并重。通过系统性地思考这十五个要点，您的团队将能更有信心地在 安全、透明、低成本、低延迟 的前提下，释放大型语言模型的真正商业价值，构建出不负“智能”之名的生产级应用。欢迎按需采纳、组合或二次演进，构建属于你的、真正可靠的智能体。