May 3, 2026

Agent Zero：把整個 Linux 系統當工具的 AI Agent 框架

2025 年中，我在評估各種 Agent 框架時，發現一件奇怪的事：幾乎所有框架都在努力替 Agent 預先包好一堆工具（search、code execute、file read），假裝這就是「能做事」的定義。但如果你看實際使用場景，這些預設工具很快就不夠用，然後就是漫長的 plugin 開發、prompt engineering、 workaround。

Agent Zero 的切入點很不一樣：它乾脆不包工具。它給 Agent 一台完整的 Kali Linux 容器，讓 Agent 自己用 terminal、寫 script、裝套件、創造工具。

這個設計選擇，徹底改變了框架的複雜度分布：困難的事從「框架設計者要預見所有需求」變成「讓 Agent 可以自由折騰 Linux」。

本文深度解析 Agent Zero 從 0 到 17.5K Stars 的技術架構。

Monologue Loop：框架的心臟

Agent Zero 的 execution model 是一個稱為 monologue 的 async loop，定義在 agent.py:Agent.monologue()（~160 行）。結構如下：

while True:                          # 外層：monologue
  monologue_start extensions
  while True:                        # 內層：message loop
    message_loop_start extensions
    prepare_prompt()
    call_chat_model(streaming=True)
    extract JSON tool request
    execute tool
    if tool == "response": break     # 最後由 response tool 終止
  monologue_end extensions

每次迴圈迭代，Agent 從 LLM 拿到一個 JSON 回應，格式大致是：

{
  "thoughts": "...",
  "tool_name": "code_execution_tool",
  "tool_args": { "command": "pip install requests" }
}

框架解析後執行對應 tool，把結果附加到 history，然後進入下一個 iteration。這個設計乾淨到不可思議：沒有所謂的「規劃階段」或「反思階段」的 hard-coded 分離 -- 一切都只是另一個 tool call。

Extension Hook System

真正讓這個框架有別於簡單 while loop 的，是它的 extension 系統。整個 agent.py 函式幾乎每個關鍵點都有 @extension.extensible decorator，掛鉤點包括：

Hook Name	觸發時機
`monologue_start/end`	整個 monologue 生命週期
`message_loop_start/end`	每個 message iteration
`message_loop_prompts_before/after`	Prompt 組裝前後
`before_main_llm_call`	LLM 叫用前
`reasoning_stream_chunk/end`	思考輸出串流
`response_stream_chunk/end`	回應輸出串流
`tool_execute_before/after`	Tool 執行前後
`process_chain_end`	Agent 處理鏈終止

Extension 實作分布在 extensions/python/ 和 extensions/webui/ 目錄，命名以數字開頭控制執行順序（如 _10_、_90_）。

這套 hooks 的實際用途：記憶管理、行為注入、歷史摘要、response 後處理。整個 framework 的 cross-cutting concerns 幾乎都透過 extension 實現，核心 agent.py 因此維持在 1000 行左右。

Multi-Agent 階層協作

Agent Zero 內建一個完整的 hierarchical multi-agent 模型，實作在 tools/call_subordinate.py。

任何 Agent 都可以透過 call_subordinate tool 建立下屬 Agent：

sub = Agent(self.agent.number + 1, config, self.agent.context)
sub.set_data(Agent.DATA_NAME_SUPERIOR, self.agent)
self.agent.set_data(Agent.DATA_NAME_SUBORDINATE, sub)
subordinate.hist_add_user_message(UserMessage(message=message, attachments=[]))
result = await subordinate.monologue()

下屬 Agent 有完全獨立的 monologue loop、history、和 context。執行完後，結果以 Response(message=result, break_loop=False) 形式回傳給 superior。

這個設計的關鍵限制（寫在 agent.system.main.solving.md）：

"never delegate full to subordinate of same profile as you"

意思是下屬應該有不同的 prompt profile，否則等於複製自己，沒有分工價值。

call_subordinate 支援 profile 參數，可以指定下屬使用的 Agent Profile（不同的 prompt 集合、tools、和 model config）。這讓同一個 framework 可以運行多個不同專業的 agent。

运行时架構：雙 Python Runtime

Agent Zero 跑在 Docker 容器裡，但它的 runtime 設計有一個很多人沒注意到的小巧思：它使用 兩個 Python virtualenv：

Runtime	Python 版本	用途
`/opt/venv-a0`	3.12	Framework 本身（API、WebUI、Agent 管理）
`/opt/venv`	3.13	Agent 的 code execution（pip install 套件在這裡）

這個分離的用意：Agent 安裝新套件時不會污染 framework 自己的 Python 環境。Framework 使用的 litellm、langchain、flask、socket.io 維持在一組可控的依賴裡，Agent 自己折騰的 pip install 全在另一個乾淨的 venv。

a0 CLI connector 解決了另一個問題：如何讓 container 內的 Agent 讀寫 host 機器的檔案。安裝 connector 後，Agent 可以獲得 host 的 filesystem 和 shell 存取權限，但需要 user 明確授權 Read+Write 模式。

限制與使用情境

Agent Zero 不是一個容易上手的框架。這是它的設計選擇，不是缺點，但確實影響適用範圍。

適合使用 Agent Zero 的場景：

實驗性的 agent 研究，需要快速調整 agent 行為邏輯
需要多個不同專業 agent 協作的複雜任務
任務需求變化大，無法事先定義完整 workflow

不太適合的場景：

對延遲和可靠性要求高的 production 系統
只需要簡單 tool calling 的場景（用 LangGraph 或 Mastra 更省事）
團隊中非技術人員需要操作 agent 的場景（prompt 改壞了後果自負）