DOCUNI-解體-004
REV2026.04
SUBJECTAGENTS · GENERAL
VOLUMEIV
SCOPEVENDOR-NEUTRAL
Kaitai Shinsho · Volume IV · the abstraction

通用 · AI Agent · 解體新書

a ten-chapter dissection of agents in general · vendor-agnostic principles
DEFINITION LOOP TOOLS MEMORY PLANNING REFLECTION MULTI-AGENT GUARDRAILS EVAL OPS
SURGEONCLAUDE
DRAFTED2026.04.08
FORMATSCROLL-HTML
BASISFIELD STATE
CHAPTERS10 + 序

前三卷各拆了一具具體的東西 — Claude Code(CLI)、Agent SDK(函式庫)、Claude API(協定)。三具都姓 Anthropic。本卷的對象不是任何一具,而是 「代理人」這個物種本身。它存在於所有廠商的所有實作之上:Claude / GPT / Gemini / Llama / Grok / 你自己訓練的小模型 — 只要有 LLM、有迴圈、有工具,就有 agent,就適用同一套原理。

本卷不討論「呼叫哪個函式」、不討論「設哪個欄位」。它討論的是:迴圈為什麼是迴圈、記憶為什麼分四層、計畫為什麼有反應式與審慎式之分、多 agent 為什麼常常做了反而更糟、評估為什麼比寫代碼更難。這些問題你選哪家廠商都會遇到,答案也大多通用。

十回章節由內而外:先定義 agent、拆認知迴圈,再講工具、記憶、計畫、反思這四個內部能力,接著放大到群體與護欄,最後落到評估與部署的工程現實。把這層打通,前三卷的選型就會從「死記名字」進化成「依原理推導」。

I.

何謂代理人

What is an agent · drawing the line
FIG · 01
DEFINITION

「Agent」這個詞被用得太鬆 — 任何用了 LLM 的東西都自稱 agent。本章先把線畫清楚:純 LLM 不是 agent、RAG 不是 agent、scripted workflow 不是 agent、chatbot 不是 agent。Agent 的最小定義 = LLM + 自主迴圈 + 工具。三樣缺一不可。其餘只是 LLM 的應用。

FOUR THINGS COMMONLY CALLED "AGENT" · 三非一是 A · NOT AN AGENT 純 LLM "a thinking parrot" 輸入 → 輸出 一次推理結束 無記憶 · 無動作 無外部觸及 寫詩、改文法、翻譯 純 chat 介面(如 ChatGPT 最簡用法) B · NOT AN AGENT RAG 系統 "a parrot with a library" 查 → 檢索 → 回答 固定的單向流程 沒有迭代決策 不挑工具、不規劃 企業知識庫問答 客服 FAQ bot 文件搜尋助手 C · NOT AN AGENT 腳本流程 "a parrot in a maze" 開發者預定的步驟序列 LLM 只填某幾格 下一步由程式決定 非 LLM 自選 LangChain 的 Chain、 n8n / Zapier 的 LLM 節點、 固定 prompt pipeline D · ✓ AGENT 真正的代理人 "a parrot that flies" LLM 自主決定下一步 迭代多個 turn 挑工具、看結果、再決定 直到完成或放棄 Claude Code、Cursor 自動模式 SWE-agent、Devin AutoGPT 類自主工具 MINIMUM VIABLE AGENT · 最小可行代理人 LLM decision-making substrate 「會推理的腦」 + 迴圈 iterative control flow 「會繼續的軀體」 + 工具 action interface to the world 「會出手的肢」 = 代理人 an agent three components 「缺一不可」 ⚠ 為何這個區別重要 · 三非一是的混淆是當代 AI 行銷最常見的誤導 — 「我們的 AI agent 解決方案」常常其實是 RAG 或腳本流程 · 真 agent 的成本、不確定性、失敗模式跟前三者完全不同 — 用 agent 心態設計腳本流程是過度工程 · 用腳本流程心態設計 agent(試圖窮舉所有路徑)是失去 LLM 自主性的全部優勢 · 先看清楚你要做的是哪一種,再決定用哪個層級的工具 — 這就是這套書四卷的存在理由
純 LLM適用:一次性轉換任務(翻譯、摘要、改寫)。優點:簡單便宜可預測。缺點:不能做需要多步、需要工具的事。
RAG適用:知識問答、文件查找。優點:把外部知識「灌」進模型。缺點:流程固定,無法處理需要動作的任務。
腳本流程適用:可預測的流水線(如「分類 → 抽取 → 驗證 → 寫入」)。優點:開發者完全掌控路徑。缺點:無法應付未預期的分支。
真正的 agent適用:開放性任務(修 bug、寫程式、查資料、執行多步操作)。優點:能處理未預期分支。缺點:成本高、不可預測、難測。
判斷準則問三個問題 — 它會自己決定下一步做什麼嗎?它會用工具嗎?它會迭代直到結束嗎?三個都 yes 才是 agent。
本卷其餘九回都是在拆「真正的 agent」這一格 — 它的迴圈結構、它的工具介面、它的記憶、它的計畫、它的自我修正、它的群體行為、它的安全與評估。
II.

