前言

如果只看 AI Agent 的 quickstart，很容易得到一種錯覺：準備一個模型、掛上幾個 tools，再寫一段 system prompt，Agent 就算完成了。真正開始做產品後，問題才一個個浮上來：工具結果怎麼放回 context？什麼時候停止？memory 如何評估？外部內容若藏有 prompt injection，Agent 還能不能安全執行？

最近研究的 bojieli/ai-agent-book，中文書名是《深入理解 AI Agent：設計原理與工程實踐》。它不是另一套 Agent framework，而是一個把書稿、程式、實驗 protocol 與執行證據放在一起的開源教材 repository。

這篇是 AI GitHub 專案研究系列的第一篇。我會從一個具體情境出發：如果團隊準備開發能搜尋資料、呼叫工具並保留執行軌跡的 Agent，這個專案究竟能教會我們什麼，又有哪些程式只能當實驗，不能直接搬進 production？

ai-agent-book 是什麼？

全書用一個簡單公式組織十章內容：

Agent = LLM + 上下文 + 工具

LLM 負責根據目前狀態選擇下一步，上下文保存 system instruction、使用者訊息、工具請求與觀察結果，工具則讓模型取得外部資訊或改變環境。後面的 memory、evaluation、post-training、Computer Use 與 multi-agent，其實都能回到這三個元素如何組合、觀察與改進。

截至查核 commit，README 將內容分成十章：

  1. Agent 基礎與 harness。
  2. Context engineering、prompt、compression 與 Agent Skills。
  3. User memory、RAG、結構化索引與知識圖譜。
  4. Tools、MCP、非同步 Agent 與工具發現。
  5. Coding Agent 與程式生成。
  6. Evaluation、benchmark 與統計比較。
  7. Pre-training、SFT、RL 與工具使用訓練。
  8. 從 trajectory 更新知識、指令、程式與模型。
  9. Speech、Computer Use 與 robotics。
  10. Multi-agent 協作與 context isolation。

Repository 官方統計是 95 個配套實驗，包含本地專案與外部復現軌道；本次研究沒有自行重算這個數字。十章與實驗索引 顯示它的廣度遠超過「教你呼叫一次 LLM API」，也意味著不同實驗的完成度、硬體與安全條件不可能完全相同。

它最適合解決哪一種學習斷層？

假設團隊要做一個研究助理：收到問題後先搜尋官方來源，必要時讀檔案、計算，再把答案與軌跡保存下來。

只讀 framework quickstart，可能知道如何宣告 tools，卻不清楚：

  • Assistant 回傳 tool call 後，哪一些欄位必須留在 history？
  • Tool output 如何用相同 tool_call_id 回填？
  • 多個 tool calls、JSON 格式錯誤與 token truncation 怎麼處理？
  • Agent 連續使用工具時，如何避免無限迴圈？
  • 保存 trajectory 時，哪些內容可能含個資、內部文件或敏感操作參數？
  • 一次 demo 成功，和可重複的 evaluation evidence 有什麼不同？

ai-agent-book 的價值在於讓這些中間狀態可以被閱讀。它刻意保留較低層的 message loop、provider resolution、validation artifact 與 experiment ledger，適合已經會 Python、想從「能呼叫模型」走到「看懂 Agent 系統」的人。

它不適合被當成 production SDK。根目錄的 agentbook package 版本仍是 0.1.0，定位是共用 provider 與實驗 plumbing，不是承諾穩定 API 的 runtime。pyproject.toml 也把大量依賴拆成 chapter extras，反映這是一組異質實驗，不是一個應用程式。

Repository 架構：書稿、實驗與證據三條線

書稿與多語發布

簡體中文原稿放在 book/，繁體中文、英文、日文等翻譯各有自己的目錄。README 明確提醒社群翻譯可能落後中文原稿，因此遇到版本敏感的技術主張，應回查原稿與程式碼，不能假設不同語言逐行同步。書稿與翻譯聲明

線上版由 GitHub Pages 建置；PDF 與 EPUB 則透過 workflow 更新到 latest prerelease。這個 latest 是會被覆寫的 rolling build，不是不可變版本。

章節實驗

chapter1/ 到 chapter10/ 各有獨立專案，從最小 ReAct loop 一路跨到 RAG、MCP、benchmark、training、speech、GUI 與 robotics。外部 benchmark 與大型訓練專案沒有全部 vendored 進 repository；README 另外列出固定 SHA 的外部 checkout，source 固定只建立復現起點，不代表資料集、模型、硬體或實驗結果已齊備。外部 repository 邊界

Experiment status 與 evidence

我認為最值得看的不是資料夾數量，而是 docs/EXPERIMENT_STATUS.md。官方把狀態分成 complete、incomplete 與 reader exercise，並明說 clone、安裝成功或 smoke test 通過，都不能當作實驗已完成。

