如何構建生產級Agent Harness：不止選框架，更需模塊化“Worker”架構

作者：惡人筆記
日期：2026年6月1日 上午7:40
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

Agents嘅Harness唔係一個框架，而係一組可插拔Worker。模塊化設計比框架綁定更適合企業長期落地。

整理版摘要

呢篇文章係基於Mike Piccolo（iii.dev創始人）一篇深度文章《How to Build Your Own Agent Harness》嘅整理。作者想解決嘅問題係：點解好多團隊最終要由頭搭建自己嘅Agent Harness？整體結論係，Harness唔係單一框架，而係由10-15個獨立職責組成嘅組合，最適合嘅方法係構建成一組可安裝、可版本化、可替換嘅Worker，透過統一引擎連接。

文章指出，團隊經常直接採用LangChain、LangGraph呢啲框架，一旦某個部分唔匹配就要分支、繞路或重寫，最終好多都要自建。所以Harness必須承擔15項核心職責，包括接受Turn請求、策略檢查、人工審批、預算控制、事件流推送等。呢啲職責喺企業級場景缺一不可。

Mike Piccolo提倡嘅模塊化Worker架構，每個Worker獨立運行、獨立版本，透過總線註冊函數同觸發器。咁樣想換策略引擎或加新模型provider都好簡單。框架同模塊化唔係二選一，而係可以透過滑塊調整，少裝幾個Worker就係輕量版，全裝就係企業級厚版。文章最後俾出實用建議，包括先評估需求、從小處實踐、重視FSM，同埋避免過度追求全自動。

  • Harness承擔15項核心職責，包括策略檢查、人工審批、預算控制、Trace等，缺一不可。
  • 建議將Harness構建成一組可插拔Worker，透過統一引擎連接，更靈活易於治理。
  • 框架上手快適合MVP，但規模化後定製成本高；模塊化Worker可獨立升級、語言無關。
  • 企業落地需優先解決觀測性（統一Trace）同治理（審批、預算），呢啲係生產環境嘅「保險絲」。
  • 避免過度追求全自動，Human-in-the-Loop喺高風險場景至關重要；上下文壓縮同Prompt組裝直接影響Token消耗。
值得記低
連結 iii.dev

How to Build Your Own Agent Harness

Mike Piccolo 原文，詳細拆解生產級 Agent Harness 嘅職責同 Worker 架構，仲有執行流程圖同替換示例。

開啟
整理重點

問題所在：Harness唔係單一框架

近年AI Agent逐漸從概念走向落地，企業關心點樣令Agent喺生產環境穩定、高效、安全運行。Mike Piccolo分享嘅文章系統拆解咗生產級Agent Harness嘅本質。佢指出：大多數團隊唔係構建Harness，而係直接「採用」一個框架，將循環、工具、記憶、編排全部打包成一個決策。

Agent = 模型 + Harness

LLM似聰明大腦，但要佢真正「做事」就需要可靠「身體」——Harness。Harness負責工具調用、狀態管理、策略控制、預算追蹤等基礎設施。一旦某個部分（例如策略引擎或審批流程）唔匹配，就要分支、繞路或重寫，最終好多團隊都要由頭搭建。

整理重點

生產級Harness嘅15項核心職責

文章詳細列出咗生產環境中Agent Harness需要處理嘅典型職責。呢啲職責缺一不可，尤其係企業級場景中，策略、審批、預算同Trace係避免「翻車」嘅關鍵。

  1. 1 接受並持久化 Turn（單次交互）請求
  2. 2 解析模型提供商憑證
  3. 3 查詢模型能力（視覺、工具、上下文窗口等）
  4. 4 驅動 per-Turn 狀態機（provision、stream、工具執行、steering、tear down）
  5. 5 加載並提供 Skill（工具描述）
  6. 6 組裝 System Prompt（模式、身份、默認技能等）
  7. 7 將 Token 流式返回客戶端
  8. 8 每個工具調用前嘅策略檢查

策略檢查、人工審批、預算控制同Trace係生產環境嘅「保險絲」

整理重點

推薦方法：模塊化Worker架構

Mike Piccolo嘅核心建議係唔好將Harness當成單一框架，而係構建成一組可安裝、可版本化、可替換嘅Worker，透過統一引擎同簡單原語（例如 iii.trigger()）連接。喺iii系統示例中，默認棧包含約11個Worker，每一個獨立運行、獨立版本，透過總線註冊函數同觸發器。

可安裝、可版本化、可替換嘅Worker