認知迴圈

The cognitive loop · perceive → reason → act → observe
FIG · 02
UNIVERSAL LOOP

所有 agent 的內核都是同一個四站迴圈。它早於 LLM — 1980 年代的 BDI 認知架構、1990 年代的 robotics 控制理論、2000 年代的 reinforcement learning,全都用同一個框架:感知(perceive)→ 推理(reason)→ 行動(act)→ 觀察(observe)。LLM agent 只是把「推理」這一站換成了 next-token prediction,其他三站的位置不變。看懂這一個迴圈,你就看懂了所有 agent 框架。

THE FOUR-STATION LOOP · 四站環 COGNITIVE LOOP 迴圈核心 ① PERCEIVE 感知 read inputs · context user msg + tool results ② REASON 推理 LLM forward pass next-token prediction ③ ACT 行動 emit tool call or final answer ④ OBSERVE 觀察 execute tool collect result if final answer DONE · 終結 「Thought → Action → Observation → Thought → … 」 — 這是 ReAct (Yao et al. 2022) 的標準軌跡 UNIVERSAL · NOT LLM-SPECIFIC
① 感知(Perceive)把當前 context(system prompt、歷史、最新工具結果)讀進來。LLM 一次只看 context window 內的東西 — 越界的就消失了。
② 推理(Reason)LLM 一次 forward pass 產生下一步。可能是文字、可能是 tool call、可能是 thinking 區段。這是迴圈裡唯一花錢的地方。
③ 行動(Act)把 LLM 的決定轉成實際動作:呼叫 API、寫檔、發訊息、查資料。或者輸出最終答案結束迴圈。
④ 觀察(Observe)把行動的結果(成功值、錯誤、副作用)格式化後注回 context。下一輪 perceive 時就會看見。
終止條件三種:模型輸出最終答案(end_turn)、超過 max iterations、外部中止訊號。沒有終止條件 = infinite loop = 燒錢。
歷史源流BDI agent (Bratman 1987)、Robotics sense-plan-act 三段、RL 的 observe-act-reward — 都是同一個迴圈的變形。LLM 只是把 reasoning 外包給了預訓練模型。
III.

工具之介面

Tool interface · function calling across vendors
FIG · 03
SCHEMAS

所有現代 LLM 都用同一套抽象 — function calling:開發者宣告函式(name、description、input schema),模型在輸出中產生 {name, arguments} 物件。差別只在 wire format。本章把 OpenAI、Anthropic、Gemini 三家的格式並排,讓你一眼看出它們其實只是同一個概念的三種編碼。

