Stage 4 — Agent 框架（Agent Frameworks）
⏱ 時間估算：2-3 週（約 10-15 小時）
💡 用語不熟（framework / supervisor / worker / handoff⋯）→ 翻
resources/glossary.md。
📋 本章組成：學習目標 → 進入條件 → 必修閱讀 →〔可選 · 概念地圖：multi-agent intro + 進階 tool patterns〕→ 動手練習 → 精選 Projects → 自我檢查 🔑 關鍵名詞：見
resources/glossary.md（framework / agent loop / handoff / supervisor 等收在 2、4）
你已經從零打造過一個 ReAct agent（Stage 3）。現在來看 framework 到底幫你做了什麼。挑一個深入學，其他的瀏覽過去就好，知道什麼時候該換。
📌 學習目標
完成這個 stage 後你會：
- 比較 5 個主流 agent framework（LangGraph、AutoGen、CrewAI、Smolagents、OpenAI Agents SDK）
- 替任務挑出對的 framework
- 用兩個 framework 各做一次同樣的 agent，親身感受差異
- 看出什麼時候該丟掉 framework、自己寫
🚪 進入條件
你應該已經：
- 跑完 Stage 3 的全部 5 個 hello-X projects
- 從零寫過 ReAct（練習 3）
- 對 async Python 上手（framework 大量依賴 async）
📚 必修閱讀
- Anthropic — Building Effective Agents — 什麼時候用 framework、什麼時候直接用 raw API
- LangChain — Conceptual Guide: Agents — agent 的抽象概念
- Best Multi-Agent Frameworks 2026 comparison — 當前市場定位
- 挑一個 framework 的 Quickstart — 選 LangGraph 或 CrewAI，把官方教學從頭跑到尾
🤔 什麼是 multi-agent framework？
兩個維度先分清楚（workflow vs agent / single vs multi）
要看懂 multi-agent framework 之前、有一個有用的釐清方式——把 workflow vs agent 跟 single vs multi LLM 當成兩個正交維度。Anthropic「Building Effective Agents」原文的核心區分是 workflow（固定 code path）vs agent（LLM 自主決定 next step）；我們把它跟 single/multi 疊起來看 4 個象限：
| Workflow （你寫好的 code path） | Agent （LLM 動態決定下一步） | |
|---|---|---|
| Single LLM | 線性 pipeline、無分支判斷 | 一個 LLM + ReAct loop、自己 plan + adapt （Stage 3 寫的就是這個） |
| Multi LLM | 預設 routing（譬如「銷售問題 → agent A、技術問題 → agent B」） | 2+ agent 互相 handoff、orchestrator 動態分配 （本 stage 主題） |
為什麼這個區分有用：production 場景大多落在「single agent workflow」+「single agent」象限——多數任務根本不需要 multi-agent。真正需要 multi-agent framework 的是右下角象限——LLM 自主性高 + 多角色協作。但實作上四個象限的邊界有時模糊（LangGraph 的 conditional edge 可以同時看成 workflow routing 跟 agent 動態決策）、不要把這個 matrix 當互斥分類。
→ 本 stage 後續討論都假設你已經知道：Multi-agent framework 主要幫你處理多個 agent 之間的協調、交接、狀態管理與重複性程式碼，讓你不用從零寫整套協作流程（右下角象限的 orchestration boilerplate）。
Single-agent vs multi-agent — 一張對照表先看清楚差異
| 維度 | Single-agent（你 Stage 3 寫過了） | Multi-agent system |
|---|---|---|
| 架構 | 一個 LLM + ReAct loop + 若干 tools | 2+ LLM、各有角色（researcher / writer / critic ...）、orchestrator 協調 |
| 怎麼決策 | 同一個 LLM 從頭想到尾 | 角色拆分 + handoff、不同 LLM instance 看不同視角 |
| State 管理 | 線性 message history | shared state / message passing / checkpoint |
| 適合場景 | 邏輯線性、tool < 20-30 個、單一目標 | 任務可分解、需要 perspective diversity、長 workflow、平行化 |
| Debug 成本 | 低（單一 loop 可以一路 trace） | 高（cross-agent 互動、error propagation 難定位） |
| Token 成本 | 1x | 通常 3-10x（每個 sub-agent 都有自己的 prompt + thinking + tool call） |
| Latency | 低 | 高（除非 sub-agent 平行跑） |
什麼時候真的需要 multi-agent（不要硬上）
Multi-agent 不是 default、是 last resort。Anthropic 跟 Cognition 兩家 frontier lab 在 2024-2025 都明白寫過：90% 用例其實不該用 multi-agent——硬上會付 3-10× token、debug 痛苦、context fragmentation（context 被切散在多個 agent、彼此看不到全貌）嚴重。
| 立場 | 來源 | 核心論點 |
|---|---|---|
| Anthropic | Building Effective Agents (2024)、How we built our multi-agent research system (2025) | 多數場景 simple workflow + single agent 就夠；multi-agent 只在「研究型 / 並行探索」任務真的有幫助 |
| Cognition | Don't Build Multi-Agents (2025) | multi-agent 的 context fragmentation 嚴重、shared state 維護痛苦；先窮盡 single-agent + long-context 才考慮 |
需要 multi-agent 通常是這 4 個信號之一：
| 信號 | 描述 | 對應 pattern |
|---|---|---|
| 1. 任務天然分解 | 大任務有清楚的子步驟、step-by-step 完成 | Sequential / Planner-Executor |
| 2. Token explosion | single agent prompt 塞不下所有 tool description / context | Supervisor-Worker（分流給 sub-agent） |
| 3. 角色衝突 | 同一個 LLM 既當 writer 又當 critic 會 self-justify | Debate / Peer review |
| 4. 平行加速 | 3 個 research 子任務同時跑、wall-clock 1/3 | Parallel / Map-Reduce 變種 |
4 個信號都不在？ → single agent + 好 prompt + tool use 就夠。硬上 multi-agent 會付 3-10x token、debug 痛苦、其實不會比較準。
💡 後續閱讀：到 Stage 7 但你真的需要 multi-agent 嗎？ 會再帶 production 視角的決策——本節是設計階段的決策、那邊是 deploy 前的最後一次回頭檢查。
Multi-agent 經典 pattern（按複雜度排序）
📝 跟 Stage 3 經典範式怎麼分：Stage 3 的 4 個 paradigm（CoT / ReAct / Reflection / Planning）是單一 agent 內部怎麼想；本節這 5 個 pattern 是多個 agent 之間怎麼協作——正交的兩個層。
| Pattern | 複雜度 | 什麼樣 | 經典場景 | 代表 framework / paper |
|---|---|---|---|---|
| 1. Routing / Handoff | ⭐ | agent 之間 1:1 handoff、無中央 orchestrator | customer support routing、context switch | OpenAI Swarm、OpenAI Agents SDK |
| 2. Sequential （Planner → Executor） | ⭐⭐ | planner 規劃多步驟 + executor 執行 | 多步驟自動化、code generation | LangGraph、ChatDev paper |
| 3. Parallel （平行加速） | ⭐⭐⭐ | N 個 agent 同時跑、結果 aggregate | research / map-reduce 任務、wall-clock 1/N | LangGraph parallel branches、CrewAI parallel tasks。坑點：async coordination + partial failure + state merge 一致性 |
| 4. Supervisor-Worker （hub-spoke） | ⭐⭐⭐ | 1 主 + N worker、主分配 + 整合 | 任務拆解、報告整合 | LangGraph、AutoGen GroupChat |
| 5. Debate / Society （多視角收斂） | ⭐⭐⭐⭐ | 2+ agent 互相 critique 或角色扮演 | research、judgment task、social simulation | AutoGen GroupChat、CAMEL paper、Generative Agents paper |
Claude Code subagent — 另一條 orchestration 路線
這節跟上面的 5 個 pattern 不同層：上面 5 個 pattern 是 framework / 自己 code 都能實作的設計選擇；本節介紹的 Claude Code subagent 是另一個 execution model（runtime 內建的 orchestration、不寫 framework code）。讀完 5 個 pattern 後、本節讓你知道「multi-agent 還有第二條路」。
Multi-agent 不只有 framework 這條路。Anthropic 自家的 Claude Code 提供另一個 abstraction 層：subagent — 寫一個 .claude/agents/<name>.md 檔就是一個 subagent，不需要 framework。
跟 framework 路線的根本差異（一句話）：framework 路線跨 LLM provider、寫 Python orchestration code、checkpointing / audit trail 完整；Claude Code subagent 只在 Claude Code runtime 內、寫 markdown 不寫 code、天生 context 隔離。
📌 完整逐維度對照表（啟動方式 / runtime / context 隔離 / provider lock-in / 學習曲線）的 canonical 在 Stage 5.5 開頭——本 stage 只需知道「multi-agent 還有 Claude Code 原生這第二條路」、逐項實作差異到 5.5 再看。
何時選 subagent 而非 framework：
- 你已經在用 Claude Code 跑日常工作
- 任務 context 大、會吃光主 session window（讀整個 codebase 之類）
- 多 subagent 平行（research / write / critic）省 wall-clock 時間
- 不需要跨 provider migration
詳細寫法 + 動手練習見 Stage 5.5（建議先完成 Stage 5.1 Claude Code 基礎再回來看 5.5——subagent 是 Claude Code 生態的進階功能、需要先熟悉基礎用法）。
Framework 的工作
Framework 把上面這 5 個 pattern 的 orchestration boilerplate（roles、handoff、state、retry、checkpoint、HITL pause）抽出來、讓你只寫角色定義跟任務描述。一句話：framework 是 multi-agent 的腳手架，不是必需品——簡單情境你自己寫個 dict 跟 for loop 也行（Stage 7 練習 1 就是這樣）。
📚 想系統化深入？
🇺🇸 學術 paper（影響後續所有 framework 設計）：
- Anthropic — "Building Effective Agents" ⭐⭐⭐ — 何時用 workflow 何時用 agent、5 個經典 orchestration pattern。英文圈 multi-agent 設計入門必讀
- AutoGen paper (Wu et al. 2023) — Microsoft 多 agent 對話框架原 paper
- CAMEL paper (Li et al. 2023) — multi-agent role-play 開山之作
- ChatDev paper (Qian et al. 2023) — multi-agent software dev、planner-executor canonical
- Generative Agents paper (Park et al. 2023) — 25 個 agent 在 The Sims 互動、社會 simulation
🀄 中文系統教材：
- hello-agents Ch6「框架開發實踐」+ Ch7「構建你的 Agent 框架」 ⭐ — 中文圈完整講 framework 開發 + 從零構建。注意：Ch4「智能體經典範式構建」是 single-agent paradigm（ReAct / Plan-and-Solve / Reflection），不是 multi-agent
- 李宏毅 — 生成式 AI 導論 — 中後段有 AI agent / multi-agent 相關集數
Framework 官方 multi-agent docs：
- LangGraph — Multi-Agent Systems — supervisor / swarm / hierarchical 三種架構官方教學
- Anthropic Cookbook —
customer_service_agent.ipynb— multi-agent orchestration canonical 範例（routing + handoff） - Microsoft AutoGen — Examples — group-chat / debate / peer review pattern 完整範例
💡 建議框架學習流程（5 步）：
- 建立 mental model（30 min）— 讀 Anthropic Building Effective Agents、把 workflow vs agent 跟 single vs multi 兩維度搞清楚
- 跑 1 個 framework quickstart（2-3 hr）— LangGraph 或 CrewAI 二選一、跑官方多 agent 教學
- 對照 Anthropic Cookbook
customer_service_agent（1 hr）— production-style routing + handoff 範例- (可選) 深入學術側：挑 paper 1-2 篇看（AutoGen / CAMEL / ChatDev / Generative Agents）
- (Claude 使用者可選) 寫一個 subagent 對照：見 Stage 5.5、跟 framework 路線比較
不必把 5 個 paper 全讀完、挑跟你場景最近的 1-2 個。
🛠 進階 tool patterns（framework 替你處理掉的東西）⭐ Track B 必看
Stage 3 教你寫 single tool / multi-tool selection（手寫 if/elif/else 路由）。Framework 把這層抽掉，並加了三種更進階的 tool pattern——這三個 pattern 都需要 framework 抽象層才寫得乾淨，Stage 3 自己手寫會炸開：
| Pattern | 解決什麼問題 | 代表實作 |
|---|---|---|
| Dynamic tool selection | 工具 > 30 個時、tools=[...] 塞不下 prompt（context 太大、selection 也變差） | LlamaIndex tool router — embedding-based 路由：先 semantic search 找 top-K tool、只把這 K 個塞進 prompt |
| Tool composition / chaining | tool A output → tool B input、不要 LLM 中間 narrative（省 token + 省 latency） | LangGraph state graph 直接連接 node、CrewAI sequential tasks、Pydantic AI 的 type-safe pipeline |
| Tool-augmented retrieval | tool 本身是 RAG search → 回結果再 reason | Stage 6 練習 4 RAG pipeline + Stage 3 練習 2 multi-tool 結合（LangGraph 直接把 retriever 包成 tool node） |
📚 深度資源：
- Anthropic — Tool Use best practices — 官方 tool design guide
- LlamaIndex — Tool Router pattern — Dynamic selection canonical reference
- LangGraph — Tool Node — composition graph 寫法
💡 Track B 學完本節：你應該講得出「同一個任務」在 (a) Stage 3 手寫 (b) 本 stage framework 寫 (c) Stage 5.5 Claude subagent 寫 三種路線的差別。這是 Track B 路線「會設計 agent」核心問題。
🛠 動手練習
練習 1：同一個 agent、兩個 framework
用以下兩個 framework 各做一次同樣的簡單 agent（搜尋 + 摘要）：
- LangGraph
- CrewAI 比較程式碼行數、debug 體驗、以及它們各自把哪些複雜度藏在哪裡。
練習 2：多 agent 角色分配
用 CrewAI 做一個 2-3 個 agent、各自有不同角色一起完成同一個任務的 demo。（這種情境 CrewAI 最拿手。）
練習 3：圖式 workflow
用 LangGraph 做一個有分支邏輯跟 human-in-the-loop checkpoint 的 workflow。（這種情境 LangGraph 最拿手。）
練習 4：CodeAct vs JSON tool
用 Smolagents 做一個會寫 Python 程式碼當作 action 的 agent（CodeAct pattern），跟 練習 1 用的 JSON tool call 路線比較。問同一個問題，看兩種路線怎麼解。
練習 5：型別安全 agent
用 Pydantic AI 做一個會回傳結構化輸出的 agent（例如：問問題回 { "answer": str, "confidence": float, "sources": [str] }）。看 Pydantic 的 schema validation 怎麼防止 agent 偷懶或 hallucinate 結構。
🎯 精選 Projects
按用途分 5 類、15 個項目一張表搞定。挑入口看「適合誰」、想深入點連結看 repo / quickstart。
| 分類 | Project | ⭐ | 適合誰 | 為什麼推薦 / 備註 |
|---|---|---|---|---|
| Production 級 （複雜 multi-agent / 需要 audit） | LangGraph ⭐ 本 stage 推薦 #1 | ⭐⭐⭐⭐⭐ | Production multi-agent + 稽核軌跡 / rollback / replay | 圖式 orchestration + checkpointing + time-travel debug、企業採用率最高，★ 31k+、MIT、Python+TS。搭 LangSmith 做 observability |
| microsoft/semantic-kernel | ⭐⭐⭐⭐ | 在 .NET / Java 環境做 agent、Microsoft 技術棧 | C# / Python / Java 三語官方 SDK、kernel + plugin + planner pattern，★ 27k+、MIT。抽象厚、不適合初學者 | |
| agno-agi/agno | ⭐⭐⭐⭐ | 要「build + serve + monitor」一條龍但不想全套 LangGraph + LangSmith | multi-modal agent runtime + control plane，★ 39k+、Apache-2.0。Stage 4 學 API、Stage 7 用 runtime | |
| 快速雛形 / 多 agent （role-based / handoff） | CrewAI ⭐ 本 stage 推薦 #2 | ⭐⭐⭐⭐ | 快速雛形「researcher → writer → critic」pipeline | ~20 行寫完 crew、學習曲線最低，★ 50k+、MIT。⚠️ 長 workflow 沒 checkpointing；雛形用 CrewAI、production 用 LangGraph |
| Microsoft AutoGen / AG2 | ⭐⭐⭐⭐ | 多 agent 辯論 / 腦力激盪 / peer review pattern | 對話式多 agent、group-chat 強，★ 57k+、CC-BY-4.0（文件 license）。⚠️ AG2 v0.4 重寫成 async-first、多數教學還在 v0.2、留意版本分支 | |
| OpenAI Agents SDK | ⭐⭐⭐⭐⭐ | 已 commit OpenAI 生態 | OpenAI 官方、agent hand-off + 結構化輸出、API 乾淨、MIT。2026-04 重大升級：內建 sandbox（7 個 provider）+ harness 抽象層、production coding agent 首次 architecturally sound（詳見 Stage 8） | |
| OpenAI Swarm | ⭐⭐⭐⭐ 教育用 ⭐⭐⭐ production | 想理解 multi-agent 核心 mental model 但不想學整套 framework | ~200 LOC、只有 Agent + handoff 兩個觀念、MIT。⚠️ OpenAI 自己標 experimental / educational、不是 production tool。讀 source 當 chapter-length 教材 | |
| Strands Agents (AWS) | ⭐⭐⭐⭐ | 已 commit AWS 雲、Bedrock-native | model-driven 設計（LLM 自己 plan、無 explicit graph）、Apache 2.0。2025 後段推出、AWS Lambda / Step Functions / Bedrock Agents 整合 | |
| 特殊路線 （CodeAct / typed / memory-first） | Hugging Face Smolagents | ⭐⭐⭐⭐ | 本地 LLM 生態、HF 整合場景 | CodeAct pattern 代表（agent 寫 Python 程式碼當 action、非 JSON tool call），★ 27k+、Apache 2.0、≤1000 LOC |
| Pydantic AI | ⭐⭐⭐ | production 預設要 runtime 型別安全 + structured output | type-safe agent、Pydantic 團隊出品、MIT。較新 | |
| Letta (formerly MemGPT) | ⭐⭐⭐⭐ | 長 session / 跨 day / persona-stable agent（long-term assistant、therapist、tutor） | memory-first multi-agent、OS-paging 概念（working memory + archival store），★ 22k+、Apache 2.0。Stage 6 練習 5 也會提 | |
| 特化 | LlamaIndex Agents | ⭐⭐⭐ | 文件密集型 agent（研究助理、知識工作者類） | 跟 RAG 緊整合，★ 49k+、MIT。retrieval 強、orchestration 弱——純 orchestration 別選 |
| agentscope-ai/agentscope | ⭐⭐⭐ | 想要視覺化 debug 多 agent 流程的研究者 | 多 agent 平台、視覺化 debug 工具強，★ 24k+、Apache 2.0。西方社群採用低、技術紮實 | |
| LangChain | ⭐⭐⭐ | 需要黏合很多零件（retrieval + chain）的快速雛形 | 萬用工具袋 framework，★ 135k+、MIT。agent orchestration 改用 LangGraph、LangChain 適合 retrieval + chaining 黏合 | |
| 基礎設施 （不是 framework、跨 stage 用） | BerriAI/litellm | ⭐⭐⭐⭐ | 要切換 Claude / GPT / Gemini / 開源模型但不想改 code | provider-agnostic SDK + AI gateway、用 OpenAI 形狀 call 100+ LLM、附 cost tracking / fallback / guardrail，★ 45k+、MIT（enterprise/ 子目錄另授權） |
💡 建議閱讀路徑：挑 1 個 production 等級（LangGraph）+ 1 個快速雛形（CrewAI）深入學 → 跑練習 1-3 → 其他 framework README 瀏覽過去、知道存在即可。特殊路線那 3 個（CodeAct / typed / memory-first）在特定場景才有對手、平常不必碰。
✅ 進 Stage 5 前的自我檢查
你能不能：
- 用 LangGraph 跟 CrewAI 各做一次同一個 agent
- 替任務挑出對的 framework（production vs 雛形）
- 解釋 LangGraph 的 checkpoint 跟 CrewAI 的 task delegation 差在哪
- 看出什麼時候 CodeAct（Smolagents）比 JSON-tool 更好
- 判斷什麼時候該丟掉 framework、直接用 raw API
如果可以 → 進 Stage 5 — Claude Code Ecosystem。
💡 策略提示 + 過程中可能踩到的坑
不要想把這些全部學完。挑**一個 production 等級的（LangGraph）跟一個快速雛形用的（CrewAI）**深入學。其他的 README 瀏覽過去就好，知道有這些選項存在即可。
Memory 預備（學的時候可能碰到、不用先讀）：有些 framework 功能會用到 memory 概念 — LangGraph 的 checkpointing（狀態持久化）、CrewAI agent 之間傳遞任務結果（輕量 memory）。這些在 Stage 6 — Memory & RAG 完整講；本 stage 看不懂某個 framework 功能時、再去那邊查就好，不用先讀完才能繼續本 stage。