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

但當我想進一步理解它們時，發現大部分教學都集中在「怎麼使用」，很少真的解釋：

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

因此，我花了大約兩個月研究 Claude Code 的架構，並把研究結果整理成開源專案：

Awesome Agent Architecture

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

目前專案已累積超過 200 顆 Stars，採用 MIT License。

LLM 本身並不是 Agent

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

但模型本身只負責根據輸入產生下一個輸出。真正讓它能夠讀取檔案、執行指令、修改程式碼、保存狀態，甚至持續工作數十分鐘的，是模型外面的系統。

這層系統通常被稱為 Agent Harness。

最小的 Agent Loop 其實非常簡單：

1. 將訊息傳給模型
2. 模型決定是否呼叫工具
3. 系統執行工具
4. 將工具結果放回對話
5. 再次呼叫模型
6. 重複直到任務結束

真正困難的部分，通常都在這個 Loop 外圍：

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

一個 Coding Agent、一個聊天助理，以及一個自動化執行器，底層可能使用相似的模型。它們真正的差別，很多時候來自 Harness 的設計選擇。

從 Claude Code 開始拆解 Agent

這個 Repo 目前主要研究兩套 Agent 系統：

• Claude Code：適合觀察完整的 Coding Agent Harness
• Hermes Agent：適合研究 Memory、Skills、長期執行與不同操作介面

我沒有只整理功能列表，而是把每個機制拆成獨立章節。

內容從第 0 節開始，一路延伸到第 21 節，包含：

Foundations

先釐清模型與 Harness 的責任邊界，以及 Agent 的行動能力到底從哪裡來。

Core Loop

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

• Tool Runtime
• Permission 與 Sandbox
• Hooks

Complex Work

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

• Planning 與 Todos
• Subagents
• Skills
• Context Management

Knowledge 與 Resilience

接著處理長時間工作時會遇到的問題：

• 跨 Session Memory
• System Prompt 組裝
• 錯誤恢復
• Context Overflow

Long-running Tasks

讓 Agent 不再只依賴一次對話完成工作：

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

Multi-Agent

進一步拆解多個 Agent 如何：

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

Integration 與 Evaluation

最後再處理 Agent 如何連接外部系統，以及如何知道它是否真的有效：

• MCP
• Plugins
• Channels
• Observability
• Evaluation
• Loop Engineering

每一節都只增加一個核心機制

我在設計這個 Repo 時，最在意的是不要讓讀者只能看架構圖和文字說明。

第 1 節到第 21 節都有可執行的 Python 範例，而且程式碼會隨著章節逐步演進。

例如：

第 1 節只有最小的 Agent Loop。

第 2 節加入 Tool Runtime。

第 3 節加入 Permission。

第 4 節再加入 Hooks。

你可以直接比較相鄰兩個章節的 src/，從 Git Diff 中看到這一節到底新增了什麼機制。

每個章節也會使用相同的分析方式：

1. 這個 Layer 解決什麼問題
2. 一般化的設計與控制流程
3. 真實 Agent 系統如何實作
4. 常見 Failure Modes 與改善方式

我的目標不是讓大家複製一套「標準 Agent 架構」。

相反地，我希望讀者理解每個元件解決的問題，以及加入它之後需要承擔的成本。

理解這些機制之後，未來看到新的 Agent Framework，就不需要重新從產品名稱開始學習，而是可以直接判斷：

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

接下來會整理成鐵人賽系列

目前 Repo 比較接近技術文件與架構參考，適合想直接研究完整系統的人。

接下來，我也計畫把這些內容重新整理成 iT 邦幫忙鐵人賽系列，從最小的 Agent Loop 開始，每天增加一個機制。

預計會依序討論：

• Agent Loop
• Tool Use
• Permission
• Hooks
• Planning
• Subagent
• Skills
• Context Management
• Memory
• Background Tasks
• Multi-Agent Coordination
• MCP 與 Plugins
• Observability
• Loop Engineering

每一篇都會盡量搭配可以執行的 Python 範例，不只介紹名詞，也會實際觀察訊息、工具結果和狀態如何在系統中流動。

如果你正在研究 AI Agent、Claude Code、Agent Harness 或 Agent Infrastructure，歡迎先看看 Repo。

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

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

有任何架構上的問題、不同觀察或想研究的 Agent，也可以直接開 Issue 一起討論。