UNIVERSAL SHAPE · 三家共通的概念 每個工具都是這四件事 ① name — 唯一識別字串(snake_case 慣例) ② description — 自然語言說明,模型靠這句決定何時用 ③ input schema (JSON Schema) ④ handler — 由你提供的執行函式 OPENAI tools[] { "type": "function", "function": { "name": "get_weather", "description": "...", "parameters": { "type":"object", "properties":{...} } }} ANTHROPIC tools[] { "name": "get_weather", "description": "...", "input_schema": { "type":"object", "properties":{...}, "required":[...] } } // 比較扁平 GEMINI function_declarations { "name": "get_weather", "description": "...", "parameters": { "type":"OBJECT", "properties":{...} } } // type 用大寫 // 子集 OpenAPI subset THE DANCE · 模型與工具的對話節奏 LLM "我想用 get_weather" 產生 tool_call 區塊 {"name", "input"} framework parse, validate route to handler execute your code def get_weather(city): return "..." LLM (next turn) 看見 tool_result "25°C, sunny" 繼續推理 ⚠ DESCRIPTION 的重量 模型決定「該不該用這個工具」「該怎麼填參數」完全靠 description 與參數的 description 一句模糊的描述會讓模型亂猜或乾脆不用 — agent 的失敗有過半比例其實是「工具描述沒寫清楚」。 把描述當成寫給未來同事的 docstring 寫,多花時間在這裡的回報遠大於 prompt 工程
三家差別其實微小都是「name + description + JSON Schema」。OpenAI 多包了一層 function、Gemini 把 type 寫成大寫並用 OpenAPI 子集 — 但概念完全相同。
JSON Schema 是公分母三家都用 JSON Schema 描述參數。學一次到處用。重點:type · properties · required · enum · description
tool_choice 控制三家都有「auto / required / specific」三種模式 — 讓模型自選、強制使用任意一個、強制使用某個特定工具。
parallel calls現代模型(GPT-4o、Claude 4、Gemini 2)都支援「一次回應多個 tool_call」。框架要平行執行並把結果一起回送。
structured output是 tool use 的近親 — 用「強制呼叫一個工具,input_schema 就是你要的輸出形狀」這個技巧,可逼模型輸出嚴格 JSON。
抽象層級往上爬LangChain / Vercel AI SDK / LiteLLM 等框架在三家之上又包了一層「Tool」抽象 — 讓你寫一次跑三家。但底層原理都是 function calling。
IV.

記憶四界

Four realms of memory · cognitive science meets agents
FIG · 04
MEMORY MATRIX

認知心理學自 Tulving 1972 之後把記憶分成四類:working、episodic、semantic、procedural。出乎意料地,這個分類在 LLM agent 上完全成立 — 對應 context window、過去 session、知識庫、工具/skill。本章把這個四象限攤開:每一界活在哪、怎麼讀、怎麼寫、會不會失效。看清楚你需要哪幾界,避免把東西塞錯地方。

FOUR REALMS · 兩軸四象限 EXPLICIT · 可言述 IMPLICIT · 內隱 SHORT-TERM LONG-TERM ① WORKING MEMORY 工作記憶 "the scratchpad" 活在哪: context window 內的 token 寫入: 每一輪 turn 都自動發生 讀取: 下一次 LLM 推理時自動讀 容量: ~200K tokens(依模型) 失效: session 結束或被壓縮 例:當前對話、剛剛的工具結果、 todo list 「最快、最即時、最貴的記憶」 ② EPISODIC MEMORY 情節記憶 "the diary" 活在哪: 資料庫 / 檔案 / 向量索引 寫入: session 結束時 dump 或定期摘要 讀取: 語意檢索 / 時間查詢,注入 context 容量: 幾乎無限(看你預算) 失效: 資料舊到不再相關 / 你刪掉它 例:上週的對話摘要、使用者偏好、 過往決策 「跨 session 的個人化記憶」 ③ PROCEDURAL MEMORY 程序記憶 "the muscle memory" 活在哪: tool registry、skill 檔案、subagent 定義 寫入: 開發者宣告(罕見:自我學習) 讀取: 每次 session 啟動時注入 容量: 中(受限於 system prompt 預算) 失效: 幾乎不會 — 跟著 agent 走 例:可用工具清單、SKILL.md、 hook handlers 「會做什麼,而不是知道什麼」 ④ SEMANTIC MEMORY 語意記憶 "the encyclopedia" 活在哪: 向量資料庫、知識圖譜、文件庫 寫入: 建構期 / 定期重建索引 讀取: RAG — 嵌入查詢 → 相似度檢索 容量: 無限 失效: 資料過期 — 需重新爬與重新嵌入 例:產品文件、API 規範、產業知識 「客觀事實的儲存庫」 「想清楚你要存的是『此刻的工作』『過去發生過的事』『會做的動作』還是『客觀知識』 — 就會知道該放哪一界。」
常見錯誤 · 把東西塞錯界