台帳中同時存在：

  • 有完整 trajectory、manifest、hash 與 verifier 的 bounded campaign。
  • 結果沒有支持原假設的負面實驗。
  • 因 credential、CUDA、硬體、長時間執行或外部服務而未完成的項目。
  • 需要讀者自己執行並保存證據的 exercise。

這種記錄方式比一排成功 badge 更接近真正的研究與工程：它把「程式存在」「跑過一次」和「主張已有足夠證據」分開。

一次真實 Agent 執行的資料流

第 1 章的 Kimi Web Search Agent 是理解整本書很好的入口。它的資料流如下：

  1. CLI 解析 query、provider、model、最大步數與輸出檔案。
  2. 程式建立 system 與 user messages，清空 trace 和 API receipts。
  3. 模型若回傳 tool_calls，assistant 的 tool request 先寫回 message history。
  4. 程式解析每一個 tool argument；目前只有 web_search 會執行，未知 tool 回傳錯誤。
  5. Search request 送到 Moonshot Formula Fiber，程式驗證狀態並保留執行 receipt。
  6. Tool output 以 role=tool 和原本的 tool_call_id 回填 context。
  7. 模型取得 observation 後再次決定要繼續搜尋或產生 final answer。
  8. 到達 final answer、token 限制或 iteration cap 時停止。
  9. 若指定 output，CLI 保存 question、trace、answer、API turns、provider 與 model 等欄位。

主迴圈原始碼 值得逐行閱讀。它展示 Agent 並不是一次模型呼叫，而是「model action → environment observation → 更新 context → 下一次 action」的受限迴圈；max_iterations 也是系統設計的一部分，不是出錯後才補上的保險。

安裝與最小使用範例

Repository 支援 Python 3.10 到 3.13。若只想理解流程，不必先準備付費 API key，可以固定查核 commit，執行第 1 章的 offline demo：

git clone https://github.com/bojieli/ai-agent-book.git
cd ai-agent-book
git checkout --detach 984aeef3573ce8a3b74140feb0166541b8cf96c3

uv sync --locked --extra ch1
uv run python chapter1/web-search-agent/main.py \
  --provider offline-demo "請示範一次搜尋 Agent 的執行流程"

offline-demo 只會回放固定的教學 trajectory，不是即時搜尋。這個差異很重要：看到 tool call 的資料形狀，不等於已驗證外部搜尋服務。

若要執行 live Kimi Formula search，查核版本的命令是：

export MOONSHOT_API_KEY="your-key"
uv run python chapter1/web-search-agent/main.py \
  "請查找並摘要一則今天的 AI 官方公告" \
  --max-steps 3 --output web-search-run.json

本次研究沒有提供私人憑證，也沒有宣稱實測 hosted Formula。程式使用的 moonshot/web-search:latest 是伺服器端會變動的 URI；即使固定本地 commit 與 uv.lock，遠端行為仍不是完全可重現。Agent 初始化與 hosted tool

最值得閱讀的關鍵程式碼

Web Search Agent 主迴圈

chapter1/web-search-agent/agent.py 處理 malformed JSON、multiple tool calls、observation 回填、token truncation 與 iteration cap。若只選一個檔案閱讀，我會選它。

Provider resolution

agentbook/providers/resolution.py 將 provider alias、credential、model 與 OpenRouter fallback 分開。它也揭露一個容易忽略的限制：模型 API 可能相容，不代表不同 provider 都有相同 hosted tools。

Prompt injection 實驗

chapter2/prompt-injection/agent.py 把外部內容標記成 untrusted data，並要求高風險寫檔、寄信動作必須由本輪 user message 明確授權。這是很好的教學方向：不要只靠「請忽略惡意指令」一句 prompt，而要在 runtime 檢查 authority 與 target。

Experiment status

若準備採用某一章的做法，先讀 code，再讀 docs/EXPERIMENT_STATUS.md。它能告訴你該案例是完整 bounded claim、負面結果，還是尚缺 credential／hardware 的設計。

與相近資源有什麼不同？

資源 比較強的地方 ai-agent-book 的差異
Anthropic Building Effective Agents 用短篇幅說清楚 workflow、agent、環境回饋、簡單 pattern 與 stopping condition ai-agent-book 把概念延伸成十章與大量實驗，適合追進訊息和證據，但內容完成度較不均一。
Hugging Face Agents Course 有循序課程、framework 練習、作業、Spaces 與 certificate ai-agent-book 更重底層工程、evaluation、post-training、speech／GUI／robotics，卻沒有統一 hosted lab。
Microsoft AI Agents for Beginners 新手導向、多語、短片與 Microsoft Agent Framework／Foundry 範例 ai-agent-book 的中文原稿與研究實驗更深，provider 和環境也更分散。

若只想在半小時內建立 agent loop 概念，Anthropic 的官方文章 更有效率；希望按課程做作業，可選 Hugging Face Agents Course；想深入 message、context、evaluation 與 evidence，再回到 ai-agent-book。

