Harness Design For AI Agents：一條真實連結講清它是如何運作的

一條真實的 Harness 連結：讓它跑起來，再讓它輸出來

假設你正在建立一個程式碼來審查 Agent，它的核心任務是用 LLM 分析 PR diff，然後產生是否通過的結論。你不想每次測試都真的打開編輯器、創建 PR、等待 GitHub Webhook——你需要一個 Harness。

Harness Design for AI Agents 的核心想法是：把 Agent 的執行過程與外部世界隔離開，用可控的輸入和斷言來驗證它的行為。這條連結分為三步驟：Mock 輸入 → 執行 Agent → 斷言輸出。

第一步：Mock 輸入，而不是真實外部調用

最常見的錯誤是直接讓 Agent 連真實 API。 Harness 的做法是提前錄製或偽造外部回應。例如，對程式碼審查 Agent，你需要 mock GitHub 的 PR 資料、diff 內容、甚至 LLM 的回傳。

一個容易失敗的地方：mock 資料太乾淨。真實環境中的 PR 評論可能帶有 @mention、空白行、亂碼，如果 harness 只用了格式化良好的範例，Agent 會在生產中出現各種意外。正確做法是至少包含 3 種變異：正常 diff、含大量註釋的 diff、以及部分檔案被刪改的 diff。

第二步：讓 Agent 在 Harness 中執行，並收集完整日誌

不只是在終端觀察 print 輸出。 Harness 應該捕捉 Agent 的每一步思維鏈、每次工具呼叫、以及最終決策。例如，你的 Agent 內部可能呼叫了 analyze_diff 和 check_style 兩個工具，Harness 需要記錄每個工具的輸入輸出和耗時。

一個可執行做法：在 Agent 程式碼中埋入結構化日誌，用 JSON 格式輸出每個步驟的 context。測試時，Harness 既能斷言最終結果，也能檢查中間步驟是否合理。例如，斷言 analyze_diff 的傳回中是否包含函數簽章變更。

第三步：斷言輸出，而不僅僅是「通過/不通過」

簡單斷言 Agent 的最終輸出是 pass 還是 fail 遠遠不夠。 Harness 應該可以讓你檢查輸出的結構、內容甚至語氣。例如，對於程式碼審查 Agent，可以斷言：

輸出必須包含 approved: true/false 字段
如果 diff 中有安全漏洞，則評論必須包含字詞 "vulnerability"
如果 diff 僅涉及文檔，Agent 必須跳過審查

一個容易失敗的地方：斷言寫得太具體，導致 harness 和 Agent 強耦合。一旦 Agent 的輸出格式調整，harness 就全掛了。建議斷言定義在介面層，用 schema（如 Pydantic 或 JSON Schema）而不是硬編碼字段路徑。

真實場景：從 GitHub PR 到本地 Harness

我的一位同事曾用 Harness 測試他的程式碼審查 Agent。他 mock 了一個包含 SQL 注入修復的 PR diff，期望 Agent 的 approve 為 true，並且在評論中出現 "LGTM"。第一次運行，Agent 確實 approve 了，但輸出的是 "Looks good to me"，Harness 斷言失敗，因為用例大小寫不匹配。他就此修復了 prompt，並要求 Agent 始終使用 "LGTM"。

這個小例子說明：Harness 不僅能驗證功能正確性，還能校驗行為一致性。如果不在 harnees 中設定這些邊界，Agent 在上線後可能會用不同的表達來混淆使用者。

編輯器中展示一個 mocked 測試運行，程式碼中包含 mock 資料和斷言邏輯。

容易失敗的地方與錯誤理解

誤解：Harness 是測試框架。實際上，Harness 更接近一個可控制、可重複的運作環境，而不僅僅是 assert 工具。它管理 mock、日誌、斷言、甚至 Agent 生命週期。
陷阱：Mock 資料缺少邊緣情況。真實 LLM 可能傳回很長的文字或空內容，mock 時需覆寫這些值。
陷阱：忽略時序依賴。有的 Agent 依賴步驟間時間間隔，harness 如果加速運行，可能改變行為。如需要，可在 harness 中引入虛擬時鐘。

筆記型電腦上顯示的 QA 檢查清單，列出 Harness 設計中需要涵蓋的邊界條件。

如果你現在就要落地，第一步該做什麼

選定一個簡單 Agent－例如單一工具、單一任務的 Agent（例如查詢天氣的 Agent）。
用 Python 寫一個 Harness 類，包含 set_mock_response、run、assert_output 三個方法。
錄製 3 種不同的真實使用者查詢，手動建構對應的 mock 輸入。
執行 Harness，檢查 Agent 輸出是否符合預期。
故意引入一個錯誤（例如 mock 中缺少必要字段），觀察 Harness 能否捕獲失敗。

完成這 5 步驟後，你就有了一套可重複使用的 Harness 基線，後續可以擴展斷言粒度、引入日誌收集等。

下一步去哪裡繼續系統化學習

如果你已經實踐了上述步驟，接下來需要學習：如何將 Harness 整合到 CI/CD 管線、如何設計多 Agent 協作場景的 Harness、以及如何將 Harness 與可觀測性工具（如 Langfuse）結合。高品質原始付費文章和 AI 程式設計進階課程會涵蓋這些內容，幫助你從一般開發者係統化轉型為 Agent 工程師。