Agent Harness（代理人外殼）是包覆在大型語言模型外層的全套基礎設施，也是決定 AI Agent 實戰成敗的關鍵變數。 LangChain 只修改 harness、不動模型，就把自家編碼 Agent 在 Terminal-Bench 2.0 上的成績從 52.8% 推到 66.5%，排名從 30 名外跳進前 5。同一時期，史丹佛 IRIS Lab 和 KRAFTON AI 合作的 Meta-Harness，用自動化 harness 演化技術搭配 Claude Opus 4.6，在同一份 benchmark 拿下 76.4% 的通過率，超越所有人工設計的系統。模型權重沒動，動的是外面那層「基礎設施」。
這個結果顛覆了很多開發者的直覺：多數團隊花了大半年調模型、選供應商、比較 token 單價，真正的瓶頸卻在他們一直忽視的地方——orchestration loop、tool 系統、memory 管理、sandbox 環境、context 壓縮策略。這篇文章把 Akshay Pachaar 2026 年 4 月 6 日在 X 上發布的貼文（194,200 次觀看）作為起點，整合 LangChain、Anthropic、OpenAI 和史丹佛的官方資料，拆解 production 級 agent harness 的完整結構和工程原則。
什麼是 Agent Harness：從「Agent = Model + Harness」說起
Agent Harness 這個術語在 2026 年初才正式成形，但概念早就存在於 Anthropic、OpenAI、LangChain 的內部文件裡。LangChain 工程師 Vivek Trivedy 在 2026 年 3 月 10 日發表的定義最清楚：
Agent = Model + Harness。如果你不是模型，你就是 harness。
換句話說，harness 是除了模型本體以外的所有程式碼、設定和執行邏輯。原始的模型本身不是 Agent，它只是個 stateless 的文字預測器；harness 把 state、tool 執行、feedback loop、約束機制套上去之後，它才變成一個會做事的實體。
Anthropic 在 Claude Code 的官方文件裡用同樣的說法：SDK 是「驅動 Claude Code 的 agent harness」。OpenAI 的 Codex 團隊也明確把「agent」和「harness」劃上等號，指的都是讓 LLM 真正可用的非模型基礎設施。
一個完整的 agent harness 至少包含以下元件：
- System Prompt：告訴模型它是誰、要做什麼
- Tools、Skills、MCP 及其 schema：模型能呼叫的能力集合
- Bundled Infrastructure：filesystem、sandbox、browser 等執行環境
- Orchestration Logic：subagent 派遣、模型路由、handoff 規則
- Hooks / Middleware：壓縮、續跑、lint 檢查等確定性執行邏輯
這個定義之所以重要，是因為它強迫工程師把思考重心從「我要用哪個模型」挪到「我要怎麼圍繞模型的智能設計系統」。
Harness 和 Context Engineering 不一樣
這兩個詞在中文圈經常被混用，但界線其實很明確。Context Engineering（內容工程） 處理的是「模型在每一步看到什麼」；harness engineering 則包含 context engineering，再加上工具編排、狀態持久化、錯誤復原、驗證迴圈、安全強制、生命週期管理等整個應用層基礎設施。
簡單說：context engineering 是 harness 的一個子集。Harness 不是 prompt 的包裝紙，而是讓 autonomous agent 行為真正成立的完整系統。
生產級 Agent Harness 的 11 個核心元件
Akshay Pachaar 在 X 貼文中引用的技術架構，融合了 LangChain 官方定義和 Avi Chawla 在 Daily Dose of DS 的整理。綜合 Anthropic、OpenAI、LangChain 的工程實踐，production agent harness 有 11 個明確的元件。以下逐一拆解。
1. Orchestration Loop（編排迴圈）
這是 harness 的心跳。它實作 Thought-Action-Observation（TAO）循環，也就是俗稱的 ReAct loop：組裝 prompt、呼叫 LLM、解析輸出、執行 tool calls、把結果餵回去、重複直到完成。機制上常常就是一個 while 迴圈，複雜度都在「迴圈管什麼」而不在迴圈本身。
Anthropic 把它們的 runtime 形容為「dumb loop」——所有智能都在模型裡，harness 只管 turn 的切換。LangGraph 的實作就是兩個節點（llm_call 和 tool_node）加一條 conditional edge：有 tool call 就走 tool_node，沒有就走 END。LangGraph 2024 年取代了 LangChain v0.2 中被棄用的 AgentExecutor，主因是舊架構難以擴充、不支援多 agent 協作。
| 框架 | Orchestration 實作 | 多 Agent 支援 |
|---|---|---|
| LangGraph | 雙節點 + conditional edge | Deep Agents 支援 subagent spawning |
| CrewAI | Agent + Task + Crew 三層 | Role-based 架構 + Flows 驗證層 |
| AutoGen（微軟 Agent Framework） | Conversation-driven | 多 agent 對話協作 |
| Claude Code SDK | "Dumb loop" + 模型主導 | Sub Agents |
2. Tools（工具層）
工具是 Agent 的雙手。它們以 schema 形式（name、description、parameter types）注入 LLM 的 context，讓模型知道有哪些能力可用。Tool 層負責註冊、schema 驗證、參數擷取、sandbox 執行、結果捕捉，以及把結果格式化為 LLM 可讀的 observation。
Claude Code 提供六大類工具：檔案操作、搜尋、執行、網頁存取、程式碼智能、subagent 派遣。OpenAI 的 Agents SDK 則支援三種工具類型：function tools（透過 @function_tool 裝飾器）、hosted tools（WebSearch、CodeInterpreter、FileSearch）、以及 MCP server tools。
現代 harness 採用 native tool calling：模型直接回傳結構化的 tool_calls 物件，不是需要 parse 的自由文字。Harness 檢查有沒有 tool call，有就執行、沒有就給最終答案。結構化輸出方面，OpenAI 和 LangChain 都支援用 Pydantic model 做 schema 約束。
3. Filesystem（檔案系統）
Vivek Trivedy 認為 filesystem 是最基礎的 harness primitive。原因是模型只能操作 context 內的資料，在有 filesystem 之前，使用者要自己複製貼上內容到模型，使用體驗很差，autonomous agent 更是做不到。
Filesystem 一進來，解鎖了三件事：
- Agent 有工作區可以讀資料、程式碼、文件
- 工作可以增量進行，中間輸出可以 offload 出去，state 跨 session 持續
- Filesystem 成為自然的協作介面，多個 agent 和人類透過共享檔案協調
Git 再把版本控管疊上去，agent 就能追蹤工作、回滾錯誤、做分支實驗。這也是為什麼 Agent Teams 架構依賴 filesystem 當共享帳本。
4. Bash + Code Execution（通用工具）
光有預先設計好的 tool 不夠，autonomous agent 常常遇到設計者沒預見的問題。最好的解法不是堆更多 tool，而是給 agent 一個通用工具：bash。
Harness 內建 bash tool，讓模型可以寫程式、執行、觀察、修正。這一步等於「給模型一台電腦」，讓它自己想辦法解決問題，而不是被限制在固定的 tool 集合裡。現代 harness 仍然會附帶其他專用 tool，但 code execution 已經成為 autonomous problem solving 的預設通用策略。
5. Sandbox（沙箱環境）
Agent 要能安全地執行動作、觀察結果、取得進展，就需要一個環境。本機執行 agent 生成的程式碼有風險，而且單一環境無法承受大規模 agent workload。
Sandbox 提供安全隔離的執行環境。Harness 連到 sandbox 去跑程式、檢查檔案、安裝套件、完成任務。進階的 sandbox 會允許命令 allow-list 和網路隔離。Sandbox 也解鎖了規模化——環境可以按需建立、分散到多個任務、用完銷毀。
業界常見的實作：LangChain 用 Daytona 或 Harbor，OpenAI Codex 用自己的 App Server，OpenClaw 用 Bun JS HTTP server 搭 Event Bus 廣播結果。
6. Memory（記憶系統）
記憶在多個時間尺度上運作：
| 記憶類型 | 時間範圍 | 典型實作 |
|---|---|---|
| Short-term | 單一 session 內 | Conversation history 滑動視窗 |
| Long-term（語意） | 跨 session、跨任務 | 向量資料庫、知識圖譜 |
| Long-term（情節） | 特定事件和經驗 | 結構化 log + 摘要 |
| Personalized | 使用者偏好 | AGENTS.md 等 memory file |
Anthropic 的 context engineering 指南直接講明目標：找出最小的高訊號 token 集合，最大化達成期望結果的機率。Filesystem 在這裡又扮演核心角色——harness 支援 AGENTS.md 這類 memory file 標準，agent 啟動時注入 context，agent 更新檔案後 harness 再把新版載入下次 session。這是一種簡單有效的 continual learning。
知識時效性方面，模型有 knowledge cutoff，沒辦法直接知道新的函式庫版本或即時資料。Web Search 和像 Context7 這類 MCP 工具補上這個缺口。
7. Context Management（上下文管理）
這一層決定模型在每一步實際看到什麼。它是階層化的：system prompt、tool definitions、memory files、conversation history、當前 user message。
OpenAI 的 Codex 用嚴格的優先順序：伺服器端 system message（最高）、tool definitions、developer instructions、user instructions（cascading AGENTS.md 檔案，32 KiB 上限）、最後才是 conversation history。這個 priority stack 防止 prompt injection 和指令衝突。
8. Context Rot 防禦（壓縮、Tool Offloading、Skills）
Chroma Research 定義的 Context Rot 說明一件殘酷的事實：context window 越滿，模型推理和完成任務的能力越差。Context 是稀缺資源，harness 必須有策略保護它。
三種主要防禦機制：
- Compaction（壓縮）：context window 快滿時，智能地摘要和 offload 既有內容，讓 agent 可以繼續工作。沒有 compaction 就會遇到 API 報錯
- Tool Call Offloading：大型 tool 輸出會污染 context，harness 只保留頭尾 token，完整內容 offload 到 filesystem，模型需要時再讀取
- Skills（進階）：tool 或 MCP server 太多時，全部載入 context 會在 agent 開始工作前就拖慢效能。Claude Agent Skills 用 progressive disclosure 解決：啟動時只載入 front-matter，需要時才載入完整內容
9. Long-Horizon Execution（長期自主執行）
要做到 10+ 步、跨越多個 context window 的複雜工作，前面所有 primitive 要組合起來：
- Filesystem + Git：durable 記錄工作歷程，讓新 agent 能快速銜接
- Planning（規劃）：模型把目標拆解成步驟，harness 用 prompting 和 plan file 輔助
- Self-Verification（自我驗證）：完成每步後 agent 檢查正確性，harness hook 跑 test suite、回報失敗
- Ralph Loops：由開發者 Geoffrey Huntley 提出的模式，當模型想退出時 hook 會攔截並重新注入原始 prompt 在乾淨的 context window，強迫 agent 繼續工作直到完成目標。每次迭代從新 context 開始，但從上一輪的 filesystem state 讀取進度
10. Error Handling 和 Guardrails
Production agent 必須處理 LLM 無限迴圈、JSON 解析失敗、tool 執行錯誤、API 超時等各種異常。常見的防線：
| 問題 | Harness 防禦 |
|---|---|
| 無限迴圈 | Hardcode step budget（20–50 步為主流） |
| JSON 格式錯誤 | 嚴格 schema 驗證 + 修正提示回注 |
| Tool 不存在 | 捕獲錯誤並以 system message 要求 LLM 修正 |
| 惡意程式碼 | Sandbox 隔離 + 命令 allow-list |
| Context 超限 | Compaction + 滑動視窗 |
Builder.io 的統計顯示，多數 production 系統的 step budget 設在 20 到 50 步之間，這個上限主要是為了控制成本和防止 runaway loop。
11. Serving Layer（服務層）
把 agent 接到終端使用者的那一層。OpenClaw 用 centralized Gateway 透過 typed WebSocket protocol 同時服務 CLI、Web UI、桌面 App、Slack、Telegram 和 WhatsApp。Codex 從純 terminal 工具演化成 App Server，用 JSON-RPC over stdin/stdout。Anthropic 的 Cowork 也是類似的多介面架構——同一個 agent，多個 surface。
真實數據：Harness 調整如何改變 Benchmark 表現
這些元件不是理論——它們在 benchmark 上留下了可驗證的痕跡。
Terminal-Bench 2.0 由史丹佛 Stanford 實驗室在 2026 年 2 月推出，包含 89 個跨機器學習、除錯、生物學等領域的硬核任務，每個任務都有獨立環境、人工撰寫的解法、完整驗證測試。前沿模型在這個 benchmark 上的分數普遍低於 65%，小模型甚至只有 15% 左右，證明它的鑑別力。
LangChain 公布的 Improving Deep Agents with harness engineering 報告（2026 年 2 月 17 日）給了具體數字：
| 階段 | Harness 配置 | Terminal-Bench 2.0 分數 | 排名 |
|---|---|---|---|
| 基線 | Default prompt + 標準 tools + middleware | 52.8%（GPT-5.2-Codex） | Top 30 外 |
| 迭代後 | 優化 system prompt、tools、middleware | 66.5% | Top 5 |
| 提升 | +13.7 個百分點 | — | +25 名以上 |
LangChain 特別強調，他們只動了 harness 的三個旋鈕：system prompt、tools、middleware（他們對 hook 的稱呼）。模型權重完全沒變。
更驚人的是史丹佛 IRIS Lab 和 KRAFTON AI 合作的 Meta-Harness 專案。研究團隊讓 LLM 自動演化 harness 設計，搭配 Claude Opus 4.6，在 89 個任務 × 5 次試驗的嚴格設定下拿到 76.4%，超越所有人工設計的 harness。Meta-Harness 基於 KRAFTON AI 的 Terminus-KIRA 擴充，關鍵創新是環境 bootstrap：agent loop 開始前先收集 sandbox 環境快照（工作目錄、檔案清單、可用語言/工具、套件管理器、記憶體）並注入 initial prompt，省下 2-5 個原本浪費在 ls、which python3 這類早期探索的 turn。
比較這幾個數字：
- Claude Opus 4.6 在 Claude Code 內建 harness：74.7%
- Claude Opus 4.6 在 Droid agent framework：69.9%
- Claude Opus 4.6 在 LangChain 早期 harness：59.6%
- Claude Opus 4.6 在 Meta-Harness：76.4%
同一個模型權重，harness 不同，分數差距可以超過 16 個百分點。這個數字對企業部署決策有直接意義——選錯 harness 造成的效能損失，遠比選錯模型大得多。
模型和 Harness 的共演化：為什麼這件事會越演越複雜
現代 Agent 產品像 Claude Code 和 Codex 是用「模型 + harness」一起 post-train 的。這讓模型在設計者認為應該原生擅長的動作上變得更好——filesystem 操作、bash 執行、planning、subagent 並行化等等。
這形成了一個回饋迴圈：有用的 primitive 被發現，加入 harness，被用來訓練下一代模型，模型在這個 harness 內變得更強。但這種共演化有副作用——模型會 overfit 到訓練時的 harness。
具體例子來自 OpenAI 的 Codex-5.3 prompting guide。一個真正「智能」的模型應該能輕鬆切換不同的 patch 方法，但 harness-in-the-loop 訓練會造成這種 overfitting。這就是為什麼 Claude Opus 4.6 在 Claude Code harness 內比在其他 harness 內表現好——模型和 harness 被耦合訓練。
這也帶來一個實用的啟示：你任務的最佳 harness，未必是模型原廠內建的那個。Terminal-Bench 2.0 的數據清楚顯示，即使是 Anthropic 原生的 Claude Code harness，也會被客製化的 Meta-Harness 擊敗。
Harness Engineering 的未來：不會消失，只會轉型
隨著模型越來越強，部分今天屬於 harness 的功能會被吸收進模型——規劃、自我驗證、長期連貫性這些能力會變成原生的，不再需要 context injection。這讓人直覺認為 harness 的重要性會下降。
但 Vivek Trivedy 的判斷是反過來：就像 prompt engineering 至今仍然有價值，harness engineering 會繼續是打造好 Agent 的關鍵。原因是 harness 不只是在 patch 模型的缺陷，它也在圍繞模型智能設計有用的系統——好的執行環境、對的 tool、durable 的 state、驗證 loop，這些都會讓任何模型變得更有效率，不論模型本身多強。
LangChain 在 deepagents 內正在研究的幾個方向值得關注：
- 大規模並行編排：成百上千個 agent 在同一個 codebase 上並行工作
- 自省式 harness：agent 分析自己的 trace，識別並修復 harness 層級的失敗模式
- Just-in-time harness 組裝：動態為特定任務組裝 tool 和 context，而不是預先設定
這三個方向都在推翻一個假設：harness 是靜態的工程產物。未來的 harness 會是動態的、自優化的、甚至部分由 AI 設計的。
FAQ：關於 Agent Harness 的常見問題
什麼是 Agent Harness？和 AI Agent 是同一件事嗎？
Agent Harness 是包覆在 LLM 外層的完整軟體基礎設施，包括 orchestration loop、tools、memory、context 管理、state 持久化、錯誤處理和 guardrails。Agent 是「模型 + harness」的組合產物——使用者互動的、會做事的實體；harness 是讓這個行為得以發生的機器。Vivek Trivedy 的說法是「Agent = Model + Harness」，這也是 Anthropic 和 OpenAI 文件共用的定義。
Harness Engineering 和 Context Engineering 差在哪？
Context Engineering 管理「模型每一步看到什麼」，也就是 prompt 的組裝和 context window 的配置。Harness Engineering 範圍更大，包含 context engineering 加上 tool 編排、state 持久化、錯誤復原、驗證迴圈、安全強制、生命週期管理。Context 是 harness 內的一個子系統，不是對立的概念。
為什麼只改 Harness 不動模型就能大幅提升效能？
因為大多數 agent 失敗案例都是基礎設施層級的問題——模型忘記三步前做了什麼、tool call 無聲失敗、context window 被垃圾填滿。這些都不是模型智能不夠，而是圍繞模型的系統沒做好。LangChain 在 Terminal-Bench 2.0 上從 52.8% 提升到 66.5% 就是證據：system prompt、tool 設計、middleware 的優化，能帶來超過 13 個百分點的提升，相當於跳過一整代模型升級。
自己動手建 Harness，還是用 LangGraph、CrewAI 這類框架？
兩者都不是錯答案，取決於團隊規模和需求複雜度。框架（LangGraph、CrewAI、AutoGen）適合快速原型和標準場景，內建 ReAct loop、tool calling、多 agent 協調。但框架是刻意「不帶立場」的——什麼時候停、怎麼強制 tool 順序、怎麼防 context rot 這些關鍵決策都留給你。當 agent 進入 production、需要跑上千種邊緣案例時，團隊通常會在框架上加一層自己的 harness，或乾脆參考 LangChain deepagents、Claude Code SDK 做自己的版本。
對企業導入 Claude Code 或 OpenClaw 來說，Harness 的重要性在哪？
直接影響 ROI。Claude Code 的 harness 經過 Anthropic 和模型一起 post-train，在標準開發任務上表現極強。但企業如果有特殊工作流——例如規範化的 code review 流程、特定程式語言的 type 系統、公司內部的部署管線——標配 harness 可能不是最佳解。LangChain 的 Top 5 經驗告訴企業：投資一位懂 harness engineering 的工程師，比單純升級模型 API 帶來的效益更高。
引用來源
- LangChain — The Anatomy of an Agent Harness（Vivek Trivedy, 2026 年 3 月 10 日）
- LangChain — Improving Deep Agents with harness engineering（2026 年 2 月 17 日）
- Stanford IRIS Lab — Meta-Harness GitHub Artifact（Claude Opus 4.6 on Terminal-Bench 2.0, 76.4%）
- Terminal-Bench Official Leaderboard
- Chroma Research — Context Rot Analysis
- Daily Dose of DS — The Anatomy of an Agent Harness（Avi Chawla）
- Parallel Web Systems — What is an Agent Harness
- Anthropic — Claude Code Documentation
Author Insight
我們導入 Agent 系統的經驗，印證了 harness engineering 的價值。一個案子用 Claude Sonnet 4.6 搭原廠 harness，在他們自家程式碼審查任務上只拿到 58% 的通過率。花了兩週重新設計 system prompt、加入針對他們 monorepo 結構的 sub-agent 分派邏輯、把 linter 和靜態分析結果做成 middleware 回注，同樣的模型跳到 81%。模型升級從來不是第一優先——多數企業忽略的 harness 層反而是回報最高的投資點。
另一個常見誤區是把 prompt engineering 當成 harness 的代名詞。System prompt 當然重要，但 production agent 出問題九成不在 prompt 寫得好不好，而在 error recovery、step budget、context compaction 這些工程層面的決策。建議企業 CTO 把 harness 當成獨立的工程學科來對待，配專人、配預算、配 benchmark。