把使用者偏好(episodic)塞進 system prompt(procedural)→ 每次都讀,浪費 token;把產品文件(semantic)全塞進 context(working)→ context 爆且查不準;把 skill 描述(procedural)放到 vector DB(semantic)→ 模型查不到也用不到。放錯地方比沒記憶更糟

讀寫策略 · 不對稱

四界的「寫入頻率 vs 讀取頻率」差很大。working:寫多讀多;episodic:寫少讀少(但重要時刻要讀);procedural:寫極少讀極多;semantic:寫批次讀按需。設計記憶系統時先畫出「誰會寫、誰會讀、何時」的矩陣再開工。

V.

計畫之術

Planning · reactive ↔ deliberative spectrum
FIG · 05
PLAN SPECTRUM

Agent 要不要先擬一份計畫?這個問題沒有單一答案 — 它是一條光譜:左端是純反應式(每步現想),右端是純審慎式(先寫完整計畫再執行)。實務上多數成功 agent 落在中間:plan-and-execute(先擬中間粒度的計畫,執行時可修訂)。本章拆光譜兩端與中間幾種典型模式。

PLANNING SPECTRUM · 從反應到審慎 REACTIVE step-by-step, no plan DELIBERATIVE full plan upfront 純 ReAct 輕計畫 Plan-and-Execute 最常見 階層分解 A · REACTIVE 純反應式 每一 turn 看當前狀態 → 決定下一步 不預想未來 優:彈性、簡單 缺:可能繞遠路 適合:探索型 · 不確定路徑 B · LIGHT PLANNING 輕計畫 心算「接下來要做幾步」 每步邊做邊想 無正式計畫物件 優:低開銷 缺:難審查 適合:日常多步任務 C · PLAN & EXECUTE 計畫後執行 先寫一份明確的步驟列表 執行中允許修訂 完成後對照計畫核對 優:可審查、可恢復 缺:起步較慢 適合:重要或長任務 · 預設選擇 D · HIERARCHICAL 階層分解 高層 agent 出宏觀計畫 每節派 subagent 分解 層層遞迴 優:可處理巨型任務 缺:協調複雜、易脫節 適合:研究 / 大型 refactor PLAN-AND-EXECUTE 細節 · 為何是預設選擇 ① 接收任務 user → agent ② 擬計畫 "plan: [step1, step2, ...]" ③ 執行第 N 步 tool calls / observe ④ 對照計畫 完成?修訂? ⑤ 完成 回報結果 未完成 → 下一步 · 必要時修訂計畫 「計畫不是契約 — 是地圖。發現走錯路時要改地圖,不是死撐到底。」
Plan 物件本身就是 working memory計畫不是另外存的東西 — 它就是 context 裡的一段文字(或結構化 todo list)。把它顯式列出來反而幫助模型保持方向。
修訂的時機每完成一步問:(a) 計畫對嗎? (b) 上一步成功嗎? (c) 有無新資訊要納入?三個都 yes 才繼續,否則 replan。
用 todo 工具強化給 agent 一個 TaskCreate / TaskUpdate 工具讓它寫 todo — 把計畫物件化、可追蹤。Claude Code 的 TaskCreate 即此模式。
Plan 模式(Claude Code)是極端 plan-and-execute 的一個版本:擬完計畫先問人類,獲准後才執行。風險高的任務適用。
避免過度計畫把每一個 detail 都寫進計畫 = 退化成腳本流程,失去 agent 自主性。計畫應在 5-10 個高層步驟之間。
階層分解的代價分得越深,subagent 越難協調且 context 連貫性越差。實務上 2 層(主 + 子)通常已足夠 — 3 層以上常常得不償失。
VI.

