從 Agent Loop 出發，逐步拆解模型外圍的工具、狀態、權限、Memory 與協作機制

一、專案資訊

專案名稱： Awesome Agent Architecture

專案類型： 開源技術教學／AI Agent 架構參考

主要技術： Python、AI Agent、Harness Engineering

開發狀態： 已上線，持續更新中

授權方式： MIT License

GitHub： https://github.com/hardness1020/awesome-agent-architecture

Awesome Agent Architecture 是一個從 0 開始拆解 AI Agent 架構的開源專案

專案從最小的 Agent Loop 開始，逐步加入 Tool Runtime、Permission、Hooks、Skills、Context Management、Memory、Subagent、Background Tasks、MCP、Multi-Agent Coordination、Observability 與 Evaluation

每個章節都提供可以執行的 Python 範例，讓讀者不只是閱讀架構圖，也能實際觀察訊息、工具結果和系統狀態如何在 Agent 內部流動

目前專案包含 22 個章節，並已累積超過 300 顆 GitHub Stars

二、開發動機

很多人已經開始使用 Claude Code、Cursor、Codex 或其他 AI Agent

但當我想進一步理解這些工具時，發現大部分教學都集中在「怎麼使用」，很少真正解釋它們背後的系統如何運作

例如：

• Agent 為什麼可以持續執行任務？
• 模型如何呼叫工具？
• 權限、Hooks、Skills 和 MCP 如何接進系統？
• Context 快滿時，Agent 如何壓縮和保存資訊？
• Subagent 與 Multi-Agent 如何分工？
• Agent 如何從單次對話，變成可以長時間運作的系統？

因此，我研究了 Claude Code 與其他 Agent 系統，並把研究結果整理成 Awesome Agent Architecture

我希望這個專案能補上目前 Agent 教學中較少被討論的一塊：不只介紹功能怎麼使用，也解釋功能背後的架構、控制流程與設計取捨

三、LLM 本身並不是 Agent

一開始接觸 AI Agent 時，很容易把所有注意力放在模型上

但 LLM 本身只負責根據輸入產生下一個輸出

真正讓模型能夠讀取檔案、執行指令、修改程式碼、保存狀態，甚至持續工作數十分鐘的，是模型外面的系統

這層系統通常被稱為 Agent Harness，而設計與改善這套系統的工作則稱為 Harness Engineering

模型負責判斷下一步，Harness 負責提供工具、狀態、限制與實際執行環境

沒有 Harness，模型只能產生回覆，無法真正對外部世界採取行動

四、最小的 Agent Loop

雖然不同 Agent 的功能差異很大，但底層通常都建立在相似的循環上：

一次模型呼叫並不會形成 Agent，Harness 必須持續執行工具、加入結果並再次呼叫模型

基本控制流程可以拆成：

1. 將目前訊息傳給模型
2. 模型判斷是否需要呼叫工具
3. Harness 檢查工具權限
4. 系統執行工具
5. 將工具結果加入對話
6. 再次呼叫模型
7. 重複執行，直到任務完成

這個 Loop 本身並不複雜

真正困難的部分通常位於 Loop 外圍：

• 工具如何註冊與派送
• 哪些操作需要使用者批准
• 如何限制檔案與 Shell 權限
• 如何管理持續增長的 Context
• 如何從模型或工具錯誤中恢復
• 如何分派任務給 Subagent
• 如何追蹤背景任務
• 如何限制 Token、成本與執行次數
• 如何讓多個 Agent 同時工作而不互相干擾
• 如何驗證 Agent 是否真的完成任務

一個 Coding Agent、一個聊天助理，以及一個自動化執行器，底層可能使用相同或相似的模型

它們真正的差異，往往來自 Agent Harness 的設計選擇

五、專案技術架構

這個專案主要研究三套 Agent 系統：

Claude Code

Claude Code 適合用來觀察完整的 Coding Agent Harness

它涵蓋工具呼叫、權限、Hooks、Skills、Context、Subagent、Background Tasks 與 Multi-Agent 等機制

Hermes Agent

Hermes Agent 適合研究：

• 長期 Memory
• Skills
• Scheduling
• Always-on Channels
• 長時間執行
• 跨介面操作

mini-swe-agent

mini-swe-agent 是一個相對精簡的 SWE Agent，適合觀察：

• 最小可用 Agent Loop
• 工具與 Budget
• Evaluation Harness
• 約束下的任務執行

我沒有只整理這些系統的功能列表，而是將每個機制拆成獨立章節，再抽象成可以套用到其他 Agent 的通用架構

目前先從這三套系統開始，後續也會陸續加入更多開源與商用 Agent，並使用相同的分析框架比較它們的架構設計、控制流程與取捨

六、從一個 Loop 演進成完整 Agent

專案從第 0 節開始，一路延伸到第 21 節，共分成八層

專案從模型與 Harness 的責任邊界開始，逐步演進到能夠長時間執行、自我驗證與協作的完整 Agent 系統

Layer 0：Foundations

先釐清模型與 Harness 的責任邊界，以及 Agent 的行動能力從哪裡產生

Layer 1：Core Loop

從最小 Agent Loop 開始，逐步加入：

• Agent Loop
• Tool Runtime
• Permission 與 Sandbox
• Hooks

Layer 2：Complex Work

當任務開始變得複雜，系統需要加入：

• Planning 與 Todos
• Subagents
• Skills
• Context Management

Layer 3：Knowledge 與 Resilience

接著處理長時間工作時的知識保存與錯誤問題：