單次Turn嘅執行鏈路簡化版：客戶端觸發 → 持久化 + 狀態機啟動 → Provisioning（沙箱、Skill下載、Prompt組裝）→ 模型Streaming → 工具調用 → 策略檢查 → （必要時）人工審批 → 執行 + Hook → Steering（決定繼續或結束）+ 上下文壓縮 + Trace記錄 → 事件流推送到UI。

薄 vs 厚Harness：透過滑塊調整，少裝幾個Worker就係輕量版（適合實驗），全裝加自定義就係企業級厚版（帶嚴格治理）。

整理重點

框架 vs 模塊化：點樣揀？

理性看待框架：優勢係上手快、社區成熟，適合MVP或小團隊快速驗證。但風險係規模化後定製成本高、Trace唔完整、治理能力弱，一年後往往面對「要麼忍受，要麼重寫」嘅困境。

規模化後，定製成本高、Trace唔完整、治理能力弱

模塊化Worker嘅優勢：靈活性（語言無關、獨立升級、易於集成現有企業系統）、可觀測性（統一Trace貫穿所有步驟）、安全性與合規（Fail-closed默認拒絕、審批路由、預算控制易實現）、成本控制（按需組裝，避免過度工程）。當然，搭建Worker體系需要一定架構投入，如果Agent只係內部簡單自動化，成熟框架加少量擴展可能夠用。

整理重點

實用建議與避坑指南

  1. 1 先評估需求：列出Agent需要嘅職責，尤其策略、預算、審批、Trace。如果已有框架滿足80%，先優化；否則考慮模塊化路徑。
  2. 2 強烈推薦直接讀Mike Piccolo原文，裏面有詳細Worker列表、Turn執行流程圖同替換示例。
  3. 3 從小處實踐：嘗試開源iii Harness bundle，Clone後本地運行，體驗Worker插拔靈活性；從核心（Turn Orchestrator + Provider + Policy）開始搭建，逐步添加。
  4. 4 企業落地Tips：把Harness當成系統一部分，而非孤立層；優先解決觀測性同治理；確保多語言支援同版本化；持續監控成本同性能。
  5. 5 避免常見坑：唔好過度追求全自動，Human-in-the-Loop喺高風險場景至關重要；上下文壓縮同Prompt組裝直接影響Token消耗同效果。

成本預算Worker唔係錦上添花，而係必需模塊

最後，Harness係基礎設施，更係長期競爭力。Agent嘅價值最終取決於能否喺真實業務中穩定交付成果。選框架係起點，但構建可組合、可演化嘅Harness先係通往生產級嘅必經之路。

近排，AI Agent（智能體）開始由概念變到真係落地，企業越嚟越關心點樣可以令到Agent喺生產環境入面穩定、高效、安全咁運行。日前Mike Piccolo（iii.dev創辦人）分享咗一篇深度文章，《How to Build Your Own Agent Harness》，引嚟唔少討論。

呢篇文章唔係淨係sell某個框架，而係系統咁拆解咗生產級Agent Harness（智能體框架）嘅本質。今日，我哋就夾埋原文嘅內容，分享一啲核心觀點同生產建議，幫大家少啲行冤枉路。

圖片

咩係Agent Harness？點解佢比模型本身更加關鍵？

簡單講，Agent = 模型 + Harness。LLM（大語言模型）就好似一個聰明嘅大腦，但要令佢真係「做到嘢」，就需要一個可靠嘅「身體」，呢個就係Harness。佢負責工具調用、狀態管理、策略控制、預算追蹤、上下文處理等一系列嘅基建工作。

Mike Piccolo指出：大部分團隊唔係喺度整Harness，而係直接「用」一個框架（例如LangChain、LangGraph、OpenAI Agents SDK、CrewAI等）。將循環、工具、記憶、編排全部打包成一個決定。一旦有某個部分（例如策略引擎或者審批流程）唔啱用，就要分支、繞路或者重寫，最終好多團隊都要由頭自己砌返個Harness。

上面的問題嘅核心，就係在於：Harness唔係「一樣嘢」，而係10至15個獨立職責嘅組合。單一嘅傳統框架好多時會將佢哋綁死，呢個就限制咗靈活性。

生產級Harness一定要承擔嘅15項核心職責

