先做最小的 harness,遇到問題再加零件
深讀 L3 1,223 字 3 分鐘 v2.0.0 更新 2026-11-16
harness 是模型外圍的工作環境。最小版本是迴圈加上讀檔、寫檔、改檔與執行指令的工具,其餘零件遇到問題再加。
組裝時要分清楚:哪些資料在啟動時讀入,哪些處理每輪都做,哪些檢查必須擋在執行之前。
啟動時,先準備規則與工具
context 是一次請求送給模型的全部內容,包含工具定義、系統指示與對話。組成與重送方式見 context 的組成。
實作可照 Thorsten Ball 的文章,先寫出迴圈與三個工具,再依序加入規則檔、權限檢查與壓縮。權限檢查擋在工具之前,壓縮則在 context 太長時執行。每個零件只解決一個問題,出問題時就能判斷該調整哪一個。
harness 啟動時讀入規則檔,把規則放在 context 前段。範例以 read("AGENTS.md") 讀取內容,存入 system。
規則檔的名稱取決於使用的環境。Claude Code 讀取的檔案與放置方式見 CLAUDE.md;這份自製 harness 範例則明確指定 AGENTS.md。
工具以名稱、說明與參數格式描述,格式見 工具呼叫的格式。工具可以由內建函式提供,也可以來自提供工具的 MCP server,連接方式見 MCP。
下圖把五個零件放在同一張圖裡,對照規則的入口、迴圈與模型的往返,以及工具前方的權限檢查。
迴圈是中心。其他零件都接在迴圈上。
每輪請求前檢查長度,收到回覆後判斷是否執行
負責問模型、執行工具並送回結果的主迴圈,見 Agent Loop。接上其他零件時,要把處理放進這個迴圈的正確位置。
範例先用 messages = [user(task)] 放入任務。每輪呼叫模型之前,harness 先執行 maybe_compact(messages),在 context 太長時壓縮內容。
接著,model(system, tools, messages) 接收規則、工具與對話。模型回覆後,harness 用 messages.append(reply) 把回覆加入對話。
工具呼叫是模型提出工具名稱與參數、交由 harness 執行的請求,詳見 工具呼叫。範例檢查 reply.tool_calls;沒有請求時,就回傳 reply.text。
下圖用偽程式碼標出各零件接入的位置。這是教學用的玩具範例,沒有附上各函式的完整實作,不能直接當成可執行的產品。
啟動時讀入規則檔,之後每一輪都不變。
權限檢查必須在工具執行之前
模型提出請求後,harness 逐一執行 gate(call)。回傳 REFUSE 時,harness 將 refused(call) 加入結果;否則才執行 run_tool(call)。
沙箱由作業系統限制程式可讀寫的檔案與可連線的網路,詳見 沙箱。規則檔只是提醒;需要限制可寫入目錄時,應由沙箱約束範圍。
規則太長與過程難查時,資料該放哪裡
規則檔太長時,可以採用 OpenAI 團隊的做法:讓 AGENTS.md 當目錄,把細節放進 docs 資料夾。啟動時載入的檔案因此負責提供入口。
另外,把每次請求、工具呼叫與結果寫成程式執行紀錄,詳見 log。出問題時,沿著紀錄找出偏離任務的那一輪,再判斷該調整哪個零件。
按錯誤發生的位置調整零件
模型選錯工具或填錯參數時,先檢查工具名稱與說明。改寫說明之後,再考慮合併功能重疊的工具。
長對話開始偏離任務,或壓縮後遺失先前決定時,檢查壓縮處理。context 會被壓縮,檔案不會,因此把計畫與決定寫進檔案,長輸出也存成檔案,只回傳路徑。
若 agent 執行不能復原的指令,或修改任務範圍外的檔案,就檢查權限規則。加入拒絕或詢問條件,並限制可寫入的目錄。
下圖可切換這三類錯誤,對照現象與要調整的零件。
現象
- 模型呼叫了不適合的工具
- 或是填錯參數
調整的零件
- 工具:改寫名稱與說明
- 合併功能重疊的工具
來源
- How to Build an Agent Thorsten Ball
- learn-harness-engineering walkinglabs
- Harness engineering: leveraging Codex in an agent-first world Ryan Lopopolo, OpenAI
- What I learned building an opinionated and minimal coding agent Mario Zechner
- Agent SDK overview Claude Code docs
- Continually improving our agent harness Cursor
- AGENTS.md agents.md