Pydantic AI Graph 簡介

雖然使用多代理人協作（Agent Delegation）可以解決很多問題，但當你的 AI 應用程式的邏輯流程變得高度複雜，包含明確的步驟順序、條件判斷分支 (if-else)、甚至需要來回循環的流程 (Loops) 時，單純依靠大語言模型自己決定要呼叫哪個工具，會變得非常不穩定且難以預測。

為了解決這類「需要嚴格掌控執行流程」的場景，Pydantic 團隊推出了 Pydantic Graph。

什麼是 Pydantic Graph？

Pydantic Graph 是一個用來構建狀態機 (State Machine) 或有向圖 (Directed Graph) 流程的 Python 函式庫。它與 Pydantic AI 完美契合，但本身是一個獨立的工具，專注於流程的編排 (Orchestration)。

你可以把 Pydantic Graph 想像成一張流程圖： 流程圖上的每一個「節點 (Node)」代表一個具體的動作或運算步驟（可能包含呼叫一個 Pydantic AI Agent），而節點之間的「連線 (Edges)」則定義了流程該往哪裡走。

為什麼需要 Graph 狀態機架構？

使用圖形 (Graph) 架構來設計 AI 工作流有幾個巨大的優勢：

1. 控制權與可預測性 (Predictability)： 讓 LLM 自己決定下一步要做什麼，就等於把控制權交給了 AI，這在某些關鍵任務上風險過高。透過 Graph，你可以在節點內部利用 AI 的理解能力，但由 Graph 的邊界條件來決定下一個執行的步驟。這將「不確定的 AI 生成」約束在一個「確定性的流程框架」內。
2. 複雜狀態的維護 (State Management)： Pydantic Graph 允許你在節點之間傳遞一個強型別的「狀態物件 (State Object)」。這個狀態物件會隨著流程的推進被不斷更新。比起把所有資訊都塞入對話歷史中，一個結構化的狀態物件更有效率且不易出錯。
3. 無限循環與重試機制 (Cycles)： 圖形結構允許流程回頭走（例如：AI 寫完一段程式碼 -> 執行測試節點 -> 測試失敗 -> 回到寫程式碼的節點修正 -> 再次測試）。這種自省與修正的迴圈 (Self-Reflection and Correction) 是打造高級 AI Agent 的核心模式。
4. 視覺化與好除錯： 基於圖形的架構通常可以被輕易地渲染成視覺化的流程圖 (例如使用 Mermaid.js)。你可以清楚看到整個 AI 工作流的全貌，當出錯時，也能立刻知道是在哪一個節點卡住的。

Pydantic Graph 的基礎元件

在開始寫程式碼之前，我們需要先了解 Pydantic Graph 中的幾個核心名詞：

• Graph (圖)：整個流程的總稱，包含所有的節點與連線。
• State (狀態)：一個 Pydantic BaseModel 或 dataclass，用來在節點之間傳遞與累積資料。
• Node / Step (節點 / 步驟)：流程圖中的一個圓圈。通常代表一個 Python 函數。這個函數會接收當前的 State，執行某些邏輯（可能是呼叫 LLM），然後決定下一個要去哪一個 Node。
• End (結束點)：一種特殊的節點，當流程走到這裡時，整個 Graph 的執行就會終止並回傳最終結果。

在下一篇文章中，我們將透過具體的程式碼範例，帶你一步步建立你的第一個 Pydantic Graph 流程。