Agent Harness 解析：智能體架構深度拆解
整理版優先睇
Agent Harness 係讓 LLM 變有用嘅關鍵基礎設施，模型改進但 Harness 唔會消失
呢篇文章嚟自 Akshay Pachaar，LightningAI 前 AI 工程師、Daily Dose of DS 聯合創始人，佢長期專注拆解 LLM 同 AI Agent 嘅底層邏輯。作者想解決嘅問題係：點解好多 agent demo 做得好，但一上生產就出事？佢嘅結論係問題唔喺模型，而係喺模型周圍嘅基礎設施，即係 Agent Harness。
Harness 係包裹 LLM 嘅完整軟件基礎設施，包括編排循環、工具、記憶、上下文管理、狀態持久化、錯誤處理、安全護欄等。Anthropic、OpenAI、LangChain 都用緊呢個概念。作者用一個精準嘅比喻：裸 LLM 係無內存、無硬盤、無 I/O 嘅 CPU，而 Harness 就係操作系統。
文章詳細拆解咗生產級 Harness 嘅 11 個組件（原文話有 12 個，但實際只列出 11 個），同埋主流框架（Claude SDK、OpenAI Agents SDK、LangGraph、CrewAI、AutoGen）係點實現。最後指出 Harness 係產品嘅真正差異所在，而且正向着更薄嘅方向演進，但唔會消失。
- Harness 係讓無狀態 LLM 變成有能力 Agent 嘅關鍵，改變 Harness 可以令 agent 排名跳升 20 位以上
- 生產級 Harness 包含 11 個組件：編排循環、工具、記憶、上下文管理、提示詞構建、輸出解析、狀態管理、錯誤處理、護欄與安全、驗證循環、子 agent 編排
- 上下文管理係常見失敗點，策略包括壓縮、觀察屏蔽、即時檢索、子 agent 委託，ACON 研究可減少 26-54% token 用量
- 模型同 Harness 協同演化，Claude Code 嘅模型學識咗配合特定 Harness，改變工具實現可能降低性能
- 架構決策要考慮：單 agent vs 多 agent、ReAct vs 計劃-執行、Harness 厚度，Anthropic 押注薄 Harness 同模型改進
咩係 Agent Harness？
Harness 係包裹 LLM 嘅完整軟件基礎設施，包括編排循環、工具、記憶、上下文管理、狀態持久化、錯誤處理、安全護欄。Anthropic 喺 Claude Code 文檔直接寫明 SDK 就係「驅動 Claude Code 嘅 agent harness」。
Harness 係產生 agent 行為嘅機器，而 agent 係湧現出嚟嘅行為
LangChain 嘅 Vivek Trivedy 定義：如果你唔係模型本身，你就係 harness。Beren Millidge 用咗一個精準類比：裸 LLM 係無內存、無硬盤、無 I/O 嘅 CPU，Harness 係操作系統。
三個工程層級
圍繞模型有三個同心圓層級：提示詞工程、上下文工程、Harness 工程。Harness 工程包含前兩者，再加上完整嘅應用基礎設施。
生產級 Harness 嘅 11 個組件
- 1 編排循環：實現思考-行動-觀察（TAO/ReAct）循環，Anthropic 描述為「笨循環」，所有智能喺模型度。
- 2 工具：以 schema 形式定義，負責註冊、驗證、沙盒執行、結果捕獲，Claude Code 有六類工具。
- 3 記憶：短期（對話歷史）、長期（CLAUDE.md、MEMORY.md），Claude Code 三層：輕量級索引、詳細主題文件、原始記錄。
- 4 上下文管理：防止上下文腐爛，策略包括壓縮、觀察屏蔽、即時檢索、子 agent 委託。
- 5 提示詞構建：分層組裝系統提示、工具定義、記憶文件、對話歷史、用戶消息。
- 6 輸出解析：依賴原生工具調用，返回 tool_calls 對象，唔使解析自由文本。
- 7 狀態管理：LangGraph 用類型字典流經圖節點，OpenAI 提供四種策略。
- 8 錯誤處理：區分瞬時、LLM 可恢復、用戶可修復、意外錯誤，Stripe 設重試上限兩次。
一個每步成功率 99% 嘅 10 步流程，端到端成功率只有約 90.4%
Claude Code 創建者 Boris Cherny 指出，畀模型驗證自身工作嘅方式能將質量提升 2 到 3 倍
循環實際運轉：逐步演練
一個完整循環有 7 步：提示詞組裝（重要放開頭結尾）、LLM 推斷、輸出分類、工具執行、結果打包、上下文更新、循環。終止條件包括模型無工具調用、超輪次、token 預算耗盡等。
Anthropic 開發咗兩階段「Ralph Loop」模式：初始化 agent 建立環境，後續編碼 agent 讀取 git 日誌定位自身
一個簡單問題可能只需 1 到 2 輪，複雜重構可以串聯幾十次工具調用。
主流框架點樣實現呢個模式
- Anthropic Claude Agent SDK：用單一 query() 函數暴露 Harness，運行時係「笨循環」。
- OpenAI Agents SDK：透過 Runner 類實現，支援三種模式，Codex 有三層架構。
- LangGraph：建模為顯式狀態圖，兩個節點（llm_call 同 tool_node）通過條件邊連接。
- CrewAI：基於角色嘅多 agent 架構，Flows 層增加確定性骨架。
- AutoGen：對話驅動編排，五種模式，magentic 模式用動態任務賬本。
每個 Harness 都面對嘅七個決策
- 1 單 agent 定多 agent：Anthropic 同 OpenAI 都建議先將單 agent 做到極致。
- 2 ReAct 定計劃-執行：LLMCompiler 報告比順序 ReAct 快 3.6 倍。
- 3 上下文窗口管理策略：五種方式，ACON 研究可減 26-54% token。
- 4 驗證循環設計：計算驗證（測試）同推斷驗證（LLM 評判）。
- 5 權限與安全架構：寬鬆型（快） vs 限制型（安全）。
- 6 工具範圍策略：Vercel 從 v0 刪 80% 工具後效果更好。
- 7 Harness 厚度：Anthropic 押注薄 Harness 同模型改進。
使用相同模型嘅兩個產品，僅憑 Harness 設計就可以產生截然不同嘅性能
下次你個 agent 失敗時，唔好怪模型，睇下 Harness。
呢篇文章嚟自Akshay Pachaar，LightningAI前AI工程師、Daily Dose of DS聯合創始人，長期專注拆解LLM同AI Agent嘅底層邏輯。深入解析Anthropic、OpenAI、Perplexity同LangChain喺度整啲乜——包含編排循環、工具調用、記憶機制、上下文管理，同埋將一個無狀態嘅LLM轉變成有能力嘅Agent需要嘅所有嘢。模型能力越嚟越強，但係Harness唔會消失
你整過一個聊天機器人，駁咗ReAct循環，掛咗幾個工具，示範效果唔錯。
跟住你想將佢變成生產級產品，問題就跟住嚟：模型記唔到三步之前做過啲乜，工具調用無聲無息咁失敗，上下文窗口俾垃圾填滿。
問題唔喺模型，而係模型周圍嘅一切。
LangChain用一個案例證明咗呢點：淨係改咗包住LLM嘅基礎設施，模型權重完全冇鬱過，喺TerminalBench 2.0嘅排名由30名開外直接跳到第5。另一個研究項目俾LLM自己優化基礎設施，通過率達到76.4%，超過咗人手設計嘅系統。
呢套基礎設施而家有咗個正式名：Agent Harness。
咩嘢係Agent Harness
呢個概念喺2026年初正式命名，但其實一早存在。Harness係包住LLM嘅完整軟件基礎設施：編排循環、工具、記憶、上下文管理、狀態持久化、錯誤處理、安全護欄。
Anthropic喺Claude Code文檔直接寫明：SDK就係「驅動Claude Code嘅agent harness」。OpenAI嘅Codex團隊都用同一個框架，將「agent」同「harness」視為等價概念，專門指等LLM變得有用嘅非模型基礎設施。
LangChain嘅Vivek Trivedy俾咗一個清晰嘅定義：如果你唔係模型本身，你就係harness。
好多人容易混淆嘅分別喺呢度：「agent」係湧現出嚟嘅行為，係用戶互動嗰個有目標、會用工具、能自我糾正嘅實體。Harness係產生呢種行為嘅機器。當有人話「我做咗一個agent」，其實佢哋係做咗一個harness，然後將佢對準咗一個模型。
Beren Millidge喺2023年嘅文章《作為自然語言計算機嘅腳手架LLM》俾咗一個精準嘅比喻：裸LLM係冇內存、冇硬盤、冇I/O嘅CPU。上下文窗口係內存，快但有限；外部數據庫係硬盤，大但慢；工具整合係設備驅動；Harness係操作系統。好似Millidge所寫：我哋重新發明咗馮·諾依曼架構，因為呢個係任何計算系統嘅自然抽象。
三個工程層級
圍繞模型有三個同心圓層級：
提示詞工程，負責設計模型接收嘅指令。
上下文工程，管理模型睇到啲乜、幾時睇到。
Harness工程，包含前兩者，再加上完整嘅應用基礎設施：工具編排、狀態持久化、錯誤恢復、驗證循環、安全執行、生命週期管理。
Harness唔係提示詞嘅包裝層，而係令自主agent行為成為可能嘅完整系統。
生產級Harness嘅12個組件
綜合Anthropic、OpenAI、LangChain同更廣泛嘅實踐者社羣，一個生產級agent harness有12個獨立組件。
1. 編排循環
呢個係心跳所在。佢實現思考-行動-觀察（TAO）循環，又叫ReAct循環：組裝提示詞、調用LLM、解析輸出、執行工具調用、將結果反饋返去、重複直到完成。
機制上，呢個通常只係一個while循環，複雜性匿喺循環管理嘅所有嘢度，而唔係循環本身。Anthropic將佢哋嘅運行時描述為一個「蠢循環」，所有智能都住喺模型度，Harness淨係管理輪次。
2. 工具
工具係agent嘅手。佢哋以schema形式定義（名稱、描述、參數類型），注入到LLM嘅上下文度，等模型知道有啲咩可用。工具層負責註冊、schema驗證、參數提取、沙盒執行、結果捕獲，同埋將結果格式化做LLM可讀嘅觀察結果。
Claude Code提供六個類別嘅工具：檔案操作、搜尋、執行、網絡存取、代碼智能，同埋子agent生成。OpenAI嘅Agents SDK支援函數工具（透過@function_tool）、託管工具（WebSearch、CodeInterpreter、FileSearch），同埋MCP伺服器工具。
3. 記憶
記憶喺多個時間尺度上運作。短期記憶係單次會話入面嘅對話歷史。長期記憶跨會話持久化：Anthropic用CLAUDE.md項目檔案同自動生成嘅MEMORY.md檔案；LangGraph用命名空間組織嘅JSON Store；OpenAI支援由SQLite或Redis支援嘅Session。
Claude Code實現咗三層層級：輕量級索引（每條約150字符，始終加載）、按需拉取嘅詳細主題檔案，同埋只透過搜尋先存取嘅原始記錄。一個關鍵設計原則：agent將自己嘅記憶視為「提示」，喺行動前會對照實際狀態進行驗證。
4. 上下文管理
呢個係好多agent無聲無息失敗嘅地方。核心問題係上下文腐爛：當關鍵內容跌咗喺窗口中間位置時，模型性能下降超過30%（Chroma研究結果，得到史丹福「迷失喺中間」論文嘅印證）。就算係百萬token嘅窗口，隨着上下文增長，指令遵循能力都會退化。
生產級策略包括：
壓縮對話摘要：喺接近上限時對對話歷史進行摘要（Claude Code喺壓縮時保留架構決策同未解決嘅bug，丟棄冗餘嘅工具輸出）；
觀察屏蔽：JetBrains嘅Junie隱藏舊嘅工具輸出，但保留工具調用可見；
即時檢索：維護輕量級標識符，動態加載數據（Claude Code用grep、glob、head、tail，而唔係加載完整檔案）；
子agent委託：每個子agent進行大範圍探索，但只返回1000到2000 token嘅壓縮摘要。
Anthropic嘅上下文工程指南明確咗目標：揾到可以最大化預期結果概率嘅最小高信號token集合。
5. 提示詞構建
呢一步組裝模型喺每一步實際上睇到嘅內容，係分層嘅：系統提示、工具定義、記憶檔案、對話歷史、當前用戶訊息。
OpenAI嘅Codex用嚴格嘅優先級棧：伺服器控制嘅系統訊息（最高優先級）、工具定義、開發者指令、用戶指令（級聯嘅AGENTS.md檔案，32 KiB上限），然後係對話歷史。
6. 輸出解析
現代Harness依賴原生工具調用，模型返回結構化嘅tool_calls對象，而唔係需要解析嘅自由文本。Harness檢查：有工具調用嗎？執行並循環。冇工具調用？就係最終答案。
對於結構化輸出，OpenAI同LangChain都支援透過Pydantic模型進行schema約束嘅響應。RetryWithErrorOutputParser呢類舊方法（將原始提示、失敗嘅補全同解析錯誤反饋俾模型）喺邊緣情況下仍然可用。
7. 狀態管理
LangGraph將狀態建模為流經圖節點嘅類型字典，用reducer合併更新。檢查點喺超步邊界處觸發，支援中斷後恢復同時間旅行調試。OpenAI提供四種互斥策略：應用內存、SDK session、服務端Conversations API，或者輕量級previous_response_id連結。Claude Code採用唔同嘅方式：git提交作為檢查點，進度檔案作為結構化草稿紙。
8. 錯誤處理
呢點好關鍵：一個每一步成功率99%嘅10步流程，端到端成功率仍然只有約90.4%。錯誤會快速累積。
LangGraph區分四種錯誤類型：瞬時錯誤（帶退避重試）、LLM可恢復錯誤（將錯誤作為ToolMessage返回等模型調整）、用戶可修復錯誤（中斷請求人工輸入），同埋意外錯誤（向上冒泡用於調試）。Anthropic喺工具處理程序入面捕獲失敗，將佢作為錯誤結果返回以保持循環運行。Stripe嘅生產Harness將重試次數上限設為兩次。
9. 護欄與安全
OpenAI嘅SDK實現三個層級：輸入護欄（運行喺第一個agent上）、輸出護欄（運行喺最終輸出上）、工具護欄（每次工具調用都運行）。一個「斷路器」機制喺觸發時即刻停止agent。
Anthropic喺架構上將權限執行與模型推理分離：模型決定嘗試啲乜，工具系統決定允許啲乜。Claude Code獨立門控約40個離散工具能力，分三個階段：項目加載時嘅信任建立、每次工具調用前嘅權限檢查，同埋高風險操作嘅明確用戶確認。
10. 驗證循環
呢個係玩具demo同生產agent嘅分水嶺。Anthropic推薦三種方式：基於規則嘅反饋（測試、代碼檢查、類型檢查器）、視覺反饋（透過Playwright截圖用於UI任務），同埋LLM作為評判者（獨立嘅子agent評估輸出）。
Claude Code創建者Boris Cherny指出，俾模型一種驗證自身工作嘅方式能將質量提升2到3倍。
11. 子agent編排
Claude Code支援三種執行模型：Fork（父上下文嘅字節級複製），Teammate（獨立終端面板，透過基於檔案嘅郵箱通信），同埋Worktree（每個agent擁有獨立嘅git工作樹同隔離分支）。OpenAI嘅SDK支援agent作為工具（專家處理有界子任務）同移交（專家接管完整控制權）。LangGraph將子agent實現為嵌套狀態圖。
（文章原文冇單獨列出第12個組件，按原文結構保留11個展開介紹。）
循環實際上點樣運作：逐步演練
瞭解咗組件，再睇一個完整循環嘅運作方式。
第1步（提示詞組裝）： Harness構建完整輸入：系統提示 + 工具schema + 記憶檔案 + 對話歷史 + 當前用戶訊息。重要上下文放喺提示詞嘅開頭同結尾（嚟自「迷失喺中間」嘅發現）。
第2步（LLM推斷）： 組裝好嘅提示詞發送俾模型API，模型生成輸出token：文本、工具調用請求，或者兩樣都有。
第3步（輸出分類）： 如果模型淨係輸出文本而且冇工具調用，循環結束。如果請求咗工具調用，進入執行。如果請求咗移交，更新當前agent並重新開始。
第4步（工具執行）： 對每個工具調用，Harness驗證參數、檢查權限、喺沙盒環境中執行、捕獲結果。唯讀操作可以並發運行；寫入操作串行運行。
第5步（結果打包）： 工具結果被格式化為LLM可讀嘅訊息。錯誤被捕獲並作為錯誤結果返回，等模型可以自我糾正。
第6步（上下文更新）： 結果追加到對話歷史。如果接近上下文窗口限制，Harness觸發壓縮。
第7步（循環）： 返去第1步，重複直到終止。
終止條件係分層嘅：模型產生冇工具調用嘅響應、超過最大輪次限制、token預算耗盡、護欄斷路器觸發、用戶中斷，或者返回安全拒絕。一個簡單問題可能只需1至2輪，一個複雜嘅重構任務可以喺多輪中串聯幾十次工具調用。
對於跨越多個上下文窗口嘅長時間運行任務，Anthropic開發咗一種兩階段「Ralph Loop」模式：初始化agent負責建立環境（初始化腳本、進度檔案、功能列表、初始git提交），然後後續每個會話入面嘅編碼agent讀取git日誌同進度檔案嚟定位自己，選擇優先級最高嘅未完成功能，完成後提交並寫入摘要。檔案系統喺上下文窗口之間提供連續性。
主流框架點樣實現呢個模式
Anthropic嘅Claude Agent SDK 透過單一嘅query()函數暴露Harness，創建agent循環並返回流式訊息嘅異步迭代器。運行時係一個「蠢循環」，所有智能住喺模型度。Claude Code用收集-行動-驗證循環：收集上下文（搜尋檔案、閲讀代碼）、採取行動（編輯檔案、執行指令）、驗證結果（執行測試、檢查輸出），然後重複。
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工具）、用於上下文管理嘅檔案系統、子agent生成，同埋持久記憶。
CrewAI 實現咗基於角色嘅多agent架構：Agent（圍繞LLM嘅Harness，由角色、目標、背景故事同工具定義）、Task（工作單元）同Crew（agent嘅集合）。CrewAI嘅Flows層增加咗「關鍵位置有智能支撐嘅確定性骨架」，喺Crew處理自主協作時管理路由同驗證。
AutoGen（正在演化為微軟Agent Framework）開創咗對話驅動嘅編排方式。其三層架構（Core、AgentChat、Extensions）支援五種編排模式：順序、併發（扇出/扇入）、羣聊、移交，同埋magentic（管理agent維護動態任務賬本，協調各專家agent）。
腳手架比喻嘅精確含義
腳手架呢個比喻唔係裝飾性嘅，佢好精準。建築腳手架係畀工人可以到達佢哋原本觸及唔到位置嘅臨時基礎設施。佢唔負責建設，但冇佢，工人上唔到高層。
關鍵洞察：腳手架喺建築完工後會被拆除。隨着模型改進，Harness嘅複雜性應該降低。Manus喺六個月內重寫咗五次，每次重寫都喺度去除複雜性。複雜嘅工具定義變咗通用嘅shell執行，「管理agent」變咗簡單嘅結構化移交。
呢個指向咗協同演化原則：模型而家同特定Harness一齊喺訓練循環中進行後訓練。Claude Code嘅模型學識咗用佢被訓練時配合嘅嗰個特定Harness。改變工具實現可能因為呢種緊密耦合而降低性能。
Harness設計嘅「面向未來測試」係：如果隨着模型能力提升，性能能夠提升而唔需要增加Harness複雜性，咁設計就係健全嘅。
每個Harness都面對嘅七個決策
單agent定多agent： Anthropic同OpenAI都建議先將單agent做到極致。多agent系統增加開銷（路由需要額外嘅LLM調用，移交時上下文會丟失）。淨係喺工具數量超過約10個重疊工具、或者存在明顯獨立嘅任務域嗰時先至拆分。
ReAct定計劃-執行： ReAct喺每一步交織推理同行動（靈活但每步成本更高）。計劃-執行將規劃與執行分離。LLMCompiler報告比順序ReAct快3.6倍。
上下文窗口管理策略： 五種生產方式：基於時間嘅清除、對話摘要、觀察屏蔽、結構化筆記、子agent委託。ACON研究表明，透過優先保留推理軌跡而唔係原始工具輸出，可以喺保持95%以上準確率嘅同時減少26到54%嘅token用量。
驗證循環設計： 計算驗證（測試、代碼檢查器）提供確定性嘅基準真相。推斷驗證（LLM作為評判者）能夠捕獲語義問題但增加延遲。Martin Fowler嘅Thoughtworks團隊將佢框架化為：指南（前饋，行動前引導）同傳感器（反饋，行動後觀察）。
權限同安全架構： 寬鬆型（快但有風險，自動批准大多數操作）定限制型（安全但慢，每次操作都要批准）。選擇取決於部署場景。
工具範圍策略： 更多工具通常意味着更差嘅性能。Vercel從v0中刪除咗80%嘅工具，結果仲好咗。Claude Code透過懶加載實現咗95%嘅上下文減少。原則係：淨係暴露當前步驟所需要嘅最小工具集。
Harness厚度： 有幾多邏輯住喺Harness度，有幾多交俾模型。Anthropic押注於薄Harness同模型改進。基於圖嘅框架押注於顯式控制。Anthropic隨着新模型版本將嗰啲能力內化，定期從Claude Code嘅Harness中刪除規劃步驟。
Harness就係產品
用同一個模型嘅兩個產品，淨係靠Harness設計就可以產生截然不同嘅性能。TerminalBench嘅證據好清楚：淨係改變Harness，就可以令agent嘅排名移動20個以上嘅位次。
Harness唔係一個已經解決咗嘅問題，亦唔係一個商品化嘅層。佢係真正硬核嘅工程所在：將上下文作為稀缺資源嚟管理，設計喺失敗累積之前就能夠捕獲失敗嘅驗證循環，構建能夠提供連續性而唔產生幻覺嘅記憶系統，同埋喺「要整幾多腳手架」同「留幾多俾模型」之間做架構決策。
呢個領域正在向更薄嘅Harness方向演進，因為模型喺持續改進。但Harness本身唔會消失。就算係最強大嘅模型，都需要一樣嘢嚟管理佢嘅上下文窗口、執行佢嘅工具調用、持久化佢嘅狀態、同埋驗證佢嘅工作。
下次你嘅agent失敗嗰時，唔好怪模型，睇下Harness。
--end--
最後記得⭐️我，每日都喺度更新：如果覺得文章仲可以嘅話可以點讚轉發推薦評論
/...@作者：你講得完全正確（YAR師）
這篇文章來自Akshay Pachaar，LightningAI前AI工程師、Daily Dose of DS聯合創始人，長期專注於拆解LLM和AI Agent的底層邏輯。深度解析Anthropic、OpenAI、Perplexity和LangChain在構建什麼——涵蓋編排循環、工具調用、記憶機制、上下文管理，以及將一個無狀態的LLM轉變為有能力的Agent所需的全部要素，模型能力越來越強，但是Harness不會消失
你搭過一個聊天機器人，接入了ReAct循環，掛了幾個工具，演示效果不錯。
然後你嘗試把它做成生產級產品，問題隨之而來：模型記不住三步前做了什麼，工具調用靜默失敗，上下文窗口被垃圾填滿。
問題不在模型。在模型周圍的一切。
LangChain用一個案例證明了這一點：只改了包裹LLM的基礎設施，模型權重完全沒動，在TerminalBench 2.0上的排名從30名開外直接跳到第5。另一個研究項目讓LLM自己優化基礎設施，通過率達到76.4%，超過了人工設計的系統。
這套基礎設施現在有了一個正式的名字：Agent Harness。
什麼是Agent Harness
這個概念在2026年初被正式命名，但早已存在。Harness是包裹LLM的完整軟件基礎設施：編排循環、工具、記憶、上下文管理、狀態持久化、錯誤處理、安全護欄。
Anthropic在Claude Code文檔裏直接寫明：SDK就是「驅動Claude Code的agent harness」。OpenAI的Codex團隊也用同樣的框架，把「agent」和「harness」視為等價概念，專指讓LLM變得有用的非模型基礎設施。
LangChain的Vivek Trivedy給出了一個清晰的定義：如果你不是模型本身，你就是harness。
很多人容易混淆的區分在這裏：「agent」是湧現出來的行為，是用戶交互的那個有目標、會用工具、能自我糾正的實體。Harness是產生這種行為的機器。當有人說「我做了一個agent」，他們其實是做了一個harness，然後把它對準了一個模型。
Beren Millidge在2023年的文章《作為自然語言計算機的腳手架LLM》裏給了一個精準的類比：裸LLM是沒有內存、沒有硬盤、沒有I/O的CPU。上下文窗口是內存，快但有限；外部數據庫是硬盤，大但慢；工具集成是設備驅動；Harness是操作系統。正如Millidge所寫：我們重新發明了馮·諾依曼架構，因為這是任何計算系統的自然抽象。
三個工程層級
圍繞模型有三個同心圓層級：
提示詞工程，負責設計模型接收的指令。
上下文工程，管理模型看到什麼、什麼時候看到。
Harness工程，包含前兩者，再加上完整的應用基礎設施：工具編排、狀態持久化、錯誤恢復、驗證循環、安全執行、生命週期管理。
Harness不是提示詞的包裝層，而是讓自主agent行為成為可能的完整系統。
生產級Harness的12個組件
綜合Anthropic、OpenAI、LangChain和更廣泛的實踐者社區，一個生產級agent harness有12個獨立組件。
1. 編排循環
這是心跳所在。它實現思考-行動-觀察（TAO）循環，也叫ReAct循環：組裝提示詞、調用LLM、解析輸出、執行工具調用、把結果反饋回去、重複直到完成。
機制上，這往往只是一個while循環，複雜性藏在循環管理的所有東西里，而不是循環本身。Anthropic把他們的運行時描述為一個「笨循環」，所有智能都住在模型裏，Harness只管理輪次。
2. 工具
工具是agent的手。它們以schema形式定義（名稱、描述、參數類型），注入到LLM的上下文中，讓模型知道有哪些可用。工具層負責註冊、schema驗證、參數提取、沙盒執行、結果捕獲，以及把結果格式化成LLM可讀的觀察結果。
Claude Code提供六個類別的工具：文件操作、搜索、執行、網絡訪問、代碼智能、以及子agent生成。OpenAI的Agents SDK支持函數工具（通過@function_tool）、託管工具（WebSearch、CodeInterpreter、FileSearch），以及MCP服務器工具。
3. 記憶
記憶在多個時間尺度上運作。短期記憶是單次會話內的對話歷史。長期記憶跨會話持久化：Anthropic使用CLAUDE.md項目文件和自動生成的MEMORY.md文件；LangGraph使用命名空間組織的JSON Store；OpenAI支持由SQLite或Redis支持的Session。
Claude Code實現了三層層級：輕量級索引（每條約150字符，始終加載）、按需拉取的詳細主題文件、以及只通過搜索訪問的原始記錄。一個關鍵設計原則：agent把自己的記憶視為「提示」，在行動前會對照實際狀態進行驗證。
4. 上下文管理
這是很多agent悄然失敗的地方。核心問題是上下文腐爛：當關鍵內容落在窗口中間位置時，模型性能下降超過30%（Chroma研究結果，得到斯坦福「迷失在中間」論文的印證）。即使是百萬token的窗口，隨着上下文增長，指令遵循能力也會退化。
生產級策略包括：
壓縮：在接近上限時對對話歷史進行摘要（Claude Code在壓縮時保留架構決策和未解決的bug，丟棄冗餘的工具輸出）；
觀察屏蔽：JetBrains的Junie隱藏舊的工具輸出，但保留工具調用可見；
即時檢索：維護輕量級標識符，動態加載數據（Claude Code使用grep、glob、head、tail，而不是加載完整文件）；
子agent委託：每個子agent進行大範圍探索，但只返回1000到2000 token的壓縮摘要。
Anthropic的上下文工程指南明確了目標：找到能最大化期望結果概率的最小高信號token集合。
5. 提示詞構建
這一步組裝模型在每一步實際看到的內容，是分層的：系統提示、工具定義、記憶文件、對話歷史、當前用戶消息。
OpenAI的Codex使用嚴格的優先級棧：服務器控制的系統消息（最高優先級）、工具定義、開發者指令、用戶指令（級聯的AGENTS.md文件，32 KiB上限），然後是對話歷史。
6. 輸出解析
現代Harness依賴原生工具調用，模型返回結構化的tool_calls對象，而不是需要解析的自由文本。Harness檢查：有工具調用嗎？執行並循環。沒有工具調用？那就是最終答案。
對於結構化輸出，OpenAI和LangChain都支持通過Pydantic模型進行schema約束的響應。RetryWithErrorOutputParser等舊方法（把原始提示、失敗的補全和解析錯誤反饋給模型）在邊緣情況下仍然可用。
7. 狀態管理
LangGraph將狀態建模為流經圖節點的類型字典，用reducer合併更新。檢查點在超步邊界處觸發，支持中斷後恢復和時間旅行調試。OpenAI提供四種互斥策略：應用內存、SDK session、服務端Conversations API，或輕量級previous_response_id連結。Claude Code採用不同的方式：git提交作為檢查點，進度文件作為結構化草稿紙。
8. 錯誤處理
這一點很關鍵：一個每步成功率99%的10步流程，端到端成功率仍然只有約90.4%。錯誤會快速累積。
LangGraph區分四種錯誤類型：瞬時錯誤（帶退避重試）、LLM可恢復錯誤（將錯誤作為ToolMessage返回讓模型調整）、用戶可修復錯誤（中斷請求人工輸入）、以及意外錯誤（向上冒泡用於調試）。Anthropic在工具處理程序內捕獲失敗，將其作為錯誤結果返回以保持循環運行。Stripe的生產Harness把重試次數上限設為兩次。
9. 護欄與安全
OpenAI的SDK實現三個層級：輸入護欄（運行在第一個agent上）、輸出護欄（運行在最終輸出上）、工具護欄（每次工具調用都運行）。一個「斷路器」機制在觸發時立即停止agent。
Anthropic在架構上將權限執行與模型推理分離：模型決定嘗試什麼，工具系統決定允許什麼。Claude Code獨立門控約40個離散工具能力，分三個階段：項目加載時的信任建立、每次工具調用前的權限檢查、以及高風險操作的明確用戶確認。
10. 驗證循環
這是玩具demo和生產agent的分水嶺。Anthropic推薦三種方式：基於規則的反饋（測試、代碼檢查、類型檢查器）、視覺反饋（通過Playwright截圖用於UI任務）、以及LLM作為評判者（獨立的子agent評估輸出）。
Claude Code創建者Boris Cherny指出，給模型一種驗證自身工作的方式能將質量提升2到3倍。
11. 子agent編排
Claude Code支持三種執行模型：Fork（父上下文的字節級複製），Teammate（獨立終端面板，通過基於文件的郵箱通信），以及Worktree（每個agent擁有獨立的git工作樹和隔離分支）。OpenAI的SDK支持agent作為工具（專家處理有界子任務）和移交（專家接管完整控制權）。LangGraph將子agent實現為嵌套狀態圖。
（文章原文未單獨列出第12個組件，按原文結構保留11個展開介紹。）
循環實際如何運轉：逐步演練
瞭解了組件，再來看一個完整循環的運作方式。
第1步（提示詞組裝）： Harness構建完整輸入：系統提示 + 工具schema + 記憶文件 + 對話歷史 + 當前用戶消息。重要上下文被放在提示詞的開頭和結尾（來自「迷失在中間」的發現）。
第2步（LLM推斷）： 組裝好的提示詞發送給模型API，模型生成輸出token：文本、工具調用請求，或兩者都有。
第3步（輸出分類）： 如果模型只輸出文本且沒有工具調用，循環結束。如果請求了工具調用，進入執行。如果請求了移交，更新當前agent並重新開始。
第4步（工具執行）： 對每個工具調用，Harness驗證參數、檢查權限、在沙盒環境中執行、捕獲結果。只讀操作可以併發運行；寫入操作串行運行。
第5步（結果打包）： 工具結果被格式化為LLM可讀的消息。錯誤被捕獲並作為錯誤結果返回，讓模型可以自我糾正。
第6步（上下文更新）： 結果追加到對話歷史。如果接近上下文窗口限制，Harness觸發壓縮。
第7步（循環）： 返回第1步，重複直到終止。
終止條件是分層的：模型產生無工具調用的響應、超過最大輪次限制、token預算耗盡、護欄斷路器觸發、用戶中斷、或返回安全拒絕。一個簡單問題可能只需1到2輪，一個複雜的重構任務可以在多輪中串聯幾十次工具調用。
對於跨越多個上下文窗口的長時間運行任務，Anthropic開發了一種兩階段「Ralph Loop」模式：初始化agent負責建立環境（初始化腳本、進度文件、功能列表、初始git提交），然後後續每個會話中的編碼agent讀取git日誌和進度文件來定位自身，選擇優先級最高的未完成功能，完成後提交併寫入摘要。文件系統在上下文窗口之間提供連續性。
主流框架如何實現這一模式
Anthropic的Claude Agent SDK 通過單一的query()函數暴露Harness，創建agent循環並返回流式消息的異步迭代器。運行時是一個「笨循環」，所有智能住在模型裏。Claude Code使用收集-行動-驗證循環：收集上下文（搜索文件、閲讀代碼）、採取行動（編輯文件、運行命令）、驗證結果（運行測試、檢查輸出），然後重複。
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工具）、用於上下文管理的文件系統、子agent生成、以及持久記憶。
CrewAI 實現了基於角色的多agent架構：Agent（圍繞LLM的Harness，由角色、目標、背景故事和工具定義）、Task（工作單元）和Crew（agent的集合）。CrewAI的Flows層增加了「關鍵位置有智能支撐的確定性骨架」，在Crew處理自主協作時管理路由和驗證。
AutoGen（正在演化為微軟Agent Framework）開創了對話驅動的編排方式。其三層架構（Core、AgentChat、Extensions）支持五種編排模式：順序、併發（扇出/扇入）、羣聊、移交，以及magentic（管理agent維護動態任務賬本，協調各專家agent）。
腳手架比喻的精確含義
腳手架這個比喻不是裝飾性的，它很精準。建築腳手架是讓工人能夠到達他們否則無法觸及位置的臨時基礎設施。它不負責建設，但沒有它，工人上不了高層。
關鍵洞察：腳手架在建築完工後會被拆除。隨着模型改進，Harness的複雜性應該降低。Manus在六個月內重寫了五次，每次重寫都在去除複雜性。複雜的工具定義變成了通用的shell執行，「管理agent」變成了簡單的結構化移交。
這指向了協同演化原則：模型現在與特定Harness一起在訓練循環中進行後訓練。Claude Code的模型學會了使用它被訓練時配合的那個特定Harness。改變工具實現可能因為這種緊密耦合而降低性能。
Harness設計的「面向未來測試」是：如果隨着模型能力提升，性能能夠提升而不需要增加Harness複雜性，那麼設計就是健全的。
每個Harness都面臨的七個決策
單agent還是多agent： Anthropic和OpenAI都建議先把單agent做到極致。多agent系統增加開銷（路由需要額外的LLM調用，移交時上下文會丟失）。只在工具數量超過約10個重疊工具、或存在明顯獨立的任務域時才拆分。
ReAct還是計劃-執行： ReAct在每一步交織推理和行動（靈活但每步成本更高）。計劃-執行將規劃與執行分離。LLMCompiler報告比順序ReAct快3.6倍。
上下文窗口管理策略： 五種生產方式：基於時間的清除、對話摘要、觀察屏蔽、結構化筆記、子agent委託。ACON研究表明，通過優先保留推理軌跡而非原始工具輸出，可以在保持95%以上準確率的同時減少26到54%的token用量。
驗證循環設計： 計算驗證（測試、代碼檢查器）提供確定性的基準真相。推斷驗證（LLM作為評判者）能捕獲語義問題但增加延遲。Martin Fowler的Thoughtworks團隊將其框架化為：指南（前饋，行動前引導）和傳感器（反饋，行動後觀察）。
權限和安全架構： 寬鬆型（快但有風險，自動批准大多數操作）還是限制型（安全但慢，每次操作都需要批准）。選擇取決於部署場景。
工具範圍策略： 更多工具往往意味着更差的性能。Vercel從v0中刪除了80%的工具，結果更好了。Claude Code通過懶加載實現了95%的上下文減少。原則是：只暴露當前步驟所需的最小工具集。
Harness厚度： 多少邏輯住在Harness裏，多少交給模型。Anthropic押注於薄Harness和模型改進。基於圖的框架押注於顯式控制。Anthropic隨着新模型版本將那些能力內化，定期從Claude Code的Harness中刪除規劃步驟。
Harness就是產品
使用相同模型的兩個產品，僅憑Harness設計就可以產生截然不同的性能。TerminalBench的證據很清楚：只改變Harness，就能讓agent的排名移動20個以上的位次。
Harness不是一個已解決的問題，也不是一個商品化的層。它是真正硬核的工程所在：把上下文作為稀缺資源來管理，設計在失敗累積之前就能捕獲失敗的驗證循環，構建能提供連續性而不產生幻覺的記憶系統，以及在「要構建多少腳手架」與「留多少給模型」之間做出架構決策。
這個領域正在向更薄的Harness方向演進，因為模型在持續改進。但Harness本身不會消失。即使是最強大的模型，也需要某個東西來管理它的上下文窗口、執行它的工具調用、持久化它的狀態、以及驗證它的工作。
下次你的agent失敗時，不要怪模型，看看Harness。
--end--
最後記得⭐️我，每天都在更新：如果覺得文章還不錯的話可以點贊轉發推薦評論
/...@作者：你說的完全正確（YAR師）