目    录

第1章  从聊天助手到第一个Agent 1

1.1  企业Agent的问题起点 2

1.1.1  两张重复采购单 2

1.1.2  聊天助手、Agent和AgentOS 3

1.2  快速上手：用Python写一个小Agent 4

1.2.1  定义采购异常请求 5

1.2.2  查询库存、合同和预算 5

1.2.3  让模型生成采购建议 7

1.2.4  串起完整流程并观察输出 7

1.3  从能跑到能接业务系统 9

1.3.1  这段代码缺什么 9

1.3.2  把动作拆成可以检查的对象 10

1.4  回到MOTOR-42：怎样才算做对 11

1.5  本章小结 12

第2章  业务变更单与Pydantic对象契约 13

2.1  从自然语言建议到对象契约 14

2.1.1  自然语言写回建议的问题 14

2.1.2  Pydantic在本书中的位置 16

2.2  快速上手：将字典数据转换为业务对象 17

2.2.1  定义一个库存对象 17

2.2.2  校验输入并观察输出 18

2.2.3  看懂校验失败 19

2.2.4  导出字典和Schema 20

2.3  定义AgentOS的基础对象 21

2.3.1  证据对象EvidenceRef 21

2.3.2  采购变更负载PurchaseRequestChange 22

2.3.3  业务变更单BusinessPatch 22

2.4  校验一张MOTOR-42业务变更单 24

2.4.1  准备合法输入 24

2.4.2  校验并导出结果 25

2.4.3  校验失败后怎么办 26

2.5  JSON Schema让多方读同一张单 27

2.6  MOTOR-42写回前的对象关系 28

2.7  格式正确不等于业务正确 30

2.8  从对象契约走向状态图 31

2.9  本章小结 31

第3章  LangGraph：用状态图组织采购审批流程 32

3.1  从手写流程的问题开始 34

3.2  LangGraph的三个基本概念 35

3.2.1  State：任务流动时携带的数据 35

3.2.2  Node：每一步都是一个普通函数 36

3.2.3  Edge：把节点连成流程 36

3.3  运行一张图：invoke与stream 38

3.3.1  使用invoke查看最终状态 38

3.3.2  使用stream观察节点更新 38

3.4  把最小图扩展为MOTOR-42采购任务 39

3.4.1  PurchaseState：采购任务状态 40

3.4.2  采购流程中的几个基础节点 40

3.4.3  审批、写回和记录节点 42

3.5  条件边：让流程根据状态选择下一步 43

3.5.1  三个路由函数 43

3.5.2  组装采购状态图 44

3.5.3  运行采购图并阅读结果 46

3.6  人工审批：interrupt的基础用法 46

3.7  checkpointer：让任务可以恢复 49

3.8  失败路径和重试出口 51

3.9  接回AgentOS：LangGraph不替代业务对象 52

3.10  本章小结 53

第4章  LiteLLM：模型网关、路由、降级和成本 54

4.1  为什么不能在节点中直接写模型名 56

4.2  LiteLLM是什么：先把模型调用统一起来 57

4.3  快速上手：用SDK发起一次模型调用 58

4.4  Router入门：让多个模型有选择规则 60

4.5  Proxy入门：团队统一模型入口 62

4.6  AgentOS中的路由对象：从模型调用到任务记录 64

4.6.1  ModelProfile：给模型一张业务说明卡 64

4.6.2  RouteRequest和RouteDecision：完整记录模型路由决策 66

4.7  fallback与降级：备用模型不能偷偷替换 67

4.8  成本记录：不要等到账单来了才发现问题 69

4.9  回到MOTOR-42：证据摘要怎么路由 70

4.10  模型网关接入业务前要检查什么 72

4.11  本章小结 73

第5章  MCP/FastMCP：让Agent学会安全地使用工具 75

5.1  从一个普通工具函数开始 76

5.2  MCP的三个角色和三类能力 78

5.3  FastMCP快速上手：写一个合同Server 80

5.3.1  创建Server并暴露一个Tool 80

5.3.2  暴露Resource：给模型读取材料说明 81

5.3.3  暴露Prompt：复用合同摘要模板 82

5.3.4  启动Server 83

5.4  用Schema固定工具输入输出 83

5.5  把ToolResult转换为EvidenceRef 85

5.6  工具调试：先看工具，再接模型 86

5.7  授权、记录与工具目录 87

5.8  回到MOTOR-42：合同工具怎样进入采购异常 89

5.9  设备工单：同一套方法怎样迁移 90

5.10  安全检查和运行方式 91

5.11  本章小结 92

第6章  LlamaIndex与RAG：让资料变成可检查依据 93

6.1  RAG和LlamaIndex的基本概念 95

6.2  快速上手：用LlamaIndex做一个基础问答 96

6.2.1  第一步：把一段资料放入Document 96

6.2.2  第二步：把Document建成索引 97

6.2.3  第三步：用QueryEngine提问 97

6.2.4  第四步：读取回答使用的来源节点 98

6.3  Document、Node与metadata：证据份不能丢 99

6.3.1  给文档补齐基础metadata 99

6.3.2  Node是检索和引用的基本单位 100

6.4  把source_nodes转换为EvidenceRef 101

6.4.1  定义一个轻量的EvidenceRef 101

6.4.2  从Node生成EvidenceRef 102

6.4.3  三种常见的处理结果 103

6.5  检索链路：权限过滤、混合检索和低置信度暂停 103

