拆解 harness：AI Agent 的能動性到底從哪來（AI Agent 架構全解析 1/8）

先講結論：讓 agent 會「動」的，不是那顆模型

你每天用的 ChatGPT、Claude，本質上是一次問、一次答：你丟一段文字進去，它吐一段文字出來，然後就結束了。它可以在回答裡「說」自己要去查資料、改檔案、寄信，但它一件也做不了——沒有手、沒有記憶、沒有權限。

那為什麼像 Claude Code 這種東西，可以真的打開你的 repo、改十幾個檔案、跑測試、看到紅字再回頭修？

答案不在模型身上，在模型外面那一圈程式碼。這圈程式碼有個名字，叫 harness（骨架、外層架構）。模型負責推理與決策；harness 負責給它工具、幫它記住狀態、在它闖禍前先攔一手。一句話：agent 的能動性，是 harness 給的，不是模型自帶的。

這是一個 8 篇的系列。我會帶你從最裡面那個小小的迴圈開始，一層一層把 harness 拆開，看清楚一個現代 AI agent 到底由哪些零件組成。這一篇是開篇導讀——先讓你看懂全貌，後面 7 篇再逐層鑽進去。內容全部來自一份很扎實的開源教材 hardness1020/awesome-agent-architecture，它把現代 agent 拆成 8 層、22 節，每節都附一支可以直接跑的 Python demo。

用餐廳廚房來想這件事

把 LLM 想成一個很強的主廚：腦子裡裝滿食譜，你報菜名，他立刻知道該怎麼做。但如果你把他一個人丟進空房間，他一道菜都端不出來——沒有爐台（沒地方執行動作）、沒有食材和備料檯（沒有工具跟觀察結果）、沒有出餐規則（沒有權限把關），也記不得上一張單點了什麼（沒有跨次狀態）。

harness 就是那間廚房：動線、爐具、冰箱、出餐窗口，還有「這道菜要不要先問過客人」的規矩。主廚（模型）依然是那個做判斷的人——決定先煎還是先燙、火候到了沒；但把判斷變成一盤真的能上桌的菜的，是整間廚房（harness）。

🍳 模型負責判斷，harness 負責環境。 這句話是整個系列的主軸。單獨一次模型呼叫只能對單一輸入產生一次回應——它可以「決定」要行動，卻無法自行行動，因為它沒有持久狀態、沒有工具執行器、碰不到檔案，也沒有權限關卡。

具體來說，harness 要接手四件模型自己做不到的事：

1. 給每個動作一個真的能執行的地方（跑工具的執行環境）。
2. 把執行結果變成模型看得懂的觀察，再餵回去。
3. 在副作用真的碰到你的檔案、系統之前，先過一道權限關卡。
4. 把狀態存下來，讓下一次呼叫接得上上一次。

拿掉 harness，模型就只能回話；它沒辦法執行工具、觀察結果，也沒辦法在多次呼叫之間記住工作進度。這也是為什麼同一顆模型，套上不同的 harness，可以是聊天機器人，也可以是能自己跑一整晚的自動化工人。

那個「小到你會嚇一跳」的核心迴圈

拆到最裡面，你會發現幾乎所有 agent 都共用同一套控制流程，而且它小得驚人：呼叫模型、執行它要求的工具、把結果接回去、再呼叫模型，如此反覆。

1
2
3
4
5
6
7

while True:
    resp = model(messages)            # 呼叫模型，帶著到目前為止的對話
    if resp.stop_reason == "end_turn":
        break                         # 模型說「講完了」，回覆使用者
    for call in resp.tool_calls:      # 模型回傳 stop_reason=tool_use，代表它要用工具
        result = run_tool(call)       # harness 執行工具，拿到觀察結果
        messages.append(result)       # 把結果接回對話，進下一圈

預期行為：模型每要一次工具，harness 就跑一次、把結果接回 messages[]，直到模型不再要工具、回傳 end_turn 為止。就這樣。

重點在於：這個迴圈本身很小，真正的工程幾乎全都長在它周圍——派發工具、控管副作用、管理塞不下的 context、保存狀態、協調其他迴圈。你之後會讀到的每一層，本質上都是在這個小迴圈外面再包一圈東西：不是取代它，而是供給它、替它把關、幫它記住事情。

兩個被攤開來看的真實系統

這份教材不講空泛的理論，它拿兩個真實系統當解剖對象，讓你看每個機制在正式產品裡到底長什麼樣。

為什麼挑這兩個？因為它們剛好站在光譜兩端：Claude Code 是「你盯著它工作」的互動式工具，Hermes 是「它自己在背景長期待命」的助理。把兩者對照著看，你會發現差別大多不在模型，而在 harness 的設計選擇。學會這一套，你手上就有一把能看穿各種 agent 的尺——不管它叫 coding 工具、聊天助理，還是無人值守的執行器。

8 層 22 節：後面 7 篇的地圖

整份教材像蓋樓一樣，從最底下那個核心迴圈開始，一層疊一層，最後疊出一個能自己運轉的 harness。本系列的 8 篇文章，就對著這 8 層走：這一篇（篇 1）打地基，接下來 7 篇各拆一層。

每一章都用同一組四個面向來看，你讀起來會很有節奏：開場（這一層要解決什麼問題）、機制（一般性的設計與控制流程）、各系統做法（真實系統怎麼實作）、失效模式（什麼會出錯、怎麼緩解）。作者也給了一個很聰明的讀法：把某一章的 src/ 跟前一章做 diff，那個差異就是這一章新加的那個機制——程式碼是一章一章長出來的，看 diff 就看得到骨架怎麼變厚。

為什麼工程師該把這系列讀完

如果你只是「會用」agent，這套東西可能可有可無。但只要你開始想自己接一個 agent、或想搞懂手上這個 agent 為什麼時好時壞，這張地圖幾乎是必修。

• 你想自己做 agent、或改造現成的： 你會知道每個能力該落在哪一層——工具註冊放哪、權限關卡放哪、記憶跟 context 該怎麼分工。不會再把所有邏輯全塞進一個 prompt 裡硬撐。
• 你在維護一個會出包的 agent： 這份教材最實用的一句話是——多數行為與多數 bug 都住在 harness，不住在模型。搞清楚分層，你 debug 時就知道該去翻哪一圈程式碼，而不是一直怪模型「怎麼又亂答」。
• 你要評估或選型： 面對市面上一堆 agent 產品，你能穿過行銷話術，直接問「它的迴圈、工具、記憶、權限是怎麼設計的」，用同一把尺比較。
• 你想動手驗證： 每個可執行章節都附 test.py（離線、不用金鑰）跟 demo.py（打真的 API）。看不懂的機制，跑一遍就懂了。

⚠️ 兩個提醒。其一：harness 是把雙面刃——它帶來安全性、持久化、subagent 跟隨需載入的知識，但它同時成為主要的程式碼表面，也是 bug 最愛住的地方，加每一層都是多一份要維護的成本。其二：要跑書裡的 demo，你需要一把 Anthropic API key（會實際消耗額度），離線的 test.py 則不用。

一個常見的踩雷這裡先破：不要把該由模型做的判斷寫死。僵硬的工具順序、寫死的規劃流程，會跟模型的判斷正面對撞——需要判斷的地方，就讓模型去決定；需要保證跟把關的地方，才交給 harness。這條界線抓對了，後面每一層你都會讀得很順。

下一篇

地基打好了。篇 2 我們就鑽進第 1 層那個核心迴圈——messages[] 怎麼滾、stop_reason 怎麼決定 agent 是繼續動作還是收工，還有工具是怎麼被路由跟呼叫的。那是整座樓真正開始「動起來」的地方，我們下篇見。