拆解 Agent Harness — 你以為的 AI Agent 其實 90% 是 harness

最近在看 LangChain 的 blog，有一篇 The Anatomy of an Agent Harness 講得很直白，其中一句話我覺得值得截圖貼牆壁：

"If you're not the model, you're the harness."

所謂的 AI Agent，其實大部分人在做的事情不是在訓練模型、不是在調 inference，而是在寫 harness。你以為你在做 AI，其實你在做工程。

Harness 到底是什麼

簡單說，Agent = Model + Harness。Model 就是那顆 LLM，你換個 API key 就換掉了。Harness 是其他所有東西：

• System prompt：你怎麼跟模型說它是誰、能做什麼
• Tools / MCPs：給模型的武器庫
• Orchestration logic：spawn subagent、handoff 給別的 agent、retry 邏輯
• Middleware / hooks：context compaction、validation、continuation
• Sandbox / 執行環境：安全隔離、filesystem 存取、bash 執行

把這個清單看一遍，你會發現跟寫一個後端服務沒什麼本質差異，只是多了一個「中間有個 LLM 在做決策」的環節。

我自己的 harness 長什麼樣

BridgeCraft 裡面有一個 agent 系統，結構大概是這樣：globalRegistry 管理所有 agent，每個 agent 定義自己的 inputSchema 跟 execute function。目前跑的有 content-distributor、trend-scout、content-recycler 這幾個。

老實說這個系統寫下來，時間分布大概是這樣：

• 模型呼叫本身：20%（就是 anthropic.messages.create()，幾行而已）
• Harness 的其他部分：80%（prompt 設計、錯誤處理、retry、排程、資料流、結果驗證）

每次有個 agent 行為不符合預期，問題幾乎都不在模型，而是 prompt 設計不清楚、output schema 沒有約束好、或是拿到的 context 根本不夠完整。這就是 harness 的問題，跟換不換 Claude 4、GPT-5 沒有太大關係。

Claude Code 本身就是一個教科書級的 harness

如果你現在在用 Claude Code（就是你正在看這篇的那個工具），它本身就是一個非常好的 harness 範例可以拆解：

• Tools：Read、Edit、Bash、Grep、Glob，每個都是定義清楚的 primitive
• Skills：更高層的 orchestration 單元，可以組合 tools 完成複雜任務
• Compaction：context window 有限，長對話會壓縮舊 context 保留關鍵資訊（原文叫 context rot，很傳神）
• Git integration：跨 context window 的狀態追蹤，用 git diff 知道現在做到哪

這就是 LangChain 文章提到的 long-horizon execution，靠 filesystem + git 讓 agent 可以跨越單一 context window 做事情。你看，同一個 model（Claude），在不同 harness 裡的表現差異很大，這就是 model-harness co-evolution 的概念。

Harness 的核心 primitives 值得單獨討論

文章裡點出幾個 harness 必備的 primitive，我覺得確實是精華：

Filesystem + Git：這是持久狀態的最小單元。Agent 做到一半 context 爆了？git stash 一下，重新 spawn 一個 agent 繼續。這不是 hack，這是設計。

Bash / Code execution：給模型一台電腦，讓它自己去試。這是從 ChatGPT 的 Code Interpreter 就開始的概念，但重要性被低估了。能執行代表能驗證，能驗證代表 feedback loop 可以成立。

Sandbox：安全隔離。你不會想要一個 agent 亂 rm -rf 吧，sandbox 就是護欄。

Context management / Compaction：這個最常被忽略。長任務跑下去，context 會開始「腐爛」，舊的、不相關的資訊佔據 window，模型開始亂。Compaction 就是定期清理，把重要的提煉出來，繼續跑。

設計哲學：從 desired behavior 反推

這個我覺得最實用。不要從「我有什麼工具」開始設計，要從「我希望 agent 最後做出什麼行為」開始，然後反推需要哪些 harness 元件。

比如我希望 trend-scout 能每週找出 AI 領域的熱門話題、自動草擬文章大綱，那我需要的 harness 就是：search tool、一個 output schema 定義大綱格式、一個 validation step 確保輸出不是垃圾、一個排程觸發機制。反過來設計，不要堆砌工具。

結論

你現在在做的 AI Agent 工程，本質上是 harness 工程。模型就那幾行呼叫，剩下的都是你在寫。這不是壞事，這代表你的工程能力直接決定 agent 的上限。

下次有人說「我在做 AI Agent 開發」，可以心裡默默對照一下：你在設計 harness，還是只是在換 system prompt？

<h2>延伸閱讀</h2> <ul> <li><a href="/blog/building-nextjs-for-an-agentic-future">Building Next.js for an agentic future</a></li> <li><a href="/blog/coding-agents-reshaping-epd">Coding Agent 正在改變工程、產品、設計的協作方式 — 但改變的不是你想的那個</a></li> <li><a href="/blog/how-we-monitor-internal-coding-agents-for-misalignment">How we monitor internal coding agents for misalignment</a></li> </ul>