Harness Engineering：打造穩定可靠 AI Agents 的完整指南

大多數人都在錯誤的層級上嘗試改進 AI Agent。

當 Agent 失敗時，他們重寫提示詞。

當它再次失敗時，他們加入更多指令。

在我們開始之前：

在我的 Substack 上追蹤最新的 AI 前沿資訊、Agent 工作流程，以及逐步指南，這些內容會比在 X 上發布更早看到：[https://substack.com/@lunarresearcher

然後他們更換模型、加入更多工具、增加上下文視窗，並希望下一次運行會表現不同。

但許多 Agent 的失敗並非推理上的失敗。

它們是環境上的失敗。

Agent 不知道哪些檔案是重要的。

它在錯誤的地方使用了正確的工具。

它遺失了前一個工作階段所做的決定。

它在沒有執行檢查的情況下就宣稱成功。

它在部分失敗後重複了某個動作。

它被允許執行某個本應需要核准的行為。

問題不一定出在模型本身。而是圍繞著模型的系統不夠完整。

這個系統就是「控制框架 (Harness)」。

而設計這個框架正逐漸成為一門獨立的工程學科。

控制框架工程 (Harness Engineering) 是一門建構環境的實務，目的是將模型的智慧轉化為可靠的工作成果。

一個提示詞只能改變一次嘗試。

一個控制框架能改變每一次嘗試。

本指南將說明如何建構一個控制框架。

1. 模型不等於 Agent

一個模型能夠推理、生成、比較和選擇。

但一個 Agent 還必須與真實環境互動。

它需要能夠：

• 理解任務
• 找到相關的上下文
• 選擇並使用工具
• 保存狀態
• 遵守權限
• 檢查結果
• 從失敗中復原
• 證明工作已完成

模型是該系統內部的推理引擎。

控制框架則是讓推理得以運作的一切。

1使用者請求
2     |
3     v
4+-----------------------------+
5|          控制框架           |
6| 合約 | 上下文 | 政策       |
7| 工具 | 狀態   | 檢查       |
8| 軌跡 | 復原                  |
9+-----------------------------+
10     |
11     v
12    模型
13     |
14     v
15真實環境

一個強大的模型配上一個薄弱的控制框架，仍然是一個薄弱的 Agent。

它可能會產生令人印象深刻的個別回應，但在處理長期任務、變化的環境以及部分失敗時，其行為會不一致。

控制框架工程的目標並非消除模型的不確定性。

而是將這種不確定性限制在一個能夠觀察、驗證和復原的系統之內。

2. 從任務合約開始

大多數 Agent 任務始於模糊的意圖：

改善入職流程。

這句話對於對話來說可能足夠了。

但對於自主執行來說則遠遠不夠。

在 Agent 行動之前，控制框架應將請求轉換為任務合約。

一份有用的合約需要回答五個問題：

1. 必須達成什麼成果？
2. 範圍內包含什麼？
3. 哪些東西不能改變？
4. 什麼證據能證明完成？
5. 哪些行動需要人類核准？

1目標: 降低入職流程的流失率
2
3範圍:
4  - 註冊流程
5  - 入職分析
6
7限制條件:
8  - 不要更改身份驗證
9  - 保留現有的行動端行為
10
11驗收標準:
12  - 測試通過
13  - 分析事件被觸發
14  - 螢幕截圖涵蓋桌面端和行動端
15
16需要核准:
17  - 生產環境部署
18  - 資料庫遷移

這將 Agent 的問題從：

我下一步該做什麼？

轉變為：

什麼行動能讓環境朝著合約所訂的成果前進？

沒有合約，Agent 會優化於看似合理的活動。

有了合約，它就能優化於可驗證的完成。

3. 給 Agent 一張地圖，而非一本手冊

將整個儲存庫、文件集和對話歷史全部倒入上下文視窗，這不是好的上下文工程。

這是上下文洪水。

控制框架應先提供一張小型地圖，然後讓 Agent 在需要時才擷取細節。

1專案地圖
2
3產品規則     -> docs/product/
4架構          -> docs/architecture.md
5前端          -> apps/web/
6後端          -> services/api/
7測試          -> tests/
8指令          -> docs/commands.md
9發布規則      -> docs/release.md

這是漸進式揭露：

1任務
2  -> 專案地圖
3      -> 相關子系統
4          -> 確切檔案
5              -> 局部指令

上下文的擴展應該是因為任務需要，而不是因為資訊存在。

一個好的上下文編譯器會決定：

• 哪些是永遠需要的
• 哪些可以稍後再擷取
• 哪些已經過時
• 哪些可以摘要
• 哪些必須保持原樣

目標不是最大化上下文。

而是最大化每個 Token 的訊號量。

4. 建立一個工具閘道，而非工具堆

給一個 Agent 二十個工具並不會讓它變得更強大。

這只是給了 Agent 二十種犯錯的方式。

每個工具都應該有明確的合約：

1工具: edit_file
2
3輸入:
4  path
5  patch
6
7前置條件:
8  path 存在
9  path 在允許的工作區內
10
11成功證據:
12  patch 已套用
13  返回產生的 diff
14
15失敗行為:
16  不進行部分覆寫
17  返回結構化錯誤
18
19風險等級:
20  可逆

控制框架應控制工具如何被暴露和使用。

它可以：

• 隱藏不相關的工具
• 驗證參數
• 限制路徑和網域
• 附加逾時
• 使重試具有冪等性
• 標準化輸出
• 對高風險行動要求確認
• 返回證據，而不只是「成功」

這建立了一個重要的分離：

1模型決定意圖
2閘道驗證行動
3工具改變環境
4感測器觀察結果

模型可以提議一個行動。

工具閘道則決定該行動是否有效到足以執行。

5. 分離大腦、雙手和歷史

許多脆弱的 Agent 將所有東西混雜在一個不斷增長的對話記錄中。

推理、工具呼叫、檔案、決策、錯誤和舊的觀察結果都在同一個上下文視窗中競爭。

一個更強大的系統會分離三個職責：

1大腦
2規劃、推理、選擇
3
4雙手
5在受控環境中執行工具
6
7歷史
8儲存持久的事實、決策和運行狀態

模型不需要在活躍上下文中保留每一個原始事件。

它需要的是正確的當前狀態。

沙盒不需要理解整個目標。

它只需要安全地執行一個有邊界的行動。

工作階段日誌不需要進行推理。

它只需要在當前上下文消失後，保存發生過的事情。

這種分離使得長時間運行的 Agent 更容易恢復、檢查和修復。

它也讓你能夠更換其中一個部分，而不需要重建整個系統。

6. 記憶必須變成持久狀態

對話歷史不是可靠的記憶。

它是一個事件流。

有用的記憶應該被轉換為明確的狀態。

至少，保存四個類別：

1事實
2關於環境發現的穩定資訊
3
4決策
5做出的選擇及其背後的原因
6
7進度
8已完成、進行中、受阻和剩餘的工作
9
10教訓
11應改變未來行為的失敗

例如：

1事實:
2  - 結帳驗證邏輯位於 services/orders
3
4決策:
5  - 重用現有的驗證管道
6  - 原因: 避免第二個真相來源
7
8進度:
9  已完成:
10    - 新增伺服器端規則
11  剩餘:
12    - 更新整合測試
13
14教訓:
15  - 本地測試指令需要 TEST_DB_URL

這比重播五十頁的對話記錄並期望模型注意到重要行要來得有用得多。

儲存原始歷史以供稽核。

編譯持久狀態以供執行。

7. 完成需要證據

Agent 說「完成了」並不能證明任務已完成。

這只是另一個模型輸出。

完成與否必須由環境中可觀察到的變化來決定。

1聲稱                          證據
2--------------------------------------------------
3"這個 bug 修好了"            失敗的測試現在通過了
4"這個頁面能用了"            瀏覽器流程已完成
5"這個遷移是安全的"          試運行和回滾都通過了
6"這份報告是正確的"          數值與原始資料相符
7"任務已完成"                 每一項驗收檢查都通過了

控制框架應先執行成本最低的確定性檢查。

1語法
2  -> 型別
3      -> 聚焦測試
4          -> 整合測試
5              -> 視覺或語意審查
6                  -> 人類核准

不要在用編譯器、結構定義、校驗和、查詢或測試就能回答問題的地方，使用另一個模型。

將模型用於處理模糊性。

將程式碼用於處理基礎建設。

模型可以提議任務已完成。

只有環境能證明它。

8. 驗證應該攻擊結果

執行者和評估者不應共享相同的目標。

執行者試圖創造最強的解決方案。

評估者則試圖找出它應該被拒絕的理由。

1執行者
2  -> 產生候選方案
3
4驗證者
5  -> 檢查合約
6  -> 搜尋遺漏的情況
7  -> 測試未經支持的聲明
8  -> 嘗試破壞結果
9
10存活下來
11  -> 接受
12
13失敗
14  -> 返回有針對性的證據

這種不對稱性至關重要。

如果你在同一個上下文中，要求同一個 Agent 去「雙重檢查它的工作」，它往往會保留那些導致錯誤的假設。

一個有用的驗證階段應該具備：

• 明確的拒絕標準
• 能存取產出的成品
• 能存取驗收合約
• 在需要時有獨立的工具或全新的上下文
• 有權拒絕而不進行修復

驗證不是第二意見。

它是一次試圖反證的過程。

9. 模型提議，政策授權

有些規則永遠不該依賴模型是否記得它們。

1未經核准絕不發布
2絕不暴露機密
3絕不在工作區外寫入
4絕不超過支出上限
5絕不標記測試為通過，除非它們真的跑過

這些不是提示詞建議。

它們是政策。

最安全的設計是將政策置於推理迴圈之外。

1低風險
2讀取檔案、搜尋、檢查
3-> 自動
4
5可逆的變更
6編輯工作區、執行測試
7-> 自動並留下軌跡
8
9外部影響
10發送訊息、部署、購買
11-> 明確核准
12
13不可逆或敏感
14刪除資料、輪換憑證、全球發布
15-> 嚴格把關或禁止

後果越嚴重，把關就越嚴格。

自主性並非缺乏控制。

而是在一個明確強制執行的邊界內自由運作的能力。

10. 復原應針對失敗類型

最常見的復原策略是：

出錯了。再試一次。

這不是復原。

這是重複。

控制框架應在選擇下一步行動之前，先對失敗進行分類。

1工具逾時
2-> 使用退避策略重試
3
4無效的參數
5-> 修復工具呼叫
6
7遺失上下文
8-> 擷取特定來源
9
10測試失敗
11-> 檢查失敗的行為
12
13權限不足
14-> 請求核准或選擇安全路徑
15
16矛盾的請求
17-> 升級給人類處理
18
19重複相同的失敗
20-> 停止迴圈

一次重試應至少改變一個相關條件。

否則系統只是在花錢複製同樣的失敗。

一個有邊界的 Agent 迴圈看起來像這樣：

1觀察
2  -> 決定
3      -> 行動
4          -> 衡量
5              -> 接受
6              -> 修復
7              -> 升級
8              -> 停止

每個迴圈都需要一個預算：

• 最大嘗試次數
• 最長時間
• 最大花費
• 最大破壞範圍
• 升級條件

可靠的 Agent 知道如何繼續。

它們也知道何時繼續下去不再合理。

11. 指令應成為基礎設施

Agent 指令在解釋局部現實時很有用。

但僅靠指令的約束力很弱。

如果某條規則反覆出現，就將它往技術堆疊的下層移動。

1"使用格式化工具"
2-> 自動執行格式化工具
3
4"不要跨層導入"
5-> 新增架構測試
6
7"包含遷移回滾"
8-> 在 CI 中要求回滾檔案
9
10"不要修改生成的檔案"
11-> 封鎖對生成路徑的寫入
12
13"引用每個外部主張"
14-> 驗證引用覆蓋率

這建立了一個指令階梯：

1解釋
2  -> 檢查清單
3      -> 模板
4          -> 自動化檢查
5              -> 強制執行政策

將重要的知識沿著這個階梯向下移動，越實用越好。

提示詞應該解釋判斷。

控制框架應該強制執行不變量。

12. 觀察運行過程，而不只是最終答案

一個乾淨的最終成品可能隱藏著糟糕的過程。

Agent 可能：

• 存取過錯誤的資料
• 忽略了失敗的指令
• 重試了兩次外部行動
• 消耗了預期預算的十倍
• 基於錯誤的理由得到了正確的答案

你需要能夠重現運行過程的軌跡。

109:14  合約已建立
209:15  上下文來源已載入: architecture.md
309:17  檔案已編輯: checkout.ts
409:18  聚焦測試失敗: 重複優惠券
509:21  實作已修復
609:22  聚焦測試通過
709:24  整合測試通過
809:25  外部部署被阻止: 需要核准

一份有用的軌跡記錄了：

• 狀態轉換
• 上下文來源
• 工具輸入和輸出
• 環境變化
• 驗證結果
• 重試原因
• 核准決策
• 成本和延遲

目標不是監視。

目標是局部修復。

當運行在第 18 步失敗時，你應該能夠從一個可信的檢查點重新開始，而不是重播整個任務。

13. 每次運行都需要一份變更收據

冗長的 Agent 對話記錄難以審查。

在運行結束時，控制框架應編譯一份簡短的變更收據。

1目標
2修復結帳時重複套用優惠券的問題。
3
4已變更
5- 結帳驗證邏輯
6- 聚焦回歸測試
7
8已驗證
9- lint 通過
10- 單元測試通過
11- 結帳整合測試通過
12
13未驗證
14- 生產環境的支付提供商
15
16決策
17- 保留了現有的優惠券優先順序
18
19風險
20- 舊版行動端客戶端無法在本地測試
21
22需要核准
23- 部署到暫存環境

這份收據不是模型說了什麼的摘要。

而是系統能夠證明什麼的摘要。

這為人類提供了一個緊湊的審查面，也為下一個 Agent 工作階段提供了一個可信的起點。

最好的交接不是「這是對話記錄」。

而是「這是狀態、證據和未解決的風險」。

14. 每次失敗都應升級控制框架

最弱的團隊只修復失敗的輸出。

最強的團隊也會修復允許失敗發生的系統。

在失敗之後，問：

1任務合約是否模糊不清？
2重要的上下文是否不可見？
3是否暴露了錯誤的工具？
4是否遺漏了前置條件？
5結果是否無法驗證？
6政策是否留在了提示詞中？
7復原策略是否過於寬泛？
8軌跡是否不足？

然後將教訓轉化為可重複使用的改進。

1失敗
2  -> 診斷
3      -> 新的感測器、規則、地圖、測試或工具合約
4          -> 未來的運行會自動改善

這就是控制框架的飛輪效應。

系統變得更加可靠，因為失敗留下了基礎設施。

一個修正後的答案幫助一次運行。

一個修正後的控制框架幫助每一次未來的運行。

15. 控制框架也會衰退

更多的控制框架不一定總是更好。

模型會進步。工具會進步。任務會改變。舊的安全措施可能變成不必要的阻礙。

為昨天的模型建立的應急方案，可能會阻止今天的模型使用更好的策略。

這導致了控制框架衰退：

1舊模型的限制
2  -> 控制框架的應急方案
3      -> 模型進步了
4          -> 應急方案卻留了下來
5              -> 系統變得更慢或能力更差

將控制框架的組件視為生產程式碼。

衡量它們是否仍然提供價值。

對於每個路由器、評估器、記憶層和重試規則，問：

• 這預防了哪種失敗？
• 那種失敗現在發生的頻率有多高？
• 這增加了多少延遲和複雜度？
• 現在能否用更簡單的方式達到同樣的結果？
• 如果移除它會怎樣？

最好的控制框架不是最大的那個。

而是能夠可靠地縮小意圖與證據之間差距的最小系統。

為了刪除而建構。

16. 最小可行控制框架

你不需要一個編排平台才能開始。

分層建構控制框架。

第一層：有邊界的任務

• 目標
• 範圍
• 限制條件
• 驗收檢查

第二層：清晰的環境

• 專案地圖
• 指令
• 局部說明
• 已知依賴項

第三層：受控的行動

• 型別化工具
• 參數驗證
• 路徑和權限邊界
• 結構化結果

第四層：持久的執行

• 明確的運行狀態
• 檢查點
• 決策
• 教訓

第五層：證據

• 確定性檢查
• 對抗性驗證
• 變更收據

第六層：復原與學習

• 失敗分類
• 有邊界的重試
• 升級
• 根據反覆出現的失敗更新控制框架

建構能夠消除你實際遇到的失敗的最小層級。

不要因為一個簡單的提示詞偶爾需要釐清，就從多 Agent 架構開始。

複雜性應該由觀察到的失敗來贏得。

17. 一份可重複使用的控制框架規格

在賦予 Agent 有意義的自主權之前，定義好這個：

1AGENT 控制框架規格
2
31. 合約
4   目標:
5   範圍:
6   限制條件:
7   驗收證據:
8
92. 上下文
10   始終載入的地圖:
11   檢索來源:
12   局部說明:
13   新鮮度規則:
14
153. 工具
16   允許的工具:
17   前置條件:
18   副作用:
19   成功證據:
20   逾時和重試政策:
21
224. 狀態
23   事實:
24   決策:
25   進度:
26   教訓:
27   檢查點格式:
28
295. 政策
30   自動行動:
31   需要核准的行動:
32   禁止的行動:
33   預算限制:
34
356. 驗證
36   確定性檢查:
37   對抗性檢查:
38   驗收規則:
39
407. 復原
41   失敗類別:
42   重試限制:
43   升級條件:
44   安全回滾:
45
468. 可觀測性
47   軌跡事件:
48   指標:
49   最終變更收據:

如果這些欄位未定義，那麼 Agent 就不是自主的。

它是在即興發揮。

18. 在正確的層級衡量系統

Token 數量不是最終指標。

嘗試的任務數量也不是。

有用的單位是已驗收的工作。

一個實用的指標是：

1已驗收的輸出
2------------------------------
3人類審查分鐘數 + 運行成本

同時追蹤：

• 首次通過驗收率
• 工具失敗後的復原率
• 重複失敗率
• 每項任務的人類干預次數
• 未經證實的完成聲稱
• 從請求到驗證結果的時間
• 各組件的控制框架開銷

這可以防止一種常見的錯覺：

一個 Agent 可能看起來生產力很高，但同時卻產生了昂貴的審查工作。

目標不是更多的 Agent 活動。

而是每單位人類注意力所產生的、更值得信賴的成果。

19. 何時不需要沉重的控制框架

並非每次模型呼叫都需要一個作業系統。

在以下情況使用簡單的提示詞：

• 任務很短
• 輸出很容易檢查
• 失敗的代價很低
• 沒有外部副作用發生
• 使用者保持在迴圈中

在以下情況加入控制框架：

• 工作跨越了多個工具或工作階段
• 環境可能會改變
• 行動有實際後果
• 完成與否難以手動判斷
• 同樣的失敗反覆出現
• 人類審查變成了瓶頸

控制框架的目的不是讓一個展示看起來很複雜。

而是讓實際工作變得可靠。

真正的轉變

第一代 AI 產品是圍繞著提示詞建構的。

下一代產品正在圍繞著環境建構。

問題不再僅僅是：

我們如何讓模型的回答更好？

而是：

我們如何建立一個系統，讓好的行動變得容易、危險的行動受到控制、失敗能被看見、完成能被證明？

這就是從提示詞工程到控制框架工程的轉變。

模型提供智慧。

控制框架提供結構。

兩者結合，產生可靠的執行。

如果你的 Agent 一直出問題，別再往提示詞裡加形容詞了。

為它建立一個能夠成功的環境。

如果你讀到了這裡

把這份指南加入書籤。

在 X 上追蹤 @LunarResearcher

訂閱我的 Substack

把這篇文章分享給那些還在試圖用更長的提示詞來修復每一個 Agent 失敗的人。