專案成熟度：活躍教材，不是統一的 production runtime

2026 年 8 月 3 日 22:12（Asia/Taipei）查核時，GitHub API 顯示 repository 有 30,691 stars、3,286 forks，HEAD 是同日提交的 984aeef，維護活動非常密集。這些是有時間戳的瞬時值，之後會變動；本文沒有使用 Trending 週增數，也不把 stars 當成品質保證。

發布狀態需要拆開看：

  • latest 是 2026 年 7 月 21 日建立、會持續覆寫 assets 的 rolling prerelease。
  • 最新語意版本 tag 是 v1.2，但它不是 GitHub Release object。
  • 因為沒有非 prerelease 的正式 Release，/releases/latest API 在查核時回 404。
  • 根目錄 package version 是 0.1.0。

rolling workflow 與 tags 說明這是一套持續更新的書，而不是按 semantic version 提供穩定 runtime 相容性的 library。

成熟度也必須落到單一實驗。部分 campaign 有實質 evidence，部分仍因 Calendar、email、CUDA、長時間 benchmark 或機器人硬體而 incomplete。正確問法不是「這個 repository production-ready 嗎」，而是「我要採用的那個實驗，在固定版本下通過了哪些 gate？」

安全、隱私與供應鏈風險

Workable demo 不等於安全 sandbox

第 4 章 execution tools 的 virtual_terminal() 最終會把模型產生的 command 交給 subprocess.run(..., shell=True)。程式先以字串 blocklist 找危險命令，再請另一個 LLM 審批；這適合展示 tool routing，不能當成 production security boundary。virtual terminal

等效命令可以繞過字串比對，LLM approval 也不等於人類同意或 OS policy。正式環境仍要使用 container／VM、低權限 OS user、egress policy、allowlist、最小權限 token 與真正的人類 gate。

Trajectory 本身可能是敏感資料

Web Search Agent 會保存 query、tool arguments、tool output、model response 與 execution receipts。即使沒有記錄 Authorization header，使用者問題、搜尋內容、檔案內容、email target 或回答仍可能含個資與商業機密。JSON output 欄位 上線前需要 redaction、保存期限、權限與 provider data-policy review。

一個 lockfile 固定不了所有東西

根目錄有 uv.lock，外部 repository 也多固定 SHA，這比只提供 requirements.txt 更好；但部分實驗仍有只有 lower bound 的 dependency，hosted tool 使用 latest，GitHub Actions 也使用 major tags。模型、資料集、瀏覽器、GPU driver 與外部服務都可能漂移。

Repository 根目錄採 Apache-2.0，部分子專案與外部 checkout 有自己的 license。使用或散布前要逐一確認，不能把根目錄授權套到全部外部資產。

採用前怎麼評估？

我會用以下順序：

  1. 先把它定位成教材與實驗 reference，不放進 application dependency。
  2. 固定 commit 或 tag；rolling latest PDF／EPUB 不當 immutable artifact。
  3. 從第 1～2 章和 offline demo 開始，只安裝需要的 --extra chN。
  4. 同時讀 chapter README、protocol、validation 與 experiment status。
  5. 執行 live experiment 前，確認 provider 費用、model exact ID、資料政策與地區可用性。
  6. Shell、browser、GitHub、email、Calendar 與 file tools 一律放在隔離環境和最小權限後面。
  7. 保存 commit、lock、prompt、seed、hardware、receipts 與失敗條件，否則日後無法比較。
  8. 要進 production，重新建立自己的 threat model、tests、observability、human approval 與 rollback。

如果團隊只是想理解 Agent，最好的 PoC 不是一次跑遍 95 個實驗，而是挑一個 bounded case：先用 offline trajectory 看資料流，再用低風險、只讀的 live tool 驗證，最後檢查 evidence 是否足以支持原本的主張。

研究後的個人結論

ai-agent-book 最值得帶走的，不是某一個 provider 或 framework，而是兩個習慣。

第一，Agent 的能力來自模型、上下文與工具之間的迴圈；每一次 action、observation、停止與錯誤處理都應該能被觀察。第二，實驗資料夾存在不代表結論成立，必須區分 source、execution、evidence 與未完成 gate。

我會推薦它給已會 Python、想建立完整 Agent 工程地圖的中文讀者。它的更新速度、實驗廣度與證據台帳很有研究價值；但不同章節的品質、安全與依賴條件並不一致。最好的使用方式是讀原理、固定一個版本、跑一個有明確邊界的實驗、審查 evidence，再把設計帶回自己的 hardened stack，而不是把整個 repository 當成企業 Agent runtime。

下一篇會研究另一種把知識帶進 Agent 的方法：book-to-skill 是什麼？把技術書編譯成可按需讀取的 Agent Skill。

參考資料