Agent Harness 的解剖學
Agent Harness 的解剖學
深入探討 Anthropic、OpenAI、Perplexity 和 LangChain 實際上在建構什麼。本文將涵蓋編排迴圈 (orchestration loop)、工具 (tools)、記憶 (memory)、context 管理，以及所有將無狀態 (stateless) LLM 轉變為強大 Agent 的關鍵要素。
你已經建構了一個聊天機器人。也許你用幾個工具串接了一個 ReAct 迴圈，這在展示時運作良好。但當你嘗試建構生產等級的系統時，問題就接踵而至：模型忘記了三步前做了什麼、工具呼叫失敗卻沒有任何提示、context 視窗被垃圾資訊填滿。
問題不在於你的模型，而在於模型周圍的一切。
LangChain 證明了這一點：當他們僅僅更換了包裹 LLM 的基礎設施（模型相同、權重相同）後，在 TerminalBench 2.0 的排名就從 30 名開外躍升至第 5 名。另一個獨立研究專案透過讓 LLM 自行優化基礎設施，達到了 76.4% 的通過率，超越了人工設計的系統。
這種基礎設施現在有一個名字：Agent harness。
什麼是 Agent Harness？
這個術語在 2026 年初被正式化，但其概念早已存在。Harness 是包裹 LLM 的完整軟體基礎設施：編排迴圈、工具、記憶、context 管理、狀態持久化、錯誤處理和防護機制 (guardrails)。Anthropic 的 Claude Code 文件簡單地說明：SDK 就是「驅動 Claude Code 的 Agent harness」。OpenAI 的 Codex 團隊也使用相同的框架，明確將「Agent」和「harness」等同起來，用以指代那些讓 LLM 變得實用的非模型基礎設施。
我非常喜歡 LangChain 的 Vivek Trivedy 提出的經典公式：「如果你不是模型本身，那你就是 harness。」
這裡有一個讓許多人混淆的區別。「Agent」是湧現出的行為：使用者與之互動的、目標導向的、使用工具的、自我修正的實體。而 Harness 則是產生這種行為的機器。當有人說「我建構了一個 Agent」時，他們的意思是他們建構了一個 harness 並將其指向一個模型。
Beren Millidge 在他 2023 年的文章《Scaffolded LLMs as Natural Language Computers》中精確地類比了這一點。原始的 LLM 就像是一台沒有記憶 (RAM)、沒有硬碟、沒有 I/O 的 CPU。Context 視窗充當了記憶（速度快但有限）；外部資料庫充當了硬碟儲存（容量大但速度慢）；工具整合則充當了裝置驅動程式。而 Harness 就是作業系統。正如 Millidge 所寫：「我們重新發明了馮·紐曼架構」，因為這是任何計算系統的自然抽象。
三個工程層級
圍繞著模型的有三個同心工程層級：
Prompt 工程：精心設計模型接收的指令。
Context 工程：管理模型何時看到什麼內容。
Harness 工程：涵蓋上述兩者，外加整個應用程式基礎設施：工具編排、狀態持久化、錯誤復原、驗證迴圈、安全性強制執行以及生命週期管理。
Harness 並非 Prompt 的封裝，它是使自主 Agent 行為成為可能的完整系統。
生產環境 Harness 的 12 個組件
綜合 Anthropic、OpenAI、LangChain 以及更廣大的從業者社群，一個生產環境的 Agent harness 包含十二個不同的組件。讓我們逐一檢視。
1. 編排迴圈 (The Orchestration Loop)
這是心臟。它實作了「思考-行動-觀察」(Thought-Action-Observation, TAO) 週期，也稱為 ReAct 迴圈。迴圈運作方式：組裝 Prompt、呼叫 LLM、解析輸出、執行工具呼叫、將結果回饋給模型、重複直到完成。
從技術上講，它通常只是一個 while 迴圈。複雜性在於迴圈所管理的一切，而不是迴圈本身。Anthropic 將他們的執行時期描述為一個「笨迴圈」(dumb loop)，所有的智慧都存在於模型中，harness 僅負責管理輪次。
2. 工具 (Tools)
工具是 Agent 的雙手。它們被定義為注入 LLM context 中的 Schema（名稱、描述、參數類型），讓模型知道有哪些可用功能。工具層負責註冊、Schema 驗證、參數提取、沙盒執行、結果擷取，並將結果格式化為 LLM 可讀的觀察結果。
Claude Code 提供了六個類別的工具：檔案操作、搜尋、執行、網路存取、程式碼智慧和子 Agent 產生。OpenAI 的 Agents SDK 支援函式工具 (透過 @function_tool)、託管工具 (WebSearch、CodeInterpreter、FileSearch) 以及 MCP 伺服器工具。
3. 記憶 (Memory)
記憶在多個時間尺度上運作。短期記憶是單次對話中的歷史紀錄。長期記憶則跨越會話持久存在：Anthropic 使用 CLAUDE.md 專案檔案和自動產生的 MEMORY.md 檔案；LangGraph 使用命名空間組織的 JSON Stores；OpenAI 支援由 SQLite 或 Redis 支援的 Sessions。
Claude Code 實作了三層階級：輕量級索引（每個條目約 150 個字元，始終載入）、按需提取的詳細主題檔案，以及僅透過搜尋存取的原始文字紀錄。一個關鍵的設計原則是：Agent 將自己的記憶視為「提示」，並在行動前針對實際狀態進行驗證。
4. Context 管理 (Context Management)
這是許多 Agent 默默失敗的地方。核心問題是 context 腐敗：當關鍵內容落在視窗中間位置時，模型效能會下降 30% 以上（Chroma 研究，史丹佛大學的「Lost in the Middle」發現也證實了這一點）。即使是百萬 token 的視窗，隨著 context 增長，指令遵循能力也會下降。
生產環境的策略包括：
壓縮 (Compaction)：在接近限制時總結對話歷史（Claude Code 會保留架構決策和未解決的 Bug，同時捨棄冗餘的工具輸出）。
觀察遮罩 (Observation masking)：JetBrains 的 Junie 會隱藏舊的工具輸出，同時保持工具呼叫可見。
即時檢索 (Just-in-time retrieval)：維護輕量級識別碼並動態載入資料（Claude Code 使用
grep、glob、head、tail而不是載入完整檔案）。子 Agent 委派 (Sub-agent delegation)：每個子 Agent 進行廣泛探索，但僅返回 1,000 到 2,000 個 token 的精簡摘要。
Anthropic 的 context 工程指南指出目標：找到最小可能的高訊號 token 集合，以最大化達成預期結果的可能性。
5. Prompt 建構 (Prompt Construction)
這組裝了模型在每一步實際看到的內容。它是階層式的：系統 Prompt、工具定義、記憶檔案、對話歷史以及當前的使用者訊息。
OpenAI 的 Codex 使用嚴格的優先權堆疊：伺服器控制的系統訊息（最高優先權）、工具定義、開發者指令、使用者指令（級聯的 AGENTS.md 檔案，32 KiB 限制），最後是對話歷史。
6. 輸出解析 (Output Parsing)
現代 harness 依賴原生的工具呼叫，模型返回結構化的 tool_calls 物件，而不是必須解析的自由文字。Harness 會檢查：是否有工具呼叫？執行它們並循環。沒有工具呼叫？那就是最終答案。
對於結構化輸出，OpenAI 和 LangChain 都透過 Pydantic 模型支援 Schema 約束的響應。傳統方法（如 RetryWithErrorOutputParser，它將原始 Prompt、失敗的完成結果和解析錯誤回饋給模型）仍然可用於邊緣情況。
7. 狀態管理 (State Management)
LangGraph 將狀態建模為流經圖節點的型別化字典，並透過 reducer 合併更新。檢查點 (Checkpointing) 發生在超步驟邊界，使得中斷後可以恢復並進行時光倒流除錯。OpenAI 提供四種互斥的策略：應用程式記憶、SDK 會話、伺服器端 Conversations API 或輕量級 previous_response_id 鏈接。Claude Code 採取了不同的方法：以 git commit 作為檢查點，以進度檔案作為結構化的草稿板。
8. 錯誤處理 (Error Handling)
這就是為什麼這很重要：一個 10 步的流程，如果每一步都有 99% 的成功率，其端到端 (End to End) 成功率仍僅約 90.4%。錯誤會迅速累積。
LangGraph 區分了四種錯誤型別：暫時性錯誤（帶有退避機制的重試）、LLM 可恢復錯誤（將錯誤作為 ToolMessage 返回，以便模型調整）、使用者可修復錯誤（中斷以獲取人類輸入）以及意外錯誤（向上拋出以進行除錯）。Anthropic 在工具處理器中捕捉失敗，並將其作為錯誤結果返回，以保持迴圈運作。Stripe 的生產 harness 將重試次數限制為兩次。
9. 防護機制與安全性 (Guardrails and Safety)
OpenAI 的 SDK 實作了三個層級：輸入防護（在第一個 Agent 上執行）、輸出防護（在最終輸出上執行）和工具防護（在每次工具呼叫時執行）。一個「絆線」(tripwire) 機制會在觸發時立即停止 Agent。
Anthropic 在架構上將權限強制執行與模型推理分開。模型決定嘗試什麼；工具系統決定允許什麼。Claude Code 獨立控制約 40 種離散的工具能力，分為三個階段：專案載入時的信任建立、每次工具呼叫前的權限檢查，以及高風險操作的明確使用者確認。
10. 驗證迴圈 (Verification Loops)
這就是將玩具 Demo 與生產環境 Agent 區分開來的關鍵。Anthropic 建議三種方法：基於規則的回饋（測試、linter、型別檢查器）、視覺回饋（透過 Playwright 進行 UI 任務的截圖）以及 LLM-as-judge（由獨立的子 Agent 評估輸出）。
Claude Code 的創作者 Boris Cherny 指出，給予模型驗證其工作的方法可以將品質提高 2 到 3 倍。
11. 子 Agent 編排 (Subagent Orchestration)
Claude Code 支援三種執行模型：Fork（父 context 的位元組級副本）、Teammate（具有基於檔案的信箱通訊功能的獨立終端視窗）和 Worktree（擁有自己的 git worktree，每個 Agent 都有隔離的分支）。OpenAI 的 SDK 支援 Agent 作為工具（專家處理有界子任務）和交接 (handoffs)（專家取得完全控制權）。LangGraph 將子 Agent 實作為巢狀狀態圖。
迴圈運作：逐步解析
既然你已經了解了組件，讓我們追蹤它們如何在單一週期中協同工作。
步驟 1 (Prompt 組裝)：Harness 建構完整的輸入：系統 Prompt + 工具 Schema + 記憶檔案 + 對話歷史 + 當前使用者訊息。重要的 context 被放置在 Prompt 的開頭和結尾（即「Lost in the Middle」發現）。
步驟 2 (LLM 推理)：組裝好的 Prompt 發送到模型 API。模型產生輸出 token：文字、工具呼叫請求，或兩者皆有。
步驟 3 (輸出分類)：如果模型產生了文字且沒有工具呼叫，迴圈結束。如果請求了工具呼叫，則進入執行階段。如果請求了交接，則更新當前 Agent 並重新開始。
步驟 4 (工具執行)：對於每個工具呼叫，harness 會驗證參數、檢查權限、在沙盒環境中執行並擷取結果。唯讀操作可以並行執行；變更操作則序列執行。
步驟 5 (結果封裝)：工具結果被格式化為 LLM 可讀的訊息。錯誤會被捕捉並作為錯誤結果返回，以便模型可以自我修正。
步驟 6 (Context 更新)：結果被附加到對話歷史中。如果接近 context 視窗限制，harness 會觸發壓縮。
步驟 7 (迴圈)：回到步驟 1。重複直到終止。
終止條件是分層的：模型產生沒有工具呼叫的響應、超過最大輪次限制、token 預算耗盡、防護機制絆線觸發、使用者中斷，或返回安全性拒絕。一個簡單的問題可能需要 1 到 2 輪。複雜的重構任務可以在多輪中串聯數十個工具呼叫。
對於跨越多個 context 視窗的長時間任務，Anthropic 開發了一種兩階段的「Ralph Loop」模式：初始化 Agent 設定環境（初始化腳本、進度檔案、功能列表、初始 git commit），然後每個後續會話中的編碼 Agent 讀取 git log 和進度檔案來定位自己，挑選最高優先權的未完成功能，進行工作、提交並寫入摘要。檔案系統提供了跨越 context 視窗的連續性。
真實框架如何實作此模式
Anthropic 的 Claude Agent SDK 透過單一 query() 函式公開 harness，該函式建立 Agent 迴圈並返回串流訊息的非同步迭代器。執行時期是一個「笨迴圈」，所有的智慧都存在於模型中。Claude Code 使用「收集-行動-驗證」(Gather-Act-Verify) 週期：收集 context（搜尋檔案、讀取程式碼）、採取行動（編輯檔案、執行指令）、驗證結果（執行測試、檢查輸出），然後重複。
OpenAI 的 Agents SDK 透過 Runner 類別實作 harness，具有三種模式：非同步、同步和串流。該 SDK 是「程式碼優先」的：工作流程邏輯以原生 Python 表達，而不是圖形 DSL。Codex harness 將此擴展為三層架構：Codex Core（Agent 程式碼 + 執行時期）、App Server（雙向 JSON-RPC API）和客戶端介面（CLI、VS Code、網頁應用程式）。所有介面共享同一個 harness，這就是為什麼「Codex 模型在 Codex 介面上感覺比在通用聊天視窗中更好」。
LangGraph 將 harness 建模為明確的狀態圖。兩個節點 (llm_call 和 tool_node) 由條件邊連接：如果存在工具呼叫，則路由到 tool_node；如果不存在，則路由到 END。LangGraph 是從 LangChain 的 AgentExecutor 演變而來的，後者在 v0.2 中被棄用，因為它難以擴展且缺乏多 Agent 支援。LangChain 的 Deep Agents 明確使用了「Agent harness」一詞：內建工具、規劃 (write_todos 工具)、用於 context 管理的檔案系統、子 Agent 產生和持久化記憶。
CrewAI 實作了基於角色的多 Agent 架構：Agent（圍繞 LLM 的 harness，由角色、目標、背景故事和工具定義）、Task（工作單位）和 Crew（Agent 的集合）。CrewAI 的 Flows 層增加了一個「在關鍵之處具有智慧的確定性骨幹」，管理路由和驗證，而 Crews 則處理自主協作。
AutoGen（正在演變為 Microsoft Agent Framework）開創了對話驅動的編排。其三層架構（Core、AgentChat、Extensions）支援五種編排模式：順序、並行（扇出/扇入）、群組聊天、交接和 magentic（管理 Agent 維護一個動態任務分類帳來協調專家）。
鷹架隱喻 (The Scaffolding Metaphor)
鷹架隱喻並非裝飾性的，它是精確的。建築鷹架是臨時的基礎設施，使工人能夠建造他們原本無法觸及的結構。它本身不進行建造，但沒有它，工人就無法到達高層。
關鍵洞察：建築完成後，鷹架就會被拆除。隨著模型改進，harness 的複雜性應該降低。Manus 在六個月內重建了五次，每次重寫都消除了複雜性。複雜的工具定義變成了通用的 Shell 執行。「管理 Agent」變成了簡單的結構化交接。
這指向了共同演化原則：模型現在是透過在迴圈中加入特定的 harness 進行後訓練 (post-trained) 的。Claude Code 的模型學會了使用它所訓練的特定 harness。由於這種緊密耦合，更改工具實作可能會導致效能下降。
harness 設計的「未來驗證測試」：如果效能隨著更強大的模型而提升，且無需增加 harness 的複雜性，那麼該設計就是合理的。
定義每個 Harness 的七個決策
每個 harness 架構師都面臨七個選擇：
單 Agent 與多 Agent。Anthropic 和 OpenAI 都表示：先最大化單一 Agent 的能力。多 Agent 系統增加了開銷（路由需要額外的 LLM 呼叫，交接期間會損失 context）。只有當工具過載超過約 10 個重疊工具，或存在明確分離的任務領域時，才進行拆分。
ReAct 與規劃並執行 (plan-and-execute)。ReAct 在每一步交替進行推理和行動（靈活但每步成本較高）。規劃並執行將規劃與執行分開。LLMCompiler 報告稱其速度比順序 ReAct 快 3.6 倍。
Context 視窗管理策略。五種生產環境方法：基於時間的清除、對話總結、觀察遮罩、結構化筆記和子 Agent 委派。ACON 研究顯示，透過優先考慮推理軌跡而非原始工具輸出，可以在保持 95% 以上準確度的同時減少 26% 到 54% 的 token。
驗證迴圈設計。計算驗證（測試、linter）提供確定性的基本事實。推理驗證（LLM-as-judge）可以捕捉語意問題，但會增加延遲。Martin Fowler 的 Thoughtworks 團隊將其定義為指南（前饋，行動前引導）與感測器（回饋，行動後觀察）。
權限與安全架構。寬鬆（快速但有風險，自動批准大多數操作）與限制（安全但緩慢，每次操作都需要批准）。選擇取決於部署環境。
工具範疇策略。更多的工具通常意味著更差的效能。Vercel 從 v0 中移除了 80% 的工具，結果反而更好。Claude Code 透過延遲載入實現了 95% 的 context 縮減。原則是：僅公開當前步驟所需的最小工具集。
Harness 的厚度。多少邏輯存在於 harness 中，多少存在於模型中。Anthropic 押注於輕量級 harness 和模型改進。基於圖的框架則押注於明確的控制。隨著新模型版本將這些能力內化，Anthropic 定期從 Claude Code 的 harness 中刪除規劃步驟。
Harness 就是產品
兩個使用相同模型的產品，僅憑 harness 設計的不同，效能可能會有天壤之別。TerminalBench 的證據很明確：僅僅更改 harness 就讓 Agent 的排名提升了 20 多位。
Harness 並非一個已解決的問題或商品化層。這是硬核工程所在之處：將 context 作為稀缺資源進行管理、設計能在錯誤累積前捕捉失敗的驗證迴圈、建構在不產生幻覺的情況下提供連續性的記憶系統，以及針對要建構多少鷹架與留給模型多少空間做出架構決策。
隨著模型改進，該領域正朝著更輕量的 harness 發展。但 harness 本身不會消失。即使是最強大的模型，也需要某些東西來管理其 context 視窗、執行工具呼叫、持久化狀態並驗證其工作。
下次你的 Agent 失敗時，不要責怪模型。看看你的 harness。
以上就是全部內容！
如果你喜歡這篇文章：
找到我 → @akshay_pachaar ✔️
我每天都會分享關於 AI、機器學習和 vibe coding 最佳實踐的教學與見解。