反思之鏡

Reflection · self-critique & the Reflexion pattern
FIG · 06
FEEDBACK LOOP

LLM 的第一答常常是錯的、第二答常常更好。這個觀察催生了一整套「自我修正」模式 — 從最簡的 self-critique 到 Reflexion (Shinn et al. 2023) 的記憶式反思、到外部 verifier 的客觀檢查。本章拆四種反思結構與它們各自的適用情境。反思不是萬靈丹:用對地方加分、用錯地方只是燒 token 走原路。

FOUR REFLECTION PATTERNS · 四種自我修正 A · SELF-CRITIQUE 自我批判 產出 批判 修訂 同一個 LLM 三段式 prompt 優:簡單,無需新工具 缺:模型對自己的盲點仍然盲 B · REFLEXION (Shinn et al. 2023) 反思迭代 嘗試 評估 反思 再嘗試 把「為何失敗」寫進記憶 → 下一輪帶著教訓重來 優:跨 trial 學習 適合:有明確 success signal 的任務 C · EXTERNAL VERIFIER 外部驗證者 產出 客觀檢查器 tests · linter · type 非 LLM 的客觀標準(編譯器、單元測試、 schema 驗證) 最強的反思:因為「對錯」不是模型自己說了算 適合:有黃金標準的任務(程式、JSON 抽取、SQL) D · SELF-CONSISTENCY · 多採樣投票 自我一致性 try 1 try 2 try 3 投票 majority answer 獨立採樣 N 次相同 prompt → 以多數決定答案 適合:有明確答案的任務(數學、選擇題) · 不適合開放生成 CHOOSING THE RIGHT REFLECTION · 對症下藥 寫程式 / 寫 SQL / 結構化抽取 → External verifier(編譯器、tests、schema)— 黃金路徑 數學、邏輯題 → Self-consistency 多採樣投票 — 簡單有效 長型推理任務 → Reflexion — 失敗時把教訓寫入記憶,下一輪帶著走 寫作 / 設計 / 開放任務 → Self-critique — 同模型 critic 是「沒檢查器時的最後手段」 ⚠ 反共識:不要對「事實性錯誤」用 self-critique — 模型不知道自己錯,反思只會原地打轉 「反思的真正力量來自 verifier — 不是模型自我懷疑。」
Self-critique 的天花板同一個 LLM 既當作家又當編輯,它不會看見它本來就看不見的問題。對「模型已經 confident 但其實錯」的情境完全無效。
Reflexion 三件事(1) 嘗試 (2) 評分 (3) 把失敗原因寫入長期記憶 — 下一輪帶著「上次失敗是因為 X」的字串重新開始。論文證實對某些 task 顯著提升。
External verifier 的範例Code 任務跑單元測試 / lint;JSON 任務 schema 驗證;SQL 任務先 EXPLAIN 再 EXEC;數學任務代回原式驗證。任何「能客觀判對錯」的東西都算。
Self-consistency 的成本跑 N 次,成本約 N 倍。但對某些任務 N=5 就比單次跑 +20% 準確率 — 算下來划算。
反思的負作用有時模型在 critique 階段會把對的答案改錯(過度修正)。設計時要保留「不修」的選項,並只在 verifier 明確指出問題時才動手。
Process vs Outcome reward進階:用 PRM(Process Reward Model)對中間推理步驟逐步打分,比只看最終結果更精準。OpenAI 的 o1 系列訓練即此路徑的延伸。
VII.

群體智慧

Multi-agent · topologies, protocols, & when NOT to
FIG · 07
TOPOLOGIES

