Stage 4 — Workflow Graph 與 Agent 框架

繁體中文 | 简体中文 | English

你在 Stage 3 已經自己寫過 Agent Loop。這一關先把多步工作畫成 Workflow Graph，再選 Framework（框架） 來幫你接線。先看懂工作地圖，再選工具箱，才不會因為某個框架很流行就硬把事情變複雜。

📌 學習目標

完成這一關後，你可以：

• 用自己的話分清 Agent Loop、Workflow Graph、Agent framework 與多角色系統。
• 先選最簡單能完成任務的工具，不為了流行硬加角色。
• 跑完五個練習，親手比較 LangGraph、CrewAI、Smolagents 與 Pydantic AI。
• 說出交接、存檔與人工批准各自解決什麼問題。

🧩 先認識八個核心詞

• Workflow（工作流程）／Workflow Graph（工作流程圖）：像照食譜做菜，再把每一步和下一站畫出來。程式先寫好 node、edge 與分支，模型只完成其中需要判斷的工作。
• Framework（框架）：一盒已經整理好的積木。它幫你接好迴圈、工具、記錄與錯誤處理；但盒子越大，藏起來的細節也越多。
• Agent（代理程式）：像拿到目標的助手。模型可以依目前結果決定下一步，但真正的權限、驗證與停止條件仍由程式控制。
• Orchestration（編排）：像交通指揮。它安排誰先做、誰後做、資料交給誰，以及失敗時怎麼回來。
• State（狀態）：像工作中的筆記本。它記住目前輸入、工具結果、進度與下一步需要的資料。
• Checkpoint（檢查點）：像遊戲存檔。流程中斷後，可以從已保存的位置繼續，不必全部重來。
• Handoff（交接）：像把工作單交給另一位同學。新的 Agent 接手後，需要拿到足夠背景，也不能得到不需要的權限。
• Human-in-the-loop（HITL，人在迴圈中）：像先舉手請老師看。程式在花錢、寄信、刪資料或發布前暫停，等人批准才繼續。

🧭 先分清：Loop、Graph 與 Framework

Framework 是工具箱；Workflow Graph 是你畫出的工作地圖；Production orchestration 是讓地圖能安全運轉的工程工作。 Graph Engineering 是新興但尚未統一的稱呼，不是 Framework 的另一個名字。Multi-Agent 可以放進圖裡，但不是每張圖都需要多個 Agent，也不是每個 node 都必須是 Agent。

🗺️ 先看一張選擇地圖

先問兩題：誰決定下一步？需要幾個 Agent？ 如果固定路線已經能完成，就停在左上角；多一個 Agent 會多一份 context、測試與失敗方式。

🚪 進入條件

先完成 Stage 3 的六題，至少能說出 schema → call → execute → result → answer。會讀 async／await 很有幫助，但不是開始第一題的門檻。

📚 必修閱讀

先讀「怎麼選簡單形狀」，再從第 4 步的兩個 framework Quickstart 挑一個。下面共有 4 個閱讀步驟、5 個官方連結；先照順序讀，不必一次讀完每一頁。

1. Anthropic — Building Effective Agents：先分清 workflow 與 agent，也看懂為什麼要從簡單方案開始。
2. LangGraph — Workflows and Agents：看固定路線與動態路線怎麼寫成圖。
3. OpenAI Agents SDK — Multi-agent orchestration：比較 manager-as-tools 與 handoff。
4. Quickstart 二選一：LangGraph 或 CrewAI；只要先深入一個。

第三方排行榜可以提供候選名單，但不能證明版本、授權、可用性或哪個「最強」。這些事以官方文件與你自己的 eval 為準。

🤔 什麼是 Agent framework？

Agent framework 是幫一個或多個 Agent 接好模型、工具、state、重試、存檔與人工批准的工具箱。一個 Agent 也能使用 framework；multi-agent 只是後面的一種系統形狀，不是 framework 的定義。 Framework 不是魔法，也不是每個專案的預設答案。

兩個維度先分清楚（workflow vs agent / single vs multi）

這四格會重疊。例如 LangGraph 的 conditional edge 可以同時有固定規則與模型決策。表格是幫你問問題，不是把所有系統硬塞進盒子。

什麼時候真的需要 multi-agent（不要硬上）

先用一個 Agent。只有出現下面的證據，再考慮增加角色：

• 任務真的能拆成彼此較獨立的工作，而且每份工作有清楚輸出。
• 不同角色需要不同工具、權限或 context，分開能降低混亂。
• 多個方向可以同時探索，最後也有明確的合併與驗證方法。
• 你的 eval 顯示多 Agent 比單 Agent 更可靠，增加的 token、延遲與除錯成本值得。

