Stage 7 — Agent 上線工程：可測、可看、可停、可恢復

繁體中文 | 简体中文 | English

先讓 AI 幫手可測、可看、可停、可恢復，再交給別人使用。

🎯 這一關在做什麼（先定位）

讓 Agent 可測、可看、可停、可恢復。這稱為 Agent Production Engineering（Agent 上線工程）。像玩具車先裝方向盤、煞車與儀表板；不需大規模。

全章用一個故事：AI 幫手查三個來源、整理摘要，送出前先請人確認。

先記住上線順序：

先說清楚怎樣算成功 → 留下做事紀錄 → 危險動作先問人 → 確認跌倒後能繼續 → 最後才交給別人使用。

先做穩單一 Agent；需要獨立分工或互相檢查時，再加 Agent。

📌 學習目標

完成本章後，你能：

1. 分清 AI 幫手工作的地方、反覆做事的節奏和帶岔路的完整路線。
2. 把真實失敗寫成可重跑的測試，不只看一次漂亮回答。
3. 找到一次任務裡的每一步、錯誤、時間與成本。
4. 讓高風險動作先停下問人，並能從正確位置繼續。
5. 用同一組證據判斷系統能不能交給別人使用。

🧩 先認識十九個核心詞

先看「像什麼」抓住方向，再看「本章用途／技術界線」了解這一關怎麼使用它。同類詞已合併在同一組，不需要讀兩次。

**Prompt（提示）**是你交給模型的指令與材料。**Context（上下文）**是這一步需要看的資料。它們仍然重要；本章是在外面補上執行、檢查和復原的系統。

🚪 進入條件

你至少應該完成：

• Stage 4：知道 Agent、Tool 與 Workflow 是什麼。
• Stage 5：看過工具權限、Subagent 與開發流程。
• Stage 6：知道 Context、RAG 與 Memory 不一樣。

Docker 還不熟也可以開始；先做四個核心練習，再為核心練習 4 補 Docker。

📚 必修閱讀

先按 production 順序讀這六份：

1. Anthropic — Demystifying evals for AI agents：先分清 Outcome 與完整 Trajectory；Agent 說「完成」不等於外部結果真的完成。
2. OpenAI Agents SDK — Tracing：看 trace、span、tool、handoff 與 guardrail 事件如何串起一次 run。
3. OpenAI Agents SDK — Human-in-the-loop：敏感工具先暫停，再保存 RunState、核准或拒絕並 resume。
4. LangGraph — Persistence：分清 checkpoint 與跨 thread store，知道中斷、復原與長期記憶不是同一件事。
5. LangGraph — Interrupts：看人工核准如何暫停與續跑，以及為什麼 interrupt 前的副作用必須冪等。
6. Anthropic — Building Effective Agents：先用簡單組合，只有真的需要分工時才增加自主性或 Multi-Agent。

🧭 Harness、Loop、Graph 與 Eval 怎麼合作？

它們不是四代產品，也不是只能選一個。請把同一個研究助理想成四個角度：

Eval 會檢查 Outcome、Trajectory，再由 Grader 依規則判斷是否合格。Eval 可以讓 Loop 重試、讓 Graph 換路，或要求 Harness 停止；但把 Harness 和 Eval 放在一起，仍不會自動產生「何時重複、何時停止」的 Loop。

學習順序是 Stage 3 的 Agent Loop → Stage 4 的 Workflow Graph／Agent Framework → 本章的安全上線整合。Loop Engineering 是 IBM 使用的新興說法；Graph Engineering 的用法更鬆散。讀者要先學清楚責任，再把這些名稱當成社群搜尋詞。來源：IBM — Loop Engineering、Anthropic — Agent harness 與 eval、Microsoft Agent Framework — graph-based workflows。

🏗 Agent Harness：先把安全工作間準備好

模型像會想辦法的大腦，但它不能自己讀檔、寄信或保存進度。Agent Harness 把工具和規則接在模型旁邊，也常負責執行 Agent Loop。外層排程器可以多次呼叫同一個 Harness，所以 Harness 不只代表一次很短的執行。正式設計這個環境的工作常叫 Harness Engineering。來源：OpenAI — Harness engineering、Anthropic — Agent harness 定義、Anthropic — Managed agents。

Harness 的 8 個核心元件

這八項是本專案的 production 檢查表，不是全世界唯一的官方分類。

🔁 Agent Loop：做一步、看結果，再決定

先分清三種很像、但範圍不同的 Loop：

IBM 用 Goal → Action → Observation → Adjustment 說明較外層的 Loop Engineering。重點不是讓 Agent 永遠自己跑，而是每一輪都能回答：目標還成立嗎？證據夠了嗎？要繼續、停止，還是交給人？