多 agent 系統聽起來很性感 — 多個 specialist 彼此協作就像團隊 — 但實踐上最常見的結局是:成本爆炸、context 不同步、決策推卸責任、整體比單一 agent 更糟。本章畫三種主流拓撲,並更重要地:列出 「不該用 multi-agent 的紅燈情境」

THREE TOPOLOGIES · 三種拓撲 A · HUB & SPOKE 中心輻射 "the conductor" agent spec1 spec2 spec3 spec4 主 agent 派任務 → 收結果 → 整合 每個 specialist 只管自己的事 最常用 · 最易控 · 預設選擇 例:Claude Code 的 Agent tool B · HIERARCHICAL 階層樹 "the org chart" CEO mgr 1 mgr 2 w1 w2 w3 w4 高層分配給中層,中層再分 適合大型專案分解 2 層即可 · 3 層以上易脫節 C · PEER-TO-PEER 對等網路 "the parliament" A B C D E 無中心,agents 互相對話 最酷 · 最難控 · 最常翻車 ⚠ WHEN NOT TO MULTI-AGENT · 五個紅燈 ① 任務本質是序列的 若每一步都依賴前一步的輸出,多 agent 並行毫無意義 — 強制串列只是浪費協調成本 ② 子任務需要共享 context 才能正確 每個 subagent 看不見彼此的對話,但任務需要全局理解 → 整合時資訊不一致、結論互相矛盾 ③ 「整合層」比子任務還難 主 agent 把 N 個子結果合成最終答案,這個合成往往本身就是最難的部分。多 agent 把難題搬家但沒解決 ④ 成本不對稱 multi-agent 通常要 5-10× 單 agent 的 token 成本。除非任務本來就要花 30 分鐘,否則延遲改善 / 品質改善都抵不過 ⑤ 你只是想避免寫 prompt 把 prompt 拆給 5 個 agent ≠ 讓 5 個 agent 各自思考。常常單一 agent 配好 prompt + tools 就解決了 「先試單 agent。真的不行,再 hub-and-spoke。最後才考慮 hierarchical。peer-to-peer 等到你有大量資源再玩。」
parallel ≠ multi-agent · 區分概念

單一 agent 可以同時派出多個工具呼叫(parallel tool use)— 這已經能拿到「並行」的好處,不需要 multi-agent 架構。Multi-agent 的「不同 system prompt / 不同 context」才是它真正的差別 — 但大多數任務不需要這個差別。

協調協議 · communication

multi-agent 的對話需要協議 — 純自然語言會發散且不可解析。實務上採用「結構化訊息」(JSON / 函式呼叫式)配合「明確的角色 prompt」。Anthropic 的「research 多 agent」與 Microsoft 的 AutoGen / Magentic 都用此模式。

VIII.

護衛之圍

Guardrails · defense in depth
FIG · 08
FIVE LAYERS

Agent 會自主行動 — 這是它的力量也是它的危險。靠單一防線(例如「我寫了個好 system prompt」)不夠 — 任何單層防禦都會被繞過。安全的 agent 系統用縱深防禦:五層由內而外的護欄,每一層都假設前一層已被攻破。本章畫這五層的邊界與職責。

