大模型越来越强，AI Agent正从"会聊天”走向"真干活”，但Demo跑通只是开始：无限循环、幻觉与静默失败、上下文溢出、工具调用失控、多Agent级联故障……都可能让智能体从"聪明”变成"不靠谱”，带来巨大损失。本书在剖析Agent框架的基础上，详细阐述Agent落地过程中最容易踩的坑，通过系统拆解执行编排、容错恢复、安全边界等Agent运行环节，结合VLM、农业机器人、CyberOps等实战案例，让读者深入理解、掌握可复用的"避坑”工程方法；将相关知识内化于心，培养AI时代的工程素养。本书既适合Agent开发者、AI应用工程师，以及后端、架构、平台和运维人员作为案头参考，也适合所有想使用Agent的读者入门学习。

吴岸城，拥有20年技术研发与团队管理经验，长期专注于人工智能、大模型、多智能体、计算机视觉及边缘计算领域。现任科技公司CTO，负责智能机器人、多智能体系统及端边云协同架构的研发与产品落地。此前曾在平安人寿、亚信科技、中兴通讯等企业负责算法、大数据及大型研发项目，具备从模型研发、系统架构到规模化交付的完整经验。他曾组建并管理9至40人的技术团队，参与1.3B—63B参数大模型训练及RM/RLHF框架研发，在知识图谱、智能对话和多模态应用方面拥有丰富实践经验。他出版过3本技术著作，拥有11项算法专利。其核心优势是兼具技术深度、产品意识与团队领导能力，能够推动前沿AI技术转化为稳定、可落地的业务产品。

第1章 Agent的“第一次”危机 1
1.1 一个真实的失败案例 1
1.2 生产环境的第一课：什么会出错 3
API调用的失败维度 3
工具调用的失败场景 3
状态管理的失败陷阱 4
1.3 Agent系统崩溃的六大模式 4
模式一：无限循环 4
模式二：上下文溢出 5
模式三：输出格式失控 5
模式四：资源耗尽 6
模式五：级联失败 6
模式六：静默失败 6
1.4 为什么Demo总是成功，而生产总是失败 7
差异一：输入的可控性 7
差异二：规模的量级 7
差异三：时间维度 7
差异四：错误的代价 8
差异五：可见性的要求 8
1.5 从失败中学习：建立正确的Agent认知 8
认知一：Agent不是魔法，是工程 8
认知二：不确定性是常态，而非异常 9
认知三：稳定性是设计出来的，不是测出来的 9
认知四：失败是最好的老师 9
认知五：建立生产环境思维要从第一天开始 9
第2章 理解Agent系统 11
2.1 什么是Agent：从“会说话”到“会做事” 11
2.2 最小闭环：Perception → Reasoning → Action → Observation 13
2.3 控制流与数据流：Agent架构的两个维度 17
2.4 单Agent系统与多Agent系统的本质区别 19
2.5 Agent的分层架构 22
2.6 统一看待主流框架的架构位置 25
2.7 Agent不是prompt：为什么必须有运行时 28
第3章 让Agent动起来：执行编排的全景图 32
3.1 从Demo到生产的死亡之谷 32
3.2 拆解的艺术：从模糊意图到可执行单元 34
三种分解范式 34
分解粒度的权衡 37
Plan-and-Execute vs ReAct 38
3.3 执行拓扑：串联、并联与有向无环图 38
Anthropic的五种工作流模式 39
LangGraph的执行语义：超越DAG 39
AutoGen的四种编排模式 40
DAG模式的工程优势 41
九大框架执行模型能力矩阵 42
3.4 调度的权衡：优先级、依赖与资源博弈 43
依赖感知调度 43
动态优先级调整 43
资源约束下的调度 44
级联路由：用便宜模型省钱 44
3.5 重试的陷阱：那些看起来简单却致命的代码 47
基本重试模式 47
五个致命陷阱 47
自我纠正的局限 49
ReliabilityBench的发现 49
3.6 优雅降级：系统断裂时的最后防线 51
多提供商故障转移链 51
四层降级策略 52
成本感知的自动降级 52
熔断器：降级的前提条件 54
3.7 熔断与限流：为失控的系统拉下电闸 55
限流：从微观到宏观 55
分层限流策略 56
雷群效应与抖动 56
批处理与prompt压缩 56
3.8 动态调度：当计划遇上现实 59
静态vs动态：核心挑战 59
运行时重规划 59
COPPER：共享反思器 61
“智能体越多死得越快” 61
Mission Keeper：防止目标漂移 61
自带重规划能力的调度器框架 62
3.9 驯服不确定性：在概率的世界里建造确定性 63
非确定性的本质 63
Temperature的实践选择 64
结构化输出：概率世界中的确定性锚点 64
5层输出解析恢复流水线 65
信心度路由：知道何时求助 66
人在回路：在不确定中寻找确定 67
多Agent投票：拜占庭容错的Agent版本 67