因此，Loop Engineering 不是 Harness 的下一代產品，也不會自動淘汰 Harness。在 Anthropic 的用語裡，Harness 本身就包含呼叫模型與路由工具的 loop；IBM 的 Loop Engineering 則把目標、檢查、工具、hooks、context、subagent 與持久狀態放進更大的反覆工作設計。不同文件切邊界的方法不同，所以請記責任，不要硬背一張唯一的層級圖。來源：IBM — Loop Engineering、Anthropic — Managed Agents。

模型變強時，某個補丁可能可以刪掉。例如 Anthropic 在較新模型上移除了先前 harness 使用的 context reset。但這只表示一個 workaround 經同一組 Eval 證明不再需要，不表示權限、安全、log、eval 或 recovery 自動過時。來源：Anthropic — Harness design for long-running applications。如何逐項保留、簡化或移除，放在 Stage 7.5 的 Model–Harness Fit。

🗺 Workflow Graph：遇到岔路時知道往哪走

Agent Loop 負責「要不要再做一次」。Workflow Graph 負責「接下來要去哪裡」。它像一張有岔路的校園地圖；地圖能排路線，但不會替每一站完成工作。

外面的文章有時把這份工程工作稱為 Graph Engineering。這是新興稱呼；真正需要學會的是 node、edge、branch、cycle、state、checkpoint 與 human approval，不是先背一個尚未統一的標籤。

一個節點裡可以有 Agent Loop；節點之間由 Workflow Graph 安排順序。

🧪 Eval：先說要什麼，再決定怎麼評

Eval 不是一個分數，也不是等系統做完才補的報表。它先寫清楚「怎樣才算成功」，再用同一套方法檢查不同版本。

先從 **Outcome（結果）**開始。研究助理的 Outcome 不是「Agent 說摘要完成了」，而是「摘要真的使用三個合格來源、引用可以打開，而且尚未跳過人工核准」。

接著建立完整的 Eval Case（評測案例）。它像一張連規則都寫好的考題；input 只是其中一格。

把多個完整案例放在一起，叫做 Eval Suite（評測組）。替 Suite 留下版本，才能知道這次和上次是不是在考同一份題目。

經人檢查、可重複使用的完整案例集合，本專案稱為 Reviewed Eval Set（已審查評測集）。外部資料有時寫 Golden Set 或 Reference Set，但這些名稱沒有跨供應商一致定義。看到它們時，要回到來源確認它是在說題目、答案、標準，還是整套資料。

**Golden／Reference Set 不只是 input，也不等於訓練資料或 Few-shot 範例。**它通常包含完整案例、條件、參考證據與評分方法；實際欄位仍要看當前專案的定義。

最後再加入這些測量詞：

Anthropic 的 Agent Eval 指南把 task、trial、grader、trajectory 與 outcome 分開；OpenAI 的 Graders API列出多種 grader。工具可以不同，但每份報告都應留下 dataset version、split、case ID、trial 次數、grader、Outcome、Trajectory 與 baseline。

負責載入 cases、重跑 Agent、呼叫 grader 並保存結果的系統，是前面定義過的 Evaluation Harness。它可以呼叫 Agent Harness，但兩者的責任不同：一個讓工作安全執行，一個讓測試可以重複比較。

🔎 Observability：出錯時看得見是哪一步

Observability 像在透明積木盒外面看每一格。它不是把所有內容公開，而是留下能除錯的 trace、log 與 metrics，並遮住密碼、個資和客戶資料。

在研究助理案例裡，一次 **Trace（追蹤紀錄）**要能回答：查了哪些來源、哪個工具失敗、重試幾次、花了多少時間，以及為什麼停在人工核准前。Trace 能解釋 Trajectory，但「記錄很多」不等於「結果正確」；Outcome 仍要交給 Eval 檢查。

🛑 Approval、Checkpoint、Resume 與 Recovery：先停，再安全繼續

研究助理準備送出摘要時，先進入 Human Approval。這不是請人從頭重做，而是把摘要、來源與風險一起交給人核對。

核准前先保存 Checkpoint。重新啟動後用 Resume 回到同一個 task；如果中間失敗，Recovery 決定要重試、補償、回到舊狀態，或交給人。任何會寄信、付款或寫資料的動作都要帶 Idempotency key，確保相同重試只產生一次外部效果。

🛡 完整上線路線：Eval → Observability → Approval／Recovery → Deploy

**Deploy（部署）**是把通過檢查的系統交給別人使用。它像開店前正式開門；開門不是成功證明，前面的測試、紀錄、煞車和復原方式才是。

這四步不是成熟度徽章，而是同一次修改要走完的檢查路線：