FIVE LAYERS · 由內而外的五層防禦 ⑤ KILL SWITCH 緊急熄火 ④ HUMAN-IN-THE-LOOP 人類決定關鍵步 ③ SANDBOX 沙箱隔離 ② PERMISSIONS 權限策略 ① PROMPT 提示工程 "don't do X" AGENT 代理人 LAYER DETAILS · 各層職責 ① Prompt 最弱也最易繞過。寫好但不可信。 「請勿執行 rm -rf」— 模型可能照做 ② Permissions(程式級) 在工具呼叫前檢查 allow/deny 清單 用 callback 客製複雜邏輯 第一道「不可被 prompt 繞過」的牆 ③ Sandbox(系統級) 執行 agent 的程序限制能存取的 檔案、網路、shell — 即使 agent 想做也做不到 ④ Human-in-the-loop 高風險操作必須人類按 yes 才繼續 「ask」模式 / Claude Code 的 permission prompt 即此層 ⑤ Kill Switch(最後防線) 若前四層都失效 — 給人類一個能 瞬間殺掉整個 process 的方法 時間 / 預算 / iteration 上限 DEFENSE-IN-DEPTH 公理 每一層都假設前一層失效 沒有任何單層是可靠的 「定義一個會自動中止的條件」 「Agent 有多自主,護欄就要有多多層 — 自由與紀律是孿生子。」
① Prompt 層的真相「我跟模型說別做 X」是最便宜的防線,但 prompt injection / jailbreak / hallucinated tool name 都能繞過。寫,但別信。
② Permissions 層程式級的工具白名單/黑名單。Claude Code 的 settings.json、Agent SDK 的 canUseTool callback 都屬此層 — 由代碼判定,不靠模型自律。
③ Sandbox 層OS / 容器級的隔離 — Docker、firejail、macOS Seatbelt、SELinux、unprivileged user。即使代碼有 bug 讓 agent 跑了不該跑的命令,sandbox 還能擋住影響範圍。
④ Human-in-the-loop 層把高風險動作(部署、刪檔、付款、發訊息)強制設為 ask 模式。人類在這層是裁判,不是阻力 — 設計上應該讓 yes/no 決定 1 秒內可做。
⑤ Kill switch 層iteration 上限(max_turns)、token 預算上限、時間上限、外部 watchdog。永遠假設前面四層都會出錯,這層是最後的物理停止鍵。
常被忽略監控與審計 — 每一層的決策都應該被記錄,方便事後 forensic 分析。沒有日誌的安全等於沒有安全。
IX.

試煉之地

Evaluation · the testing pyramid for agents
FIG · 09
EVAL PYRAMID

「你怎麼知道你的 agent 變好了?」這是 agent 工程裡最難回答的問題。傳統軟體可以靠單元測試 — agent 的非確定性讓單元測試只能驗證「沒崩潰」而非「答對了」。本章畫出 agent 評估的五層金字塔:從便宜快速但表淺的單元測試,到昂貴慢但有信度的人類審查。

EVALUATION PYRAMID · 由廣到精的五層 ⑤ HUMAN 人類審查 最貴最慢但最有信度 · 最終裁判 ④ EVAL SET 手動評估集 10-100 個精選案例 · 每月跑一次 ③ END-TO-END 端對端 完整任務跑完看結果 ② INTEGRATION 整合測試 幾步串起來測 ① UNIT 單元測試 每次 commit 跑 LAYER DETAILS · 各層對應檢驗的對象 ① 單元測試 驗證 tool handler、prompt template、message parser 等代碼塊。 確定性、毫秒級、每次 push 跑。但只能驗證「沒爆炸」,不能驗證「答對」。 ② 整合測試 驗證「LLM + 一兩個工具」的小組合。常用 mock LLM 或固定 seed 取得確定性。 捕捉 schema 不對、tool 串接錯誤、context 組裝 bug。 ③ End-to-End 真實 LLM、真實工具、真實任務 — 但用「半固定 input + 程式化檢查 output」。 如「修這個 bug 後跑這套測試應該全綠」 — 客觀的成功訊號是金本位。 ④ Eval set 10-100 個代表性任務的精心策展集。每月或每改大型 prompt 跑一次。 用 LLM-as-judge 或正規表達式檢查;維護一張歷史趨勢圖。 ⑤ Human review 真人讀 trace、判斷品質、發現 LLM-as-judge 抓不到的細微失敗。 最貴 — 每週幾十個樣本。但這層的判斷常常是其他層的真理基準。 參考 benchmark:SWE-bench(軟體 bug 修復)· GAIA(綜合任務)· AgentBench · WebArena · TauBench PUBLIC EVAL SUITES
LLM-as-judge 陷阱 · 自我評分

用 LLM 評另一個 LLM 的輸出很方便 — 但 judge 模型有偏見:偏好較長答案、偏好較複雜措辭、偏好它自己會寫的風格。當你要證明「新版比舊版好」時,至少做雙盲(隨機交換 A/B 順序)並用人類抽樣校準 judge 的判斷。

