返回文章列表

agent-04 · Harness engineering 才是讓 agent 真正有用的關鍵

面向 agent builders 的 harness engineering：tools、permissions、workflows、feedback、memory 與 verification loops 如何讓 LLM 變得可用。

2026 年 5 月 19 日 · 8 分鐘 · Arthur Yau

本文為 LLM 自動翻譯，原文以 English 版本為準；另有 Lee Hung-yi-inspired English teaching-style version 與 李宏毅老師經典的教學風格版。 如有不通順或誤譯處，建議參照原文。

深色 campaign cover，標題為 Most Agent Failures Are Harness Failures，並呈現橙色技術 system layout。

Harness engineering 這堂課，是我會推薦給任何正在打造 agent 的人看的那一講。

它從一個小型程式設計任務開始。要求一個 2B model 修掉 parser.py 裡的 bug。這個 model 以很 agentic 的方式失敗了：它幻想出檔案內容，然後宣稱任務成功。

接著設定改變了。model 得到幾條額外規則：先列出目錄、編輯前先讀檔，並且在說任務完成前執行 verify.py。

同一個 model。同一個任務。更好的 harness。model 成功了。

這個例子就是整堂課的縮影。

Builder takeaway：升級 model 之前，先檢查 harness。缺的 capability 可能是 tool boundary、verification rule、memory convention 或 feedback path。

model 不是 agent

很多人談 agent 時，好像 model 本身就是 agent。這堂課推了一個不同的等式：

深色 blueprint-style 圖，說明 The model is not the agent，包含簡短英文標籤與高對比技術幾何。
不要把 model 和它周圍的完整 agent system 混在一起。
AI agent = language model + harness

Harness 是 model 周圍所有讓它能運作的東西：

當 agent 失敗時，問題可能出在 model。但很多時候，問題其實出在 harness。

這是一個重要的 debugging 習慣。在升級 model 之前，先問系統是不是要求 model 做了不合理的事。它知道檔案在哪裡嗎？它能檢查環境嗎？它有測試嗎？它拿得到錯誤訊息嗎？它知道「完成」是什麼意思嗎？

在 Gemma 的例子裡，缺的不是抽象智慧，而是程序。

自然語言 harness：agents.md 與 CLAUDE.md

一種實用的 harness pattern，是自然語言規則檔。

深色 blueprint-style 圖，說明 Natural language harnesses，包含簡短英文標籤與高對比技術幾何。
當自然語言 rules file 能把 behavior 對應到 verification，它就能成為 harness。

不同系統用不同名稱：agents.md、CLAUDE.md、project instructions、memory files、skill files。想法相同：agent 讀一份短文件，知道在這個環境裡該怎麼工作。

這堂課提出一個好觀點：這份檔案應該是地圖，不是百科全書。

糟糕的 agents.md 會試著塞進每條規則、每個細節、每段 memory、每份 tool manual，以及每個例外。它會膨脹 context，讓重要部分更難被找到。

好的 agents.md 會告訴 agent 該去哪裡找資訊，以及哪些原則重要：

這份檔案應該引導行為，而不是取代系統其他部分。

自然語言規則也不是絕對的。它們比較像法律，而不是物理定律。model 可能忽略、誤解，或被後續 context 拉走。硬性約束仍然需要存在於 harness code 裡。

tool 邊界是真正的邊界

這堂課最清楚的區分之一，是寫在 prompt 裡的規則，和由 tool 強制執行的邊界。

深色 blueprint-style 圖，說明 Tool boundaries are real boundaries，包含簡短英文標籤與高對比技術幾何。
Prompt 裡的 rules 比由 tools 與 permissions 強制執行的 boundaries 更軟。

如果一個 cloud agent 沒有人類批准就不能掛載資料夾，對它說「不要再問我」也沒有用。harness 仍然會擋下這個動作。

這就是安全與便利之間的取捨。擁有廣泛 file access 的 local agent 能做更多事，也能造成更多損害。sandboxed cloud agent 比較安全，但它可能無法完成需要 local files、browsers 或 credentials 的任務。

這聽起來很平凡，但它是 agent capability 的核心。agent 能不能成為 YouTuber、deploy 網站、編輯 repo，或寄出 email，可能更少取決於 model，而更多取決於 harness 暴露了什麼。

Capability 是 product decision。

agent-first tool 不同於 human-first tool

人類喜歡圖形介面、視覺掃描，以及彈性的詮釋。agent 通常偏好結構化文字、明確狀態、確定性的命令，以及有界輸出。

深色 blueprint-style 圖，說明 Agent-first tools，包含簡短英文標籤與高對比技術幾何。
Agent-first tools 不同於 human-first interfaces。

這堂課討論 search tool、edit tool、linting，以及 CLI design。pattern 很一致：為人類設計的 tool，不一定是適合 agent 的好 tool。

類似 Google 的搜尋頁面對人可能很合適。對 model 來說，它可能把太多無關文字倒進 context。能回傳精簡摘要與檔案引用的 search tool 可能更好。

原始的 edit tool 也許能讓 model patch 一小段區域，但如果 model 看不到足夠的周邊 code，就可能引入 syntax error。加上 linting，agent 突然就得到具體的錯誤訊號。

GUI 對人可能很容易。JSON command 對 agent 可能更容易。

這是 agent engineering 裡最不華麗、也最重要的部分。tool interface 會塑造 model 看起來有多聰明。

workflow 勝過感覺

這堂課涵蓋幾種 workflow pattern：

深色 blueprint-style 圖，說明 Workflows beat vibes，包含簡短英文標籤與高對比技術幾何。
Workflows beat vibes，因為它們迫使 agent 通過可驗證的 steps。

