1. 結論先行：Agent Graph 是控制面，不是多 Agent 裝飾
來源事實：Microsoft 將架構複雜度分成直接模型呼叫、帶工具的單一 Agent，以及多 Agent 協作，並建議使用能可靠滿足需求的最低複雜度；多 Agent 會增加協調成本、延遲與失敗模式。AI 判讀：Agent Graph 的價值不在節點越多越先進，而在把原本藏在提示詞與對話歷史裡的控制邏輯，移到可檢視、可測試、可持久化的工程結構。它回答五個問題：目前狀態是什麼、下一個節點由誰決定、哪些工作可以並行、失敗後從哪裡恢復，以及何時必須停止或交給人。
2. 先分清四個概念：Loop、Workflow、Agent Graph 與多 Agent
Loop 是單一 Agent 在「思考、呼叫工具、觀察結果」之間反覆執行；Workflow 是由程式預先決定步驟與順序；Agent Graph 是以節點、邊與共享狀態表示工作，既能包含固定流程，也能在少數節點使用模型做動態決策；多 Agent 則表示系統內有多個具不同指令、工具、模型或權限的角色。四者不是互斥關係：一個 Graph 可以只有一個 Agent，也可以讓某個節點內部跑 Loop；反過來，多個 Agent 若只在共享聊天室互相說話，卻沒有狀態契約、停止條件與復原機制，仍不等於可控的 Graph。
3. 何時值得升級成 Graph：用決策梯，而不是跟著框架選架構
AI 建議：先依序檢查四層。第一層，單次分類、摘要或轉換能否由一次模型呼叫完成；第二層，單一 Agent 加少量工具與迭代上限是否足夠；第三層，固定的序列、條件分支或佇列工作流能否解決；第四層，只有在需要根據中間結果動態路由、平行處理彼此獨立的子任務、隔離不同工具權限、保存長時間任務狀態、插入人工核准，或讓專業角色互相校驗時，才採 Agent Graph。若團隊無法先寫出完成條件與失敗處理，多一層 Graph 只會把不確定性放大。
4. Graph 的最小組成：State、Node、Edge、Router、Reducer、Terminal
來源事實：LangGraph 的 Graph API 以狀態結構定義資料綱要，節點讀取狀態並回傳更新，邊定義控制流，START 與 END 表示入口與終點。工程上可把最小模型拆成六件事：State 是唯一可追溯的任務事實；Node 是具單一責任的處理單元；Edge 表示確定的轉移；Router 根據狀態輸出有限集合的下一站；Reducer 定義平行更新如何合併；Terminal 表示成功、失敗、取消、等待輸入或需要人工處理等終止狀態。任何一項若只能靠自然語言猜測，測試與復原都會變得困難。
5. 五種常用拓撲：序列、路由、Fan-out／Fan-in、Maker–Checker、動態規劃
來源事實：Microsoft 的架構指南整理了 sequential、concurrent、group chat／maker-checker、handoff 與 magentic 等模式。序列適合前一步輸出是後一步必要輸入的管線；路由或 handoff 適合專業需求在執行途中才明朗的工作；Fan-out／Fan-in 適合彼此獨立的研究、分類或風險分析，再由聚合器合併；Maker–Checker 適合有明確驗收標準的產生與審核迴圈；動態規劃則由管理節點建立任務清單、追蹤進度並重規劃。選型依賴資料相依性、可接受延遲、衝突處理與完成條件，不是依 Agent 名稱或模型品牌。
6. 決定性控制優先：已知規則用程式，模糊判斷才用模型
AI 建議：檔案格式、權限、金額門檻、重試次數、必填欄位、狀態轉移與安全政策，應由一般程式碼或規則引擎判定；只有語意分類、計畫生成、證據綜合或無法列舉的路由，才交給模型。即使使用模型路由，也不要讓它回傳任意節點名稱，而應要求符合 Schema 的列舉值，例如 `route = research | test | security | human`，再由程式驗證。這能把不可預測性限制在明確邊界，也讓路徑覆蓋、錯誤回應與 fallback 可以自動測試。
7. State 設計：把對話歷史降級，把任務事實升級
State 不應只是無限增長的 messages 陣列。建議分成 identity、input、plan、work_items、evidence、artifacts、decisions、budget、status、errors 與 audit 等欄位，並為每個欄位定義型別、版本、擁有者與合併規則。事實資料要保留來源或 artifact ID，AI 推論要標註產生節點與模型版本，建議要附適用條件。對話可作為除錯資料，但真正驅動路由的應是結構化狀態。長流程還要設定內容保留與摘要策略，避免 checkpoint、上下文與儲存成本無限制成長。
8. Node 契約：每個節點都要能單獨理解、重跑與驗證
一個可維護 Node 至少應聲明 input schema、output patch、允許讀寫的狀態欄位、可用工具、逾時、重試策略、副作用、錯誤分類與成功條件。節點只回傳自己負責的狀態差異，不要把整份 State 任意覆寫。模型節點的輸出先做 Schema 驗證，再寫入共享狀態；工具節點需把 HTTP 狀態、外部資源 ID 與錯誤碼轉成領域結果。把「規劃」「執行」「驗證」拆開，避免同一個 Agent 自己宣稱自己的操作成功。
9. Router 與停止規則：把無限循環變成有限狀態機
每個循環必須有硬性邊界，包括最大節點數、最大迭代、總工具呼叫、牆鐘時間、Token 或金額預算，以及同一路徑重複次數。Router 除了下一節點，還應輸出 reason_code 與 evidence_ref，供測試和稽核；當狀態連續多輪沒有新增證據、錯誤指紋重複或預算接近上限時，應轉入 blocked 或 needs_human，而不是繼續「再想一次」。Microsoft 也建議對單一 Agent 與 maker-checker 迴圈設定迭代上限，以避免無限工具呼叫或反覆修訂。
10. 平行執行與合併：速度收益必須大於狀態衝突
Fan-out 只適合輸入可複製、子任務相對獨立且合併規則清楚的情境。每個 Worker 應寫入自己的命名空間或產生不可變 artifact，再由 Aggregator 依規則合併；不要讓多個 Agent 同時修改同一筆外部資料或同一個自由文字欄位。合併策略可以是集合聯集、依 ID 去重、加權分數、明確優先序或獨立驗證器，但必須先處理部分成功、逾時、結果矛盾與重複提交。若子任務高度相依或需要持續共享完整上下文，序列流程通常更穩定。
11. 持久化與復原：Checkpoint 只是起點，還要處理副作用
來源事實：LangGraph 的 checkpointer 可保存單一 thread 的 Graph 狀態，用於對話延續、人工介入、time travel 與 fault tolerance；正式環境不應只用記憶體儲存，也要為 checkpoint 設定保留政策。工程上每次執行要有穩定的 task_id／thread_id，節點完成後保存狀態與 artifact 參照，並區分可重試錯誤、不可重試錯誤與需要補償的外部變更。重新啟動時應從最後一個已提交 checkpoint 繼續，而不是重跑全部流程。
12. 冪等與補償：中斷後重跑時不能重複寄信、扣款或寫資料
來源事實：LangGraph 的 interrupt 會在恢復時重新執行所在節點，因此 interrupt 前的副作用應具冪等性，或移到獨立節點。實作上可使用 idempotency key、唯一約束、compare-and-set、outbox／inbox、已處理事件表與外部資源 ID，讓相同操作重送不會產生第二份結果。對無法天然冪等的動作，必須定義補償流程，例如撤銷預約、回復狀態或建立人工處理單；「有 checkpoint」不代表外部世界也能自動回滾。
13. Human-in-the-loop：把人放在不可逆決策前，不是失敗後才找人
人工閘門適合放在付款、正式發布、刪除資料、傳送外部訊息、調整權限、修改生產環境與高風險醫療或法務決策之前。核准畫面應提供原始要求、預計動作、受影響資源、證據、Diff、風險等級與可選動作，不能只顯示一句「是否同意」。OpenAI Agents SDK 與 LangGraph 都提供中斷或人工介入機制；重要的是核准結果要寫回 State，並讓拒絕、修正、逾時與取消成為正式路徑。
14. 安全邊界：每個 Agent 都應視為可能被誤導的低信任元件
來源事實：OWASP 的 Agentic Top 10 包含目標劫持、工具濫用、身分與權限濫用、供應鏈風險及非預期程式執行等問題；NIST 的生成式 AI 風險框架則強調把治理、測試、內容來源與事件揭露納入生命週期。AI 建議：依節點配置最小權限、短效憑證、網路與資料 allowlist，區分唯讀與寫入工具，對使用者輸入、工具參數、工具結果與最終輸出分層 guardrail，並把外部網頁、檔案與其他 Agent 的文字視為不可信資料。不同安全域應使用獨立 Agent 或服務帳號，而不是共用一組全能工具。
15. 可觀測性：不要只記錄最後答案，要保留整條執行軌跡
來源事實：OpenAI Agents SDK 的 tracing 會記錄模型生成、工具呼叫、handoff、guardrail 與自訂事件；OpenTelemetry 也已定義 GenAI agent、workflow、tool、token 與 evaluation 等語意欄位，但部分仍處於開發狀態。每次 Graph Run 至少應可查到 trace_id、task_id、節點起訖、路由決定、模型與提示版本、工具參數摘要、狀態差異、artifact、重試、錯誤、Token、成本、等待人工時間與最終 outcome。記錄前需遮蔽病患資料、個資、憑證與敏感工具內容，不能為了除錯而無限制保存完整 Prompt。
16. 測試金字塔：Node 測試、路徑測試、故障注入與 Agent Evals
最底層先測純函式節點、Reducer、Schema 與確定性 Router；中層測節點契約、工具 stub、各條件分支、平行合併及 checkpoint 恢復；上層用隔離環境跑端到端任務，注入逾時、429、工具回傳惡意文字、部分 Worker 失敗、重複事件與人工拒絕。來源事實：Anthropic 的 Agent eval 指南區分 task、trial、grader、trace、outcome 與 harness，並建議以最終環境狀態判定成功，而非相信 Agent 宣稱完成。由於模型輸出具變異性，關鍵案例應跑多次 trial，持續追蹤成功率、成本與錯誤類型。
17. 工程範例：用 Graph 產生軟體變更風險與測試計畫
可建立一個不接觸真實病患資料的 QA Graph：START → validate_input → classify_change → fan-out 到 requirement、code-impact、security 與 test-design 四個唯讀 Worker → aggregate_evidence → checker → human_approval → publish_report → END。State 可包含 change_id、scope、source_refs、risk_items、test_cases、open_questions、confidence、budget、status 與 audit。四個 Worker 只能產生結構化 artifact，Aggregator 依 requirement_id 與 risk_id 去重，Checker 驗證每個高風險項目是否有測試與來源；資訊不足就進 needs_input，高風險或涉及正式環境就進 human_approval。
18. 最小實作順序：先跑一條直線，再逐步增加分支
第一步，寫出 State Schema 與 terminal 狀態；第二步，把現有固定流程拆成可單獨測試的 Node；第三步，加入確定性 Edge 並完成 happy path；第四步，加入一個受限的模型 Router；第五步，接上持久化與 task_id；第六步，為寫入工具加入冪等鍵與人工閘門；第七步，建立 trace 與 eval dataset；第八步，最後才加入平行 Worker、subgraph 或動態規劃。概念性流程可寫成 `START → validate → classify → [research || test || security] → merge → verify → approve → END`，每一個箭頭都必須能說明條件與失敗去向。
19. 框架與協定怎麼選：Runtime、SDK、架構指南與 A2A 解決不同問題
LangGraph 偏向具共享狀態、checkpoint、中斷與可回復執行的 Graph Runtime；OpenAI Agents SDK 提供 Agent、工具、handoff、guardrail、session 與 tracing 等較輕量原語；Microsoft Azure Architecture Center 提供拓撲與選型指南，而不是特定 Runtime；A2A 則是獨立 Agent 系統之間的互通協定，以 Agent Card、Message、Task、Artifact、狀態生命週期、串流與推播描述跨服務協作。AI 判讀：單一應用內先用函式或 Graph Runtime；只有 Agent 分屬不同部署、語言、供應商或權限域時，才需要把邊界提升成 A2A 類協定。
20. 常見反模式：把角色扮演誤當架構，把聊天紀錄誤當狀態
警訊包括：為每個小步驟建立一個 Agent；所有 Agent 共用同一組高權限工具；用共享聊天室累積無限上下文；讓 LLM 自由決定任何下一站；Maker 同時擔任 Checker；平行 Worker 直接競寫同一份資料；只有重試沒有補償；只保存最後答案不保存 trace；只用 LLM Judge 而沒有確定性驗證；用平均成功率掩蓋高風險失敗；測試時連到真實外部系統。Microsoft Research 的 Magentic-One 顯示 Orchestrator 加專業 Agent 可以處理複雜任務，但其評估同樣依賴隔離、可重複執行與錯誤分析，不能只複製角色名稱。
21. 上線檢查表：能回答這十二題，才算從 Demo 走向系統
一、每個 State 欄位是否有型別與來源；二、每個 Node 是否有明確輸入輸出；三、每條 Edge 是否有可測條件；四、每個 Loop 是否有硬上限；五、平行結果是否有衝突規則；六、重試是否會重複副作用；七、程序重啟能否從 checkpoint 繼續；八、不可逆工具是否需要核准；九、各 Agent 是否採最小權限；十、trace 是否能還原路由、工具與狀態變化；十一、eval 是否檢查最終 outcome 與真實失敗；十二、模型、工具或提示更新後是否有可比較的回歸基準。缺少其中一項，都應先限制權限與自動化範圍。
22. 不確定性與邊界：Graph 能控制流程，但不能自動創造正確性
Graph 可以降低協作混亂、保存狀態、限制權限並改善除錯，但它無法保證模型推論正確，也無法替代領域規格、資料品質與風險責任。框架 API、A2A 與 OpenTelemetry 的 Agent 語意仍持續演進，實作前需確認所用版本；供應商文件也可能偏向其產品能力。AI 建議：把架構選擇視為可逆決策，先建立單一 Agent 或固定 Workflow 的基準資料，再用成功率、人工修正時間、延遲、成本、重大失敗率與可恢復性證明 Graph 的額外複雜度確實值得。