Outcome Eval 要檢查外部世界的結果。例如 Agent 說「信已寄出」只是文字；測試環境真的只有一封信、收件者正確，才是 Outcome 通過。Trajectory Eval 則檢查它用了哪些工具、嘗試幾次、是否繞過核准、花多少 token。兩種一起看，才不會只因最後一句很漂亮就放行。

案例先從真實失敗建立：每遇到一次錯誤，就留下去識別化的輸入、預期 Outcome、禁止動作與重現步驟。正式資料不能直接複製進公開 repo；必要時改成結構相同的假資料。

🧭 OpenRouter、Pi、OpenCode、Orca、QM 到底差在哪？

它們不是五個同類產品。把它們放到正確層，就不會混在一起：

模型入口 → Agent runtime → 多 Agent 協作平台。這三層可以互相搭配，但不能互相代替。

🛠 動手練習

先走四個核心練習。不要先把檔案改名或重抄一份；直接跑測試，再只改一個小地方。

核心練習 1：Eval

**成果：**用固定案例與規則檢查 Agent，看到哪一題退步。

cd examples/stage-7/02-eval
python test.py

核心練習 2：Observability

**成果：**看到一次執行的步驟、延遲、token 與錯誤。

cd examples/stage-7/03-observability
python test.py

核心練習 3：Approval、Checkpoint 與 Recovery

**成果：**敏感動作先停在人工核准點；重新啟動後從 checkpoint resume，相同 idempotency key 不會重複執行。

cd examples/stage-7/06-safe-execution
python test.py

核心練習 4：Deploy

**成果：**把 Agent 包成有 /health 與 /chat 的 API，再用測試確認錯誤狀態。

cd examples/stage-7/05-deploy
python test.py

🧭 進階選修（入口保持可見）

選修 A：Multi-Agent 辯論

**成果：**兩個 Agent 分別提出正反意見，第三個 Agent 依規則裁決。只有單一 Agent baseline 已有 Eval，且角色真的需要分開時再做。

打開 Multi-Agent 範例

選修 B：Streaming 與 Prompt caching

**成果：**比較 streaming 與 prompt caching 的行為；成本效果必須自己量，不把 cache 當成安全或復原機制。

打開 SDK 進階範例

cd examples/stage-7/01-multi-agent-debate
python test.py

cd ../04-sdk-advanced
python test.py

🧪 推薦小專案：有收據的研究助理

先做一個單一 Agent 版本：

1. 找三個來源，保留 URL 與擷取時間。
2. 只根據來源寫短摘要；找不到就明寫不知道。
3. 在「發布摘要」前停下來，讓人核准、修改或拒絕。
4. 保存 checkpoint；模擬程式中斷後 resume。
5. 用 idempotency key 證明同一次發布重跑也只寫入一次。

交出 execution receipt（執行收據）。記下 task ID、Outcome、Trajectory、工具與來源。再記耗時、token、錯誤、checkpoint 版本與人工核准。先用 5 個 development cases 做 baseline，再把真實失敗加入版本化 suite。結果變差時，重跑足夠 trials，比對預先門檻並檢查失敗案例；單次隨機失敗不等於已證實退步。

單一 Agent 穩定後，才考慮拆出「找資料」與「審查」角色，比較品質、成本與延遲。

📊 Agent Benchmark Landscape：怎麼看，不要只看排行榜 + ⚠ Reward-Hacking 警告

**Benchmark（基準測試）**像統一考卷。它能幫你比較，但不能保證你的真實工作也會一樣好。

看任何分數前，先問五件事：

**Reward hacking（獎勵鑽漏洞）**就是「拿到高分，卻沒有真的完成目的」。像小孩發現只要按一下鐘就有糖，於是一直按鐘，卻沒做原本的任務。

🎯 精選 Projects（範本 / SDK / 工具 collection）

按用途選，星等不是 GitHub stars。兩份新文件供單 Agent baseline 後比較；三星依文件教學價值，未實跑 API。

既有查核：2026-09-13 UTC；新文件查核：2026-10-02 UTC

✅ Stage 7 之後的自我檢查

• 我能分清 Outcome 與 Trajectory，並用兩者檢查同一個 case。
• 我有從真實失敗建立的固定 Eval cases，不只看一次漂亮輸出。
• 我能找到一次執行的 trace、錯誤、延遲與 token。
• 高風險工具有最小權限與人工核准；沒有核准時會 fail closed。
• 我能從 checkpoint resume，並證明相同 idempotency key 不會重複副作用。
• 我能展示 execution receipt，並說明何時停止、復原或 rollback。
• 我能用一句話分清 OpenRouter、Agent runtime 與多 Agent 平台，也知道單一 Agent 是預設選擇。

完成後，進入 Stage 7.5 — 進階 Agentic 概念地圖，再到 Stage 8 — Agent Interfaces。如果其中一項還說不清楚，回到對應練習，只改一件事再測一次。