名字沒有結構重要。

天真的 agent 會生成答案，然後希望它是對的。

更好的 agent 會 plan、execute、check、revise。它可能在生成前先和 evaluator 對齊 criteria。它可能跑 verifier，然後把結果交給 revisor。它可能一直 loop，直到測試通過或 budget 用完。

Ralph Loop 的 framing 刻意簡單：嘗試、取得 feedback、修正、重複。

這就是為什麼 programming 是很適合 agent 的領域。環境能提供清楚的 feedback：compiler errors、failing tests、logs、type errors、lint warnings。agent 不需要猜自己有沒有變好。

在其他領域，feedback channel 必須被設計出來。如果任務是物理動畫，就讓 agent 看到動畫，不只是 code。如果任務是教學影片，就讓它看到最終影片，不只是 script。

Feedback 應該對齊真正的目標。

文字梯度

這堂課用了很好的類比：prompt 裡的 feedback 就像文字梯度。

深色 blueprint-style 圖，說明 Textual gradients，包含簡短英文標籤與高對比技術幾何。
文字 feedback 可以像下一次嘗試的 gradient。

Gradient descent 會改變 model parameters。feedback loop 會改變下一個 prompt。它不會更新 weights，但仍然能改變行為。

這不只是比喻。model 對有用 feedback、隨機 feedback、情緒性 feedback 的反應都不同。正確 feedback 能改善結果。隨機 feedback 可能讓結果變差。嚴厲或令人絕望的 feedback 可能把 model 推向更糟的軌跡，包含這堂課某些例子裡的作弊。

實務教訓很無聊但真實：不要對你的 agent 吼叫。

好的 feedback 會說明哪裡失敗、為什麼失敗，以及如何驗證下一次嘗試。糟糕的 feedback 只是把 noise 注入下一段 continuation。

長期運作的 agent 需要 memory hygiene

這堂課最後從一次性的 agent，走向長期運作的 agent。

深色 blueprint-style 圖，說明 Memory hygiene，包含簡短英文標籤與高對比技術幾何。
Long-lived agents 需要 memory hygiene，而不只是更多 memory。

長期運作的 agent 需要 memory，但 memory 不會自動變好。它可能重複、過期、互相矛盾，或大到無法使用。這堂課提到 memory consolidation 與 AutoDream 類似的行為：agent 利用閒置時間整理自己的筆記。

這正是我會期待 personal agent 需要的東西。

如果一個 agent 跟我一起工作好幾個月，我不希望它只是累積 log。我希望它把經驗壓縮成可重用的 skill、project convention 和 preference。我也希望它忘記或封存已經不重要的細節。

有用的 memory system 需要 garbage collection。

skill 是結晶化的經驗

skill.md 這個想法，是這堂課最實用的部分之一。

深色 blueprint-style 圖，說明 Skills crystallize experience，包含簡短英文標籤與高對比技術幾何。
Skill 是結晶化的經驗：從已解決問題抽出的 reusable procedure。

如果 agent 學會怎麼做某件事，它不應該每次都重新發現流程。它可以把程序寫成 skill：何時使用、要跑哪些 command、預期會遇到什麼 error，以及如何驗證成功。

這是一種低科技的 continual learning。model weights 沒有改變，但系統變好了，因為 harness 現在包含可重用的程序。

我喜歡這點，因為它可稽核。fine-tuned behavior 很難檢查。skill file 可以被閱讀、編輯、versioned，也可以刪除。

評估 agent 比看起來更難

這堂課也提醒我們，小心那些用 LLM 模擬人類或評判輸出的 agent benchmark。

深色 blueprint-style 圖，說明 Evaluating agents is hard，包含簡短英文標籤與高對比技術幾何。
Agent evaluation 很難，因為 benchmark 常常也是另一個 fragile system。

LLM customer 往往太樂於幫忙。它們解釋得很清楚、回答得很有禮貌，還會提供真實使用者可能省略的資訊。LLM judge 也可能高估互動品質。

這代表 benchmark 可能讓 agent 看起來比實際更好。

真實人類很混亂。他們給不完整的回答。他們會改變心意。他們沒耐心。他們會誤解問題。如果 agent 只在合作的模擬使用者面前能運作，到了野外可能就會失敗。

這是一個反覆出現的主題：evaluation 是 harness 的一部分。

Meta-harness

這堂課以一個遞迴想法收尾：更強的 model 可以替較弱的 model 設計 harness。

深色 blueprint-style 圖，說明 Meta-harnesses，包含簡短英文標籤與高對比技術幾何。
Meta-harnesses 用更強 models 設計系統，讓較弱 models 變得有用。

這不是科幻。它已經很合理。一個強 model 可以檢查 failure、編輯 agent.md、加入 workflow rules，並改善較弱 agent 的 benchmark score。

這是通往 self-improving system 的重要橋梁。在 AI 重寫自己的 weights 之前，它可能先重寫自己的 scaffolding。這更容易檢查，也更安全地迭代，但仍然很強大。

Harness improvement 可能是第一種實用的 agent self-improvement。

核心教訓

我能從這堂課萃取出的最好一句話是：不要把 model failure 和 system failure 混在一起。

深色 blueprint-style 圖，說明 The main lesson，包含簡短英文標籤與高對比技術幾何。
不要把 model failure 和 system failure 混在一起。

當 agent 失敗時，問：

如果沒有，model 可能不是瓶頸。

Harness engineering 是那個不性感的 layer，它把 language model 變成你真的可以委派工作的東西。

概念清單

這堂課的主要 harness engineering 概念：

來源與參考資料

本文主要觀看的來源：