沒有這些證據時，一個 Agent 加好工具、好 context 與有限迴圈通常更容易測試。多 Agent 不保證比較準，也不保證比較快。

五種協作 pattern

Supervisor（主管 Agent） 像班長，負責拆工作與合併答案。Worker（工作 Agent） 像組員，只拿完成自己任務所需的資料與工具。

依需求選工具

Ollama 練習先從 LangGraph 或 CrewAI 路線開始。不要因為工具清單超過某個固定數字就換框架；先用 eval 看 context、選錯率與延遲是否真的惡化。

🛠 動手練習

每題先安裝該資料夾的 requirements，再跑不連網測試。看到成功後，再依同資料夾 README 選 Ollama Path A 或 Anthropic Path B。

練習 1：同一個 agent、兩個 framework

成果：同一個搜尋加摘要任務各走 LangGraph 與 CrewAI，說出兩者藏起來的工作有什麼不同。

Set-Location examples/stage-4/01-same-agent-two-frameworks
py -3.11 -m pip install -r requirements.txt
py -3.11 test.py

預算：Path A 單次 API 費 $0；Path B 依 $1／$5 每百萬輸入／輸出 tokens 計算。若五題各跑一次，本章總額就是五次實際 token 成本相加。

練習 2：多 agent 角色分配

成果：讓 researcher、writer 與 reviewer 各做一件清楚的事，並看見每次交接的輸出。

Set-Location examples/stage-4/02-multi-agent-roles
py -3.11 -m pip install -r requirements.txt
py -3.11 test.py

預算：Path A 單次 API 費 $0；Path B 使用同一公式。角色越多，通常會多出 prompt 與呼叫，但沒有固定倍數，請記錄實際 tokens。

練習 3：圖式 workflow

成果：在 LangGraph 建立分支、checkpoint 與 HITL 暫停點，再從保存位置繼續。

Set-Location examples/stage-4/03-graph-workflow
py -3.11 -m pip install -r requirements.txt
py -3.11 test.py

預算：Path A 單次 API 費 $0；Path B 依實際 tokens 計算。Checkpoint 保存的是進度，不會自動降低模型費用。

練習 4：CodeAct vs JSON tool

CodeAct 是讓模型寫程式碼當 action。它像請助手自己寫一把臨時工具，彈性高，但模型產生的程式一律視為不可信，必須放在 sandbox 或受限環境，不能直接在主機任意執行。

成果：用同一題比較受限 CodeAct 與 JSON tool call，說出哪一條更容易驗證。

Set-Location examples/stage-4/04-codeact-vs-json-tool
py -3.11 -m pip install -r requirements.txt
py -3.11 test.py

預算：Path A 單次 API 費 $0；Path B 依實際 tokens 計算。Sandbox、容器或受管執行環境可能另收費。

練習 5：型別安全 agent

Type-safe（型別安全） 像先畫好表格格子，再檢查每格放對資料。Pydantic 可以驗證 Structured Output 的形狀與範圍；它不能保證答案內容一定是真的。

成果：讓 Pydantic AI 回傳 answer、confidence 與 sources，並親眼看到不合規資料被拒絕。

Set-Location examples/stage-4/05-typed-agent
py -3.11 -m pip install -r requirements.txt
py -3.11 test.py

預算：Path A 單次 API 費 $0；Path B 依實際 tokens 計算。Schema 驗證失敗後的重試也會產生 token 成本。

🎒 推薦小專案：有人先檢查的研究摘要流程

把五題合成一個小作品：一位 researcher 找資料，一位 writer 寫摘要；程式保存 state，最後停在 HITL，等你檢查來源後才輸出。先用兩個角色就好，不要一開始做十人團隊。

成功標準：你能重新啟動程式並從 checkpoint 繼續；沒有人的批准，流程不會進入最後發布步驟。

🎯 精選 Projects

第一個入口先看 LangGraph ⭐⭐⭐⭐⭐：你能直接看到 state、edge、checkpoint 與中斷點。其餘 18 筆已依用途分組放在下面；推薦度是本章學習順序，不是人氣排行榜。

既有框架資訊查核：2026-08-27 UTC；Bifrost：2026-09-03 UTC

✅ 進 Stage 5 前的自我檢查

• 我能分清 Agent Loop、Agent framework、Workflow Graph 與 multi-agent，不把它們當同一件事。
• 我會先用最簡單方案，只有看到可量測證據才增加 Agent。
• 我能說明 State、Checkpoint、Handoff 與 HITL 各自保存或控制什麼。
• 我跑過五題的離線測試，並完成至少一條 Ollama Path A。
• 我知道 CodeAct 要隔離執行，type-safe output 也仍需檢查內容。

都做到後，進入 Stage 5 — Claude Code Ecosystem。如果還分不清四格，回到上面的選擇地圖；不必重讀 19 筆表格。