文章入面列出咗生產環境中Agent Harness需要處理／承擔嘅典型職責（以下總結有少少精簡）：

  1. 1. 接收同持久化Turn（單次交互）請求
  2. 2. 解析模型提供商嘅憑證
  3. 3. 查詢模型能力（視覺、工具、上下文窗口等）
  4. 4. 驅動per-Turn狀態機（provision、stream、工具執行、steering、tear down）
  5. 5. 加載同提供Skill（工具描述）
  6. 6. 組裝System Prompt（模式、身份、默認技能等）
  7. 7. 將Token串流返俾客戶端
  8. 8. 每個工具調用前嘅策略檢查
  9. 9. 需要人工審批嘅暫停同恢復
  10. 10. 追蹤LLM嘅花費同預算控制
  11. 11. 工具調用前後嘅Hook（日誌、脱敏、自定義副作用）
  12. 12. 以分支樹形式持久化Session，支援fork同resume
  13. 13. 上下文窗口滿咗嗰陣進行壓縮
  14. 14. 發出UI可以訂閲嘅事件流
  15. 15. 貫穿成個過程嘅OpenTelemetry Trace，方便除錯

呢啲職責一個都唔少得，特別係喺企業級場景入面，策略、審批、預算同Trace係避免「炒車」嘅關鍵。

推薦方法：模塊化做可插拔嘅Worker

Mike Piccolo嘅核心建議係唔好將Harness當成單一框架，而係砌成一組可安裝、可版本化、可替換嘅Worker，透過統一嘅引擎同簡單原語（例如 iii.trigger()）連接。

喺佢哋嘅iii系統示例入面，默認棧包含大約11個Worker（例如turn-orchestrator、harness元Worker、approval-gate、llm-budget、唔同provider等）。每個Worker獨立運行、獨立版本，透過總線註冊函數同觸發器。

圖片

單次Turn嘅執行鏈路（簡化版）：

  • • 客戶端觸發 → 持久化 + 狀態機啟動
  • • Provisioning（沙箱、Skill下載、Prompt組裝）
  • • 模型Streaming
  • • 工具調用 → 策略檢查 → （有需要時）人工審批 → 執行 + Hook
  • • Steering（決定繼續定結束）+ 上下文壓縮 + Trace 記錄
  • • 事件流推送俾UI

呢種設計令到「自己整」變得簡單：想換策略引擎？寫一個註冊相同函數嘅Worker換走就得；想加新模型provider？加一個新Worker就得，唔使重構成個系統。

薄 vs 厚Harness：唔係二揀一，而係一種「滑塊」調整。裝少幾個Worker就係輕量版（適合實驗）；全部裝曬加自定義就係企業級厚版（有嚴格治理），透過配置調整就可以切換。

分析：框架綁定 vs 模塊化，邊個更適合企業？

理性看待框架：

  • • 優勢：上手快、社區成熟，適合MVP或者細團隊快速驗證。
  • • 風險：規模化之後，定製成本高、Trace唔完整、治理能力弱。一年後好多時會面臨「一係忍，一係重寫」嘅困境。

模塊化Worker嘅優勢：

  • • 靈活性：語言無關（支援多語言SDK）、獨立升級、容易集成現有企業系統（Secrets Manager、OPA/Cedar策略等）。
  • • 可觀測性：統一Trace貫穿所有步驟，除錯效率高。
  • • 安全性與合規：Fail-closed（默認拒絕）、審批路由、預算控制更容易實現。
  • • 成本控制：按需要組裝，避免過度工程。

當然，冇萬能嘅選擇。建立Worker體系本身就需要一定嘅架構投入。如果你嘅Agent只係內部簡單自動化，成熟框架加少量擴展可能已經夠。但係對於長期生產落地、涉及敏感操作或者多團隊協作嘅企業，模塊化思路更加可持續。

實用建議：點樣揀？

  1. 1. 先評估需求：列出你嘅Agent需要邊啲職責（尤其係策略、預算、審批、Trace）。如果現有框架滿足到八成，先優化佢；否則考慮模塊化路徑。
  2. 2. 強烈建議直接睇Mike Piccolo篇文（iii.dev博客），入面有詳細Worker列表、Turn執行流程圖同替換示例。
  3. 3. 由細位開始實踐：
    • ◦ 試嚇開源嘅iii Harness bundle，clone之後本地運行，體驗Worker插拔嘅靈活性。
    • ◦ 由核心（例如Turn Orchestrator + Provider + Policy）開始砌，逐步加。
    • ◦ 重視FSM（有限狀態機）：佢係單次Turn可靠執行嘅基礎。
  4. 4. 企業落地Tips：
    • ◦ 將Harness當做「系統嘅一部分」，唔係孤立層。Agent本身都可以係Worker。
    • ◦ 優先處理觀測性同治理：Trace同審批係生產環境嘅「保險絲」。
    • ◦ 多語言支援同版本化：方便唔同團隊協作。
    • ◦ 持續監控成本同性能：預算Worker唔係錦上添花，而係必要嘅模塊。
  5. 5. 避免常見陷阱：唔好太過追求「全自動」，Human-in-the-Loop（人工審批）喺高風險場景入面好重要；上下文壓縮同Prompt組裝直接影響token消耗同效果。