第4章 让任务跑到底：执行可靠性的工程实践 69
4.1 Agent失败：是编排而不是模型问题 69
从编排到稳定性的进阶之路 69
五层Agent可靠性体系 70
4.2 错误的第一性原理：并非所有错误都值得处理 71
15种Agent故障的完整图谱 71
可恢复错误vs不可恢复错误 72
Agent错误的概率性本质 73
分层错误处理框架 74
4.3 时间的边界：超时、中断与优雅恢复 76
LLM调用的时间成本 76
三种超时策略 77
取消令牌与中断传播 77
可中断Agent的设计原则 80
心跳与续约机制 80
Kubernetes中的Agent生命周期 81
4.4 不朽的状态：如何让任务从断点重生 82
最让人沮丧的失败模式 82
LangGraph的检查点系统 82
检查点设计的核心权衡 83
生产中的检查点实践 83
Eunomia：进程级检查点/恢复 84
基于检查点的断点续跑框架 84
4.5 幂等性悖论：AI Agent精确、一次性执行 88
为什么Agent幂等性这么难 89
“准幂等”的实用策略 89
分层幂等性实现 90
4.6 撤回的艺术：当Agent犯下无法撤销的错误 93
从数据库到Agent：补偿事务的迁移 93
Saga模式 94
事务性沙箱 94
Agent系统中的撤销挑战 94
设计可补偿操作的四项原则 95
Saga补偿事务框架 96
Saga补偿执行流程 99
4.7 马拉松选手：长时任务的生命周期工程 100
有状态工作空间的本质 100
上下文窗口管理：Agent的呼吸系统 101
token预算管理 102
长时任务的生命周期阶段 104
心跳、续约与优雅关停 105
经验反思学习 106
4.8 健康仪表盘：如何知道你的Agent是否真的可靠 107
可观测性工具对比 108
SLI/SLO定义建议 109
可靠性层级金字塔 109
Agent健康度检查框架 111
第5章 调试与排查实战 115
5.1 Agent调试的特殊性 115
非确定性：幽灵般的Bug 116
长时序执行：失焦的调用链 117
级联错误：雪崩效应 118
静默失败：健康的假象 119
多Agent系统的非线性复杂度 120
记忆污染：看不见的慢性毒药 121
主流框架的调试实践：一幅参差不齐的图景 121
5.2 可观测性设计三要素 124
传统可观测性为何失灵 124
三要素：追踪、指标与日志 125
追踪（Trace）：重建决策的故事 126
指标（Metrics）：量化行为的标尺 127
日志（Logs）：还原真相的细节 128
Agent可观测性的第四信号：GenAI事件 128
关键可观测维度 129
OpenTelemetry语义约定 129
框架可观测性实践：从原生到生态 131
5.3 日志追踪：还原Agent决策过程 133
追踪的核心概念：从Run到Thread 133
token级执行追踪：打开黑箱 134
决策路径的可视化重建 136
会话回放：从成功与失败中学习 137
记忆操作日志：第一类可观测性公民 139
评估分数的Span级嵌入 141
时间旅行调试：从检查点到分叉 142
实战：InnerTrace的事件溯源方案 143
5.4 故障诊断方法论 144
故障分类学：三个主流框架的对比 147
根因分析的分层策略 151
专业Agent的调试创新：从约束到隔离 153
LLM-as-a-Judge：自动化故障标注 154
红队测试与主动防御 155
从诊断到修复的验证闭环 157
多层级评估：Session/Trace/Span三级质量度量 158
从trace到test：Agent回放测试Harness 159
5.5 常见故障排查手册 160
幻觉级联 160
工具调用失败 162
上下文窗口溢出 164
无限循环与失控执行 166
多Agent通信故障 168
Prompt注入攻击 169
记忆系统故障 169
供应链安全与权限逃逸 170
故障排查速查表 172
框架选择与调试就绪度评估 173
第6章 生产级部署 175
6.1 性能优化的关键指标 175
从Demo到生产的性能鸿沟 175
推理延迟的三层度量体系 176
吞吐量与并发能力 177
可靠性：Agent能稳定跑多久 178
框架层面的性能架构对比 179
6.2 成本控制：让Agent用得起 180
token经济学的残酷现实 180
模型层优化 181
架构层优化 182
推理引擎优化 182
运营层成本治理 183
6.3 安全边界与防护 185
Agent的攻击面全景 185
Production Harness：把安全策略变成运行时强约束 186
七层纵深防护体系 186
约束性部署：生产安全的核心策略 187
框架安全机制对比 188
从红队测试到持续安全 189
6.4 合规性考量 191
全球合规图谱 191
数据治理与隐私保护 192
透明度与可解释性 193
Compliance-as-Code 2.0 194
6.5 从部署到运维的闭环 195
部署架构的五种模式 195
五层监控指标体系 197
日志、追踪与幽灵调试 199
智能告警体系 200
持续部署与灰度发布 200
从失败中学习 202
第7章 审片官的诞生——VLM闭环视频生产Agent 204
7.1 线性管道的终结 204
Prompt Drift：当视频“自由发挥” 204
审片官登场：VLM-as-a-Judge的崛起 206
从生成后检查到生成中感知 208
7.2 自反思循环——Agent如何“知错能改” 210
反思的力量 210
在视频生成中的应用 212
状态保持：不在同一个坑里跌倒两次 214
7.3 延伸思考——反思的边界在哪里 216
反思的悖论：越反思越好吗 216
从审片到更多场景 218
第8章 泥土与代码之间——农业机器人的决策图谱 220
8.1 当AI走进田间地头 220
精准农业的Agent时代 220
从识别到决策：置信度的分流艺术 223
状态机：Agent的交通信号灯 224
8.2 人机协同——在危险面前踩下刹车 227
为什么完全自主是危险的幻想 227
中断机制的设计 228
人机协同的信任构建 230
8.3 优雅降级——当传感器离线时 231
真实世界的不可靠性 231
降级策略设计 232
CrewAI的角色哲学 234
8.4 实战——AgriClaw的完整架构 236
架构全景图 236
关键节点实现 237
端到端示例：一次完整的植保任务 238
第9章 裸机上的进化论——自治环境演进与代码修复Agent 241
9.1 ACI——Agent与计算机的界面革命 241
从CLI到ACI：一次范式转移 241
SWE-agent的ACI设计解剖 243
Claude Code的工具哲学 244
OpenHands：沙箱里的全栈工程师 247
9.2 多Agent博弈——当部署者遇上监控者 249
对抗式多Agent架构 249
协同诊断：当系统OOM了 250
共识机制：谁说了算 252
9.3 动态扩展——Agent的自我进化 254
量化：Agent自主选择的降维之路 254
AutoResearch：Karpathy的自治实验框架 257
从代码修改到环境重建 258
9.4 实战——CyberOps的完整架构 260
架构全景图 260
关键节点实现 262
端到端示例：从仓库到生产 263
第10章 框架丛林与Agent的未来 267
10.1 十大框架横评 267
10.2 三条设计哲学 271
哲学一：简单胜于复杂 272
哲学二：状态机优于无限循环 272
哲学三：接口即性能 273
10.3 Agent的下一步 274
10.4 写给读者的行动建议 276