AI Agent 工程实践（19）：从 Demo 到生产环境——AI Agent 的工程 Checklist

上一篇第 18 篇《Agent 如何做 Benchmark》下一篇第 20 篇《组件都学完了为什么还是写不出企业级 Agent》发布时间2026-07-12标签AI AgentLLM生产部署工程实践Checklist本文是 [AI Agent 工程实践] 系列的第 19 篇第二季收官。Demo 跑通的那天我觉得可以上线了。Prompt 能出结果、Tool 能调通、答案看起来不错。上线第一天一个长任务跑了 30 分钟后 OOM——没有断点恢复从头重跑。一个 Tool 返回了脏数据——没有 Trace花了两小时才定位。用户投诉答案时好时坏——没有 Benchmark不知道是哪个 commit 搞坏的。我盯着屏幕想Demo 和 Production 之间差的从来不是模型好不好而是你的 Agent 有没有这些东西。Demo Agent 只需要跑通一次Production Agent 需要跑对每一次。这中间差的就是这份 Checklist。本文你将学到✓ 一个真正能上线的 Agent必须覆盖的十个维度✓ 每个维度对应的通过标准——不是做了就行是做到什么程度才算✓ 一份可直接打印的生产就绪度自检表✓ 第二季 10-18 篇的完整回链——每个维度对应哪篇详解适合阅读✓ Demo 跑通了、准备上生产的人✓ Agent 上线后问题不断、不知道哪里还缺的人✓ 想把 Agent 当作产品而非玩具交付的人问题背景99% 的 Agent 教程在教你怎么做一个 Demo——写 Prompt、调 Function Call、连一个 Tool。Demo 跑通了教程结束了。但 Demo 和 Production 之间的鸿沟没人告诉你。我把踩过的生产事故总结成了十件事缺任何一件上线的 Agent 都会在某天出问题。这十件事不是最佳实践建议——是我炸过的十个坑每一个都有对应的系列文章讲清楚为什么炸、怎么修。这篇是把它们压缩成一张表上线前逐条检查全过才算生产就绪。关键观察Demo Agent 和 Production Agent 的区别用一张表对齐维度Demo AgentProduction Agent跑通手动跑通一次每次改动后自动 Benchmark 回归出错重试 or 放弃State 断点恢复 Retry 兜底调试看终端输出Trace 串联全链路升级靠感觉好像变好了Benchmark 量化对比安全不考虑Tool 审批 数据脱敏Demo Agent 只需要跑通一次Production Agent 需要跑对每一次。能跑通不等于能上线——中间差的就是这份 Checklist。最终方案Agent 生产就绪十大 Checklist十维总览逐项详解1. Rules · 行为底线问题Agent 的行为不受约束想做什么做什么。通过标准core/常驻规则 ≤ 5 条超过就是噪声参见 01 篇heavy/能力文件按任务类型触发不是全开参见 05 篇每条规则有明确的触发条件Trigger没有永远加载的无效规则对应文章[01] Rules 分层 / [05] Rule Router2. Review · 复盘闭环问题出了问题不沉淀同一个坑反复踩。通过标准有 Daily Review 机制记录当天被手动修正的输出参见 04 篇有 Weekly Review 机制同类问题 ≥2 次 → 沉淀为规则参见 06 篇复盘结果能回流到 Knowledge 或 Rules 层不是记了就完了对应文章[04] Review 复盘 / [06] Knowledge→Rules3. Memory · 记忆系统问题Agent 没有长期记忆每次都从头教。通过标准区分了 Conversation / Working / Long / Archive 四层参见 03/10 篇长期记忆有 Promition 机制复用 ≥2 次或用户明确要求才晋升有清理机制过期/冷数据/冲突自动降级或删除参见 15 篇对应文章[03] Memory 设计 / [10] Memory 架构 / [15] RAG 知识治理4. Security · 安全治理问题Agent 可能执行危险操作或泄漏用户数据。通过标准高危 ToolShell/DB Write有审批机制参见 13 篇传给 LLM 的数据经过脱敏PII / 密钥过滤Tool 的输入有 Schema 校验类型/范围/正则约束有 Rate Limit 和 Token 预算上限对应文章[13] Tool Calling5. Workflow · 编排能力问题多步任务没有编排Agent 丢步骤或上下文爆炸。通过标准复杂任务有 Planner → Execute → Review 链路参见 11 篇有回退机制Review 不通过 → 回到 Execute 或 Planner状态在节点间传递不是靠 prompt 拼接参见 16 篇没有不必要的 Multi-Agent步骤多 ≠ 该拆 Agent参见 08/12 篇对应文章[08] Multi-Agent 决策 / [11] Workflow 实现 / [12] Multi-Agent 失败 / [16] State6. Retry · 容错恢复问题Agent 一步出错就全盘垮掉。通过标准Tool 调用有分类重试Schema 错修参数 / 超时退避 / 工具不存在换工具参见 13 篇Agent 有断点恢复能力挂了从 checkpoint 续跑参见 16 篇重试有上限不是无限重试超限后降级或人工介入有 Waiting 状态不等外部事件时不阻塞参见 16 篇对应文章[13] Tool Calling / [16] State7. Trace · 调用链问题出了错不知道哪个环节的问题。通过标准每次 Agent 运行有唯一的 Trace ID不是零散日志 ID每个 LLM 调用 / Tool 调用 / 状态转换都是一个 Span参见 17 篇Span 记录了 input/output tokens、latency、是否成功能从 Trace 还原完整决策链为什么得出这个结论参见 17 篇 Audit对应文章[17] Observability8. Metrics · 指标问题不知道 Agent 整体健康度。通过标准有成功率Success Rate——不是靠感觉有成本Token 消耗 × 单价——知道花了多少钱有延迟 P50/P95/P99——知道多快有 Tool 调用次数——知道效率指标有 Dashboard不是翻日志找是一眼看对应文章[17] Observability / [18] Benchmark9. Benchmark · 回归评测问题改了一行 Prompt不知道是变好还是变坏。通过标准有标准任务集不是顺手跑几个 case参见 18 篇每次 commit 自动跑 BenchmarkCI/CD不是手动跑有四维评分Success Rate Cost Time Tool Calls和历史 baseline 对比——退化自动阻止合并对应文章[18] Benchmark10. Logging · 审计与合规问题出了安全事故无法追溯。通过标准有结构化日志JSON不是 print 字符串每条日志含 Trace ID 时间戳 用户 ID 操作类型日志有保留策略不是永远不删也不是随便删敏感数据不写入日志PII、密钥脱敏后再记录完整生产就绪度自检表#检查项通过对应篇1Rulescore ≤ 5 条heavy 按触发条件加载☐01/052Review有日/周复盘复盘结果回流到 Rules☐04/063Memory四层分层 Promotion 清理机制☐03/10/154Security高危 Tool 审批 数据脱敏 Schema 校验☐135WorkflowPlanner→Execute→Review 回退机制☐08/11/12/166RetryTool 分类重试 Agent 断点恢复☐13/167TraceTrace ID 串联 完整 Span Audit Trail☐178Metrics四维指标 Dashboard☐17/189Benchmark标准任务集 CI 回归 四维评分☐1810Logging结构化 Trace ID 审计保留☐—十个全过Agent 才不是 Demo。缺一个生产环境会在某一天替你做 checklist——用事故的方式。代码或配置示例生产就绪度自检脚本def production_readiness_check(agent) - dict: 上线前自检——十个维度逐一检查 checklist { rules: check_rules_layer(agent), # core ≤ 5, heavy 有 trigger review: check_review_loop(agent), # 日/周复盘存在 memory: check_memory_layers(agent), # 四层分层 promotion security: check_security(agent), # 审批 脱敏 schema workflow: check_workflow(agent), # P→E→R 回退 retry: check_retry(agent), # Tool 分类重试 checkpoint trace: check_tracing(agent), # Trace ID Span metrics: check_metrics(agent), # 四维指标 Dashboard benchmark: check_benchmark(agent), # 任务集 CI 回归 logging: check_logging(agent), # 结构化 审计 } passed sum(checklist.values()) return { total: len(checklist), passed: passed, ready: passed len(checklist), # 全过才是生产就绪 details: checklist, }跑一遍这个脚本比感觉可以上线了可靠一万倍。总结✅ Demo Agent 只需要跑通一次Production Agent 需要跑对每一次。✅ 十个维度的生产就绪标准Rules / Review / Memory / Security / Workflow / Retry / Trace / Metrics / Benchmark / Logging。✅ 每个维度不是做了就行是做到什么程度才通过——Checklist 给出了明确的通过标准。✅ 十个全过Agent 才不是一个 Demo。缺一个生产环境会用事故来提醒你。第二季回链第二季 · 工程实现10-19把第一季的架构决策落地为可运行的工程系统篇主题对应清单项10Memory 架构实现Memory11Workflow 实现Workflow12Multi-Agent 失败分析Workflow13Tool CallingSecurity / Retry14MCP 协议—基础设施15RAG 知识治理Memory16State 状态管理Workflow / Retry17Observability 可观测性Trace / Metrics18Benchmark 评测Metrics / Benchmark19生产 Checklist本篇全部本文是 [AI Agent 工程实践] 系列的第 19 篇第二季收官。系列导航上一篇第 18 篇《Agent 如何做 Benchmark》下一篇第 20 篇《组件都学完了为什么还是写不出企业级 Agent》