最後：Harness係基建，更加係長期競爭力

Agent嘅價值最終取決於可唔可以喺真實業務入面穩定咁交出成果。揀框架係起點，但係砌一個可組合、可演化嘅Harness先係通往生產級嘅必經之路。Mike Piccolo嘅分享提醒我哋：技術選型要服務於業務靈活性，而唔係反過嚟被綁死。

如果你正在整或者優化企業Agent，歡迎喺評論區分享你嘅經驗。我哋一齊交流，推動AI由「行得鬱」到「可靠咁賺錢」。

圖片

參考同延伸閲讀：

  • • 《How to Build Your Own Agent Harness》 https://iii.dev/blog/how-to-build-your-own-agent-harness/
  • • https://x.com/mfpiccolo/status/2060069083878408689
  • • iii.dev相關開源項目
  • • @shao__meng嘅分享帖

（本文係根據公開分享內容整理，觀點盡量客觀理性。如果有更新，以原文為準。）

近年來，AI Agent（智能體）逐漸從概念走向落地，企業越來越關注如何讓Agent在生產環境中穩定、高效、安全地運行。近日Mike Piccolo（iii.dev創始人）分享了一篇深度文章，《How to Build Your Own Agent Harness》，引發了不少討論。

這篇文章不是簡單推銷某個框架，而是系統拆解了生產級Agent Harness（智能體框架）的本質。今天，我們就結合原文內容，分享一些核心觀點和生產建議，幫助大家少走彎路。

圖片

什麼是Agent Harness？為什麼它比模型本身更關鍵？

簡單說，Agent = 模型 + Harness。LLM（大語言模型）就像聰明的大腦，但要讓它真正“做事”，需要一個可靠的“身體”，這就是Harness。它負責工具調用、狀態管理、策略控制、預算追蹤、上下文處理等一系列基礎設施工作。

Mike Piccolo指出：大多數團隊不是在構建Harness，而是直接“採用”一個框架（如 LangChain、LangGraph、OpenAI Agents SDK、CrewAI等）。把循環、工具、記憶、編排全部打包成一個決策。一旦某個部分（如策略引擎或審批流程）不匹配，就得分支、繞路或重寫，最終很多團隊還是得從頭搭建自己的Harness。

上面的問題核心，就在於：Harness不是“一個東西”，而是10-15個獨立職責的組合。單一的傳統框架往往把它們綁死，這也限制了靈活性。

生產級Harness必須承擔的15項核心職責

文章中列出了生產環境中Agent Harness需要處理/承擔的典型職責（以下總結略有精簡）：

  1. 1. 接受並持久化 Turn（單次交互）請求
  2. 2. 解析模型提供商憑證
  3. 3. 查詢模型能力（視覺、工具、上下文窗口等）
  4. 4. 驅動 per-Turn 狀態機（provision、stream、工具執行、steering、tear down）
  5. 5. 加載並提供 Skill（工具描述）
  6. 6. 組裝 System Prompt（模式、身份、默認技能等）
  7. 7. 將 Token 流式返回給客戶端
  8. 8. 每個工具調用前的策略檢查
  9. 9. 需要人工審批的暫停與恢復
  10. 10. 追蹤 LLM 花費與預算控制
  11. 11. 工具調用前後的 Hook（日誌、脱敏、自定義副作用）
  12. 12. 以分支樹形式持久化 Session，支持 fork 和 resume
  13. 13. 上下文窗口滿時進行壓縮
  14. 14. 發出 UI 可訂閲的事件流
  15. 15. 貫穿全程的 OpenTelemetry Trace，便於調試

這些職責缺一不可，尤其是在企業級場景中，策略、審批、預算和 Trace是避免“翻車”的關鍵。

推薦方法：模塊化為可插拔的Worker

Mike Piccolo的核心建議是不要把Harness當成單一框架，而是構建成一組可安裝、可版本化、可替換的Worker，通過統一的引擎和簡單原語（如 iii.trigger()）連接。