6.5.1  先过滤权限，再进行检索 104

6.5.2  为什么需要混合检索 105

6.5.3  低置信度时要暂停 105

6.6  结构化数据查询：从自然语言问题到查询计划 106

6.6.1  定义MetricQueryPlan 106

6.6.2  指标目录让口径先说清楚 107

6.6.3  QueryEvidence和ReportSection 107

6.7  回到项目：设备工单和MOTOR-42采购异常 110

6.7.1  设备工单：从维修手册到工单草案 110

6.7.2  MOTOR-42：文档证据和数据证据一起使用 111

6.8  上下文预算和评测 111

6.9  本章小结 112

第7章  OPA与工具工程：策略、审批、幂等和补偿 113

7.1  为什么需要OPA：不要把策略散落在业务代码中 115

7.2  OPA/Rego快速上手：输入、规则、结果 116

7.2.1  第一步：准备策略输入 117

7.2.2  第二步：写一组入门Rego规则 118

7.2.3  第三步：查看策略输出 119

7.3  把OPA输出变成PolicyDecision 120

7.4  从策略到审批：ApprovalRequest和ApprovalGrant 122

7.5  工具契约：不要把写回工具当成普通函数 124

7.6  幂等键、错误分类和补偿任务 126

7.7  回到MOTOR-42：高风险采购写回的完整流程 130

7.8  设备工单：同一套方法也能服务其他场景 132

7.9  本章小结 133

第8章  OpenTelemetry、测试与评测：让任务看得见、查得清 134

8.1  普通日志为什么不够 136

8.2  OpenTelemetry的4个入门概念 137

8.3  快速上手：为MOTOR-42任务添加Trace 139

8.3.1  创建Tracer和顶层Span 139

8.3.2  给关键节点加子Span 139

8.3.3  记录外部调用错误 140

8.4  AgentOS中应该记录哪些字段 142

8.5  TraceSpan和AuditEvent要分开 143

8.6  Metric和运营看板：看整体健康度 145

8.7  pytest入门：先测对象关系和失败路径 146

8.8  promptfoo入门：测试模型输出和RAG引用 148

8.9  线检查：把测试、评测和Trace字段放在一起 149

8.10  MOTOR-42超时复查：把本章内容接回主线 151

8.11  攻击面和数据最小化 152

8.12  事故回灌：把真实问题变成新样本 155

8.13  本章小结 156

第9章  长任务运行时 157

9.1  问题起点：一次可能跑丢的采购任务 158

9.2  队列和Worker：先把任务放到后台 160

9.3  什么时候普通队列足够，什么时候需要Temporal 163

9.4  Temporal入门：Workflow、Activity、Worker和Client 164

9.4.1  第一步：把外部动作写成Activity 165

9.4.2  第二步：Workflow负责组织长流程 166

9.4.3  第三步：Worker注册并执行任务 166

9.4.4  第四步：Client启动Workflow 167

9.5  确定性要求、RetryPolicy与失败分类 168

9.6  审批等待、Signal与跨天恢复 170

9.7  死信、人工接管与幂等补偿 172

9.8  接入LangGraph：谁表达流程，谁保障时间跨度 175

9.9  设备工单、索引重建与多场景长任务 176

9.10  部署结构：API、Worker、Temporal和可观测性 176

9.11  成本、SLO和运行反馈 177

9.12  恢复演练、常见坑和修正方式 180

9.13  本章小结 181

第10章  把框架组合成基础AgentOS工程 183

10.1  从单个框架到组合工程 185

10.2  快速上手：用一条任务线串起对象 186

10.3  工程模块：先分清责任，再看目录 188

10.4  配置入口：把场景、工具、策略和预算写清楚 190

10.5  编排入口：用一个很薄的服务提交任务 191

10.6  数据表：先保存能说清楚的事 193

10.7  端到端验证：正常路径和失败路径一起看 194

10.8  两个场景：采购异常和设备工单怎样复用同一套工程 196

10.9  安全、多租户和版本：不要把复杂问题藏起来 196

10.10  轨迹回放、指标快照和上线检查 197

10.11  服务拆分和试点范围 199

10.12  本章小结 200

第11章  完整实战：采购异常与设备工单 201

11.1  实战章节先看什么 202

11.2  两个场景共用的对象 204

11.3  采购异常快速上手：从输入到依据 206

11.4  采购变更单：从建议到ERP写回前的对象 209

11.5  采购策略、审批和写回 210

11.6  采购失败路径：拒绝、超时、冲突和越权 214

11.7  设备工单快速上手：从告警到依据 217

11.8  设备工单：从依据到CRM工单草案 219

11.9  设备失败路径：信息缺失、旧版手册和反馈复核 221

11.10  回放、测试和接入前检查 223

11.11  把现场反馈带回系统 225

11.12  本章小结 226

第12章  从项目到企业AgentOS：能力目录、负责人和成熟度 227

12.1  问题起点：项目成功不等于平台成功 228

12.2  能力目录是什么 230

12.3  快速上手：用一个对象登记平台能力 232

12.4  能力检查：先让机器发现明显问题 233

12.5  负责人：能力出了问题要找得到人 235

12.6  自助接入：让新团队按同一张表接入 236

12.7  从项目资产沉淀成平台能力 239

12.8  运行看板和成本归因 240

12.9  成熟度模型：判断下一步应该补什么 243

12.10  平台化路线图和注意事项 245

12.11  本章小结 246