Pydantic AI 新版 Graph API 簡介

在先前的章節中，我們介紹了基於 BaseNode 類別的 Pydantic Graph 寫法。為了讓開發者在處理「平行執行」、「條件分支」以及「複雜工作流」時能有更直覺的體驗，Pydantic 團隊推出了全新的 Beta Graph API。

這個新版的 Beta API 與原有的 API 互相兼容，但它採用了不同的設計模式，也就是 Builder Pattern (建造者模式)。

Beta API 的核心特色

新的 Beta Graph API 透過 pydantic-graph 套件提供了一個強大的建構器介面，具備以下幾項主要優勢：

  1. 更簡潔的語法：透過 Python 的裝飾器 (@g.step)，你不再需要定義一堆類別與繼承，直接寫非同步函數即可成為節點。
  2. 明確的平行控制：提供了內建的 map (映射) 與 broadcast (廣播) 語法，讓同時執行多個 AI 任務變得異常簡單。
  3. 內建的匯總機制 (Reducers)：處理平行任務時，通常需要將結果收集起來。Beta API 內建了 Join 節點與常見的 Reducer 模式，安全且方便地聚合資料。
  4. 易於視覺化的資料流：透過 g.add(g.edge_from(...).to(...)) 明確定義節點之間的連線 (Edges)，這讓流程的依賴關係更加一目瞭然，甚至能直接輸出 Mermaid 流程圖。
雖然這個 API 冠上了 Beta 的名稱，但它代表的是 Pydantic 團隊對未來 Graph 開發體驗的最新設計方向。原有的物件導向 (Class-based) 寫法依然被完全支援，你可以根據專案的複雜度與團隊的偏好來選擇使用哪一種 API。

Builder Pattern：GraphBuilder

在 Beta API 中，一切的出發點都是 GraphBuilder 類別。它就像是一塊畫布，讓你可以宣告整個狀態機的形狀。

當你建立一個 GraphBuilder 實例時，你需要明確告訴它：

  • state_type：貫穿所有節點的共用狀態 (State) 型別。
  • input_type：流程剛開始啟動時，預期收到的初始輸入資料型別（可選）。
  • output_type：流程結束時，預期輸出的最終結果型別。
  • deps_type：如果有依賴注入 (Dependencies) 需求，需要宣告型別（可選）。

這確保了從流程的起點到終點，資料型別都是受到嚴格檢查的，維持了 Pydantic 家族一貫的型別安全 (Type-safe) 傳統。

持久化 (Persistence) 注意事項

要注意的是，與舊版的 Graph API 不同，Beta Graph API 目前 沒有內建原生的狀態持久化機制 (Native Persistence)。這主要是因為在高度平行的執行狀態下，要做到一致性 (Consistent) 的快照 (Snapshotting) 非常複雜。

如果你正在開發的 AI 工作流程非常漫長，需要跨越系統重啟、或是需要支援中斷後接續執行，官方建議整合使用支援持久化執行的解決方案，例如 Temporal 等。

在接下來的文章中，我們將透過具體的程式碼範例，帶你使用 GraphBuilder 一步步打造出你的 Beta API 工作流。