regression 監控 · 防退化

agent 的可怕之處:改 prompt 改一個字、換模型版本、加一個 hook — 都可能讓某些任務從通過變失敗。你需要 固定的 eval set + 自動回歸跑分,每次發版前對照歷史曲線。沒這個,就是憑感覺發版。

X.

部署實戰

Deployment · observability, cost, latency, ops
FIG · 10
OPS STACK

原型 agent 跑通是一回事,把它送上生產又是另一回事。Agent 的 ops 跟一般 web 服務有共通之處(監控、scaling、deploy),但也有自己的怪癖(單次請求可能跑 5 分鐘、成本不可預測、失敗可能是「答得不好」而非「拋例外」)。本章列出生產 agent 必備的五大 ops 能力。

FIVE OPS CAPABILITIES · 生產 agent 五大能力 ① OBSERVABILITY · 觀測性 每一 turn 都能回放 · 完整 message trace(含 system prompt、tool calls) · token usage、cost、latency 每 turn 細到單一 LLM call · 階層式 span(agent → tool → http → db) · session id 串起整個對話 工具參考:LangSmith · Langfuse · Helicone · OpenTelemetry GenAI ② COST CONTROL · 成本紀律 不讓單次請求燒光預算 · max_turns 上限(防 infinite loop) · 每 session token 預算 + 命中時中止 · prompt caching(重複前綴 90% 折扣) · 任務分級 → 不同模型(haiku for simple, opus for hard) 早期 90% 的 cost overrun 都是 infinite loop 與重複呼叫 ③ LATENCY · 延遲管理 使用者撐不過 10 秒沒回應 · streaming UI — 第一個 token 越早越好 · parallel tool calls — 子任務並行而非串列 · prompt caching 縮短 TTFT (time to first token) · progress signal("正在查詢...") · background mode — 長任務改 async + webhook 通知 ④ SCALING · 容量擴張 同時跑 100 個 session 還能不爆 · stateless agent runner(state 在外部 store) · session 持久化 → 可跨 instance 接續 · 排隊系統(celery / temporal)處理長任務 · LLM provider rate limit 監控與退避 · 多 provider failover(避免單點依賴) ⑤ OPERATIONAL MATURITY · 運維成熟度 把 agent 當成生產系統而不是 demo · 灰度發版 (canary / shadow deployment) · prompt / model / tool schema 版本管控(不是改了就上) · feature flag 控制 agent 行為(出包能立即關閉) · 用 eval set 做 pre-prod 回歸(見第玖回) · on-call rotation — 誰半夜三點爬起來看 agent 燒錢 · 事後檢討制度(postmortem culture)— 每個 incident 都要寫 RCA 「demo 容易、production 難。從 demo 到生產的路上倒下的 agent,比你想像的多。」
觀測為何最重要agent 失敗最常見的形式不是 throw exception,而是「答得不好」「繞遠路」「卡在某個 tool 重複呼叫 50 次」— 沒有 trace 你連發生了什麼都不知道,更別說修。
cost 是 SLO 不是會計把「單次 request 不超過 X 元」當作 SLO 監控、超過就觸發 alert。事後算帳已經來不及。
latency 心理學使用者對 agent 的耐心比對網頁高很多 — 但前提是「你讓他知道在做什麼」。沉默 5 秒會放棄;流著文字 30 秒會繼續等。streaming 不是優化,是必需。
不要 spawn 太多常見災難:使用者開很多 tab,每個 tab 都跑一個 agent,瞬間 100 個 LLM call 同時打 provider,rate limit 爆,整個服務掛掉。要在前面放排隊。
versioningprompt、model 名稱、tool 定義、agent 配置 — 全部都要 version 控制。否則「上週還好的,今天突然爆」根本無法 bisect。
postmortem 重點不是「為什麼模型答錯」(無解),而是「為什麼我們沒擋下這個錯」。永遠把原因歸到系統設計,不是模型靈感。