在他們的iii系統示例中，默認棧包含約11個Worker（如turn-orchestrator、harness元Worker、approval-gate、llm-budget、各種 provider等）。每個Worker獨立運行、獨立版本，通過總線註冊函數和觸發器。

圖片

單次Turn的執行鏈路（簡化版）：

  • • 客戶端觸發 → 持久化 + 狀態機啓動
  • • Provisioning（沙箱、Skill下載、Prompt組裝）
  • • 模型Streaming
  • • 工具調用 → 策略檢查 → （必要時）人工審批 → 執行 + Hook
  • • Steering（決定繼續或結束）+ 上下文壓縮 + Trace 記錄
  • • 事件流推送到 UI

這種設計讓“自建”變得簡單：想換策略引擎？寫一個註冊相同函數的Worker替換即可；想加新模型provider提供商？新增一個Worker即可，無需重構整個系統。

薄 vs 厚Harness：不是二選一，而是一種“滑塊”調整。少裝幾個Worker就是輕量版（適合實驗）；全裝 + 自定義就是企業級厚版（帶嚴格治理），通過配置調整即可切換。

分析：框架綁定 vs 模塊化，誰更適合企業？

理性看待框架：

  • • 優勢：上手快、社區成熟，適合MVP或小團隊快速驗證。
  • • 風險：規模化後，定製成本高、Trace不完整、治理能力弱。一年後往往面臨“要麼忍受，要麼重寫”的困境。

模塊化Worker的優勢：

  • • 靈活性：語言無關（支持多語言 SDK）、獨立升級、易於集成現有企業系統（Secrets Manager、OPA/Cedar策略等）。
  • • 可觀測性：統一Trace貫穿所有步驟，調試效率高。
  • • 安全性與合規：Fail-closed（默認拒絕）、審批路由、預算控制更易實現。
  • • 成本控制：按需組裝，避免過度工程。

當然，沒有萬能的選擇。搭建Worker體系本身就需要一定的架構投入。如果你的Agent只是內部簡單自動化，成熟框架+少量擴展可能就夠了。但對於長期生產落地、涉及敏感操作或多團隊協作的企業，模塊化思路更可持續。

實用建議：如何選擇？

  1. 1. 先評估需求：列出你的Agent需要哪些職責（尤其是策略、預算、審批、Trace）。如果已有框架滿足80%，先優化它；否則考慮模塊化路徑。
  2. 2. 強烈推薦直接讀Mike Piccolo的文章（iii.dev博客），裏面有詳細Worker列表、Turn執行流程圖和替換示例。
  3. 3. 從小處實踐：
    • ◦ 嘗試開源的iii Harness bundle，clone後本地運行，體驗Worker插拔帶來的靈活性。
    • ◦ 從核心（如Turn Orchestrator + Provider + Policy）開始搭建，逐步添加。
    • ◦ 重視FSM（有限狀態機）：它是單次Turn可靠執行的基礎。
  4. 4. 企業落地Tips：
    • ◦ 把Harness當成“系統的一部分”，而非孤立層。Agent本身也可以是Worker。
    • ◦ 優先解決觀測性和治理：Trace和審批是生產環境的“保險絲”。
    • ◦ 多語言支持和版本化：便於不同團隊協作。
    • ◦ 持續監控成本和性能：預算Worker不是錦上添花，而是必需的模塊。
  5. 5. 避免常見坑：不要過度追求“全自動”，Human-in-the-Loop（人工審批）在高風險場景中至關重要；上下文壓縮和Prompt組裝直接影響token消耗和效果。

最後：Harness是基礎設施，更是長期競爭力

Agent的價值最終取決於能否在真實業務中穩定交付成果。選框架是起點，但構建可組合、可演化的Harness才是通往生產級的必經之路。Mike Piccolo的分享提醒我們：技術選型要服務於業務靈活性，而不是反過來被綁定。

如果你正在構建或優化企業Agent，歡迎在評論區分享你的經驗。我們一起交流，推動AI從“能跑”到“可靠賺錢”。

圖片

參考與延伸閲讀：

  • • 《How to Build Your Own Agent Harness》 https://iii.dev/blog/how-to-build-your-own-agent-harness/
  • • https://x.com/mfpiccolo/status/2060069083878408689
  • • iii.dev相關開源項目
  • • @shao__meng的分享帖

（本文基於公開分享內容整理，觀點力求客觀理性。如有更新，以原文為準。）