• 跨 Session Memory
• System Prompt Assembly
• Error Recovery
• Context Overflow

Layer 4：Long-running 與 Async

讓 Agent 不必依賴一次對話完成所有工作：

• Task System
• Background Execution
• Scheduling
• Git Worktree Isolation

Layer 5：Multi-Agent

處理多個 Agent 如何：

• 建立團隊
• 傳送訊息
• 分配任務
• 審核計畫
• 完成 Shutdown Handshake
• 自主領取工作

Layer 6：Extension 與 Integration

讓 Agent 能與外部系統連接：

• MCP
• Plugins
• Channels
• Tool Pool Assembly

Layer 7：Composition

最後將前面的機制組合起來：

• Observability
• Evaluation
• Verification
• Loop Engineering

七、每一節只增加一個核心機制

這個專案最重要的設計原則，是避免一開始就把所有 Agent 功能放進同一個大型範例

例如：

• 第 1 節只有最小 Agent Loop
• 第 2 節加入 Tool Runtime
• 第 3 節加入 Permission
• 第 4 節加入 Hooks
• 第 5 節加入 Planning
• 第 6 節加入 Subagent

每一章的程式碼都建立在前一章的基礎上。

讀者可以直接比較相鄰兩章的 src/ 目錄，透過 Git Diff 看到這一章究竟新增了什麼：

• 新增了哪些類別與函式
• 訊息流程在哪裡改變
• 新機制攔截了哪個執行階段
• 系統狀態增加了哪些欄位
• 這個功能帶來哪些額外成本

這種方式比直接閱讀一個完整 Framework 更容易理解，因為每次只需要關注一個變化

八、核心技術挑戰

挑戰一：如何將產品實作抽象成通用架構

Claude Code 中的許多功能都有特定產品名稱

如果只是照著功能名稱介紹，內容會變成 Claude Code 使用手冊，而不是可以套用到其他 Agent 的架構知識

因此，我將產品功能重新抽象成通用問題：

• Permission 對應 Tool Policy Enforcement
• Todo 對應 Explicit Task State
• Subagent 對應 Context 與 Responsibility Isolation
• Memory 對應 Selection、Storage、Recall 與 Consolidation
• Background Task 對應非同步工作的生命週期管理
• MCP 對應外部工具與資源的標準化介面

未來即使出現新的 Agent Framework，也可以使用相同概念分析它

挑戰二：讓範例簡單，但不能失去真實性

如果範例過度簡化，讀者只能理解概念，卻看不到真實系統中的控制流程

但如果直接放入完整 Production 架構，又會出現大量與目前章節無關的程式碼

我的解法是讓每一章只加入一個主要變化，同時保留真實 Agent 會出現的資料流：

• Model Request
• Tool Call
• Permission Decision
• Tool Result
• Hook Event
• Context Update
• Task State
• Retry 與 Recovery
• Final Verification

九、專案的解決方法

為了讓複雜的 Agent 架構可以被逐步理解，我採用了以下方法

Progressive Disclosure

只在真正需要時引入新概念

讀者不需要先理解完整 Production Agent，才能開始學習最小 Agent Loop

Diff-driven Learning

相鄰章節保持相似，只修改與當前主題相關的程式碼

Git Diff 本身就是這一章的學習內容

Runnable Examples

第 1 到第 21 節都附有可以執行的 Python 範例

每一章包含：

• src/loop.py
• 對應機制的模組
• test.py
• demo.py

其中 test.py 可以離線執行，不需要 API Key；demo.py 則可以連接模型觀察完整流程

Architecture before Framework

先解釋問題與架構，再討論特定 Agent 如何實作

這樣知識就不會被綁定在單一 Framework 或產品上

Failure-oriented Design

除了正常執行流程，每章也整理常見 Failure Modes，例如：

• Tool 執行失敗
• Context Overflow
• Memory Recall 雜訊過多
• Subagent 遺失重要資訊
• Background Task 失去追蹤
• Agent 提早宣告完成

十、這個專案適合誰

這個 Repo 適合：

• 想從 0 開始理解 AI Agent 的開發者
• 已經在使用 Claude Code、Cursor 或 Codex，但想理解底層架構的人
• 正在設計 Agent Framework 或 Agent Infrastructure 的工程師
• 想理解 Tool Use、Memory、Context 和 Subagent 差異的人
• 想將 Agent 從 Demo 推進到可靠執行的人
• 想比較不同 Agent 產品架構選擇的人

我的目標不是提出一套所有人都應該複製的「標準 Agent 架構」

不同產品需要的 Harness 複雜度並不相同

一個只負責回答問題的 Agent，可能不需要 Background Tasks；一個只能讀取資料的 Agent，也不一定需要複雜的 Permission System

真正重要的是理解每個元件解決什麼問題，以及加入後需要承擔哪些成本

理解這些機制後，未來遇到新的 Agent Framework，就可以直接分析：

• 它的 Loop 如何運作？
• 工具如何被限制？
• Context 如何管理？
• Memory 保存在哪裡？
• Subagent 如何隔離？
• 多個 Agent 如何交換訊息？
• 系統如何驗證結果？
• Agent 失敗時如何恢復？

十一、歡迎交流

如果你正在研究 AI Agent、Claude Code、Agent Harness 或 Agent Infrastructure，歡迎查看專案：

https://github.com/hardness1020/awesome-agent-architecture

如果內容對你有幫助，也歡迎幫忙按個 Star

對架構有不同觀察、遇到實作問題，或有其他值得研究的 Agent，也歡迎直接開 Issue 一起討論