企業級AgentOS架構設計與工程實踐

許家譽，哈爾濱工業大學學士、碩士、博士，中科院深圳先進技術研究院博士後，控制工程高級工程師。曾在華為、騰訊等企業從事算法研發與技術管理工作，長期專註於人工智能算法、平臺系統及工程化落地。 現任華南某工業智能科技企業研發部總經理，負責企業級大模型與智能體平臺建設，主導或深度參與工業智能體平臺、企業知識庫與數據引擎、AI標註與訓練平臺、雲端推理平臺、全生命周期管理平臺等項目研發，在智能體架構設計、知識工程、模型部署優化、工業場景系統集成及團隊管理等方面具有較為豐富的實踐經驗。 在學術與技術成果方面，已發表論文15篇，擁有發明專利12項、國際發明專利1項、實用新型20余項。

目    錄

第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