把 AI 當一般工程對待:Pydantic AI 憑什麼在 2026 年突圍?

Pydantic 團隊推出 Pydantic AI 時,將型別驗證、重試與測試等工程實務帶入 Agent 開發。

正如 Pydantic 團隊在發布文中所強調:

building GenAI applications is still just engineering

開發生成式 AI 應用終究是一般工程。把不確定性高的語言模型,當成隨時可能出錯的遠端 API 時,工程重點便回歸到嚴謹的型別驗證、可靠的重試機制與單元測試。

Pydantic AI 在兩年內累積了超過 2 萬顆 GitHub 星數,月下載量突破數百萬次。作為建立在 Pydantic 之上的 Agent 框架,它有哪些工程優勢?採用時又需要考慮哪些代價?


核心定位:以 Pydantic 模型整合 AI 應用

Pydantic AI 使用 Pydantic 模型驗證資料,將型別契約帶入 AI 應用。

官方在發布文中直言自建框架的初衷:

We built Pydantic AI because no existing agent framework met our bar for developer ergonomics, engineering quality, and production readiness.

這份初衷也確立了 Pydantic AI 的取捨:寧可捨棄過度包裝的代理概念,也要守住程式碼的可維護性。

這套框架最大的優勢在於生態位:無論是 OpenAI SDK、Anthropic SDK、Google GenAI SDK、LangChain 還是 FastAPI,底層早已全面採用 Pydantic 作為資料結構驗證層。

相較於其他框架常引入自訂的 Message 或 Document 抽象類別,迫使開發者在 Web 請求模型、框架物件與業務資料間層層轉換,Pydantic AI 天生站在 Python 最短的整合路徑上:從 FastAPI 輸入、工具參數到結構化輸出,皆以原生 Pydantic 模型與標準 Dataclass 貫穿,構成端到端的型別契約。


兩大差異化優勢:執行期型別契約與免 API 單元測試

Pydantic AI 的特色,在於把靜態型別提示延伸為執行期的強制契約。這具體體現在兩個關鍵機制上:

1. 結構化輸出的自我修正機制

在 Pydantic AI 中,Agent 的輸出直接綁定 Pydantic 模型。模型產生的原始文字必須通過驗證才算完成交付;若欄位型別不合或缺少必要鍵值,框架會自動將驗證錯誤訊息作為回饋注入對話,要求 LLM 自動重新修正。

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    urgency: int  # 1–5

agent = Agent(model="openai:gpt-5", output_type=SupportTicket)
result = agent.run_sync("客戶說系統整個掛了,要馬上處理")
print(result.output.urgency)  # 保證為通過驗證的整數

除了輸出驗證,Tool 函式的參數也直接由型別提示動態生成 JSON Schema,呼叫時逐次驗證。而外部依賴(如資料庫連線或 API 金鑰)則透過 deps_type 以 Dataclass 明確注入,避免了隱式全域變數與環境耦合,讓工具函式的外部依賴一目了然,大幅降低測試時 Mock 替換與隔離的難度。

AI 資料分析引擎 MindsDB 在使用動態鏈框架兩年後,決定將核心管線遷移至 Pydantic AI。執行長 Jorge Torres 指出核心痛點:

我們越讓 LLM 在迴圈裡自行發揮,它犯的錯就越多。

他們放棄的是由模型自主決定行動路徑的代理迴圈(Agentic Loop),改採由程式碼主控的工作流程(Code-first workflow),僅在單一步驟仰賴 Pydantic AI 進行局部、確定性的資料契約驗證與重試。

每個步驟產出經驗證的 Pydantic 物件,使後續路由邏輯能建立在經驗證、確定的契約上,同時移除了以 GB 計的龐雜相依套件。

在 Speakeasy 引用的 Nextbuild 90 天實測中,這套執行期型別系統在進入正式環境前,就攔截了 23 個若缺乏嚴格驗證便會直接流向生產線的資料契約缺陷。

2. 視為一級公民的可測試性

多數 Agent 框架在測試時,高度仰賴真實 API 呼叫或昂貴的雲端追蹤平台,而 Pydantic AI 內建了 TestModel 與 FunctionModel。

官方文件對 TestModel 的定義是:它「沒有任何 ML 或 AI,就是一段平實的程序式 Python 程式碼,想辦法產出能通過 tool 的 JSON schema 驗證的資料」。

搭配全域開關 ALLOW_MODEL_REQUESTS = False,工程師能在 CI/CD 管線中阻斷對外部 LLM 的網路請求,並利用 Agent.override(model=...) 與 capture_run_messages() 斷言 Agent 的內部思考與工具呼叫流程。

這讓 Agent 邏輯得以像普通業務程式碼一樣在 pytest 中快速執行回歸測試,擺脫過去依賴外部 tracing 平台或昂貴 token 成本的困境。

在 Speakeasy 引用的 Nextbuild 90 天實測中,Pydantic AI 的開發者體驗(DX)評分為 8/10,在五個受測框架中最高。


架構取捨:Pydantic AI vs LangGraph 的狀態哲學對照

進入 2026 年,Agent 框架市場已度過野蠻生長期。Speakeasy 評測指出,相較於早期的龐大抽象,現代框架更像是「sharper tools for the job」(針對特定工種更鋒利的工具)。在架構評估上,Pydantic AI 與另一主流 LangGraph 展現了截然不同的取捨:

架構面向Pydantic AILangGraph
核心哲學軟體工程優先、型別強制約束圖狀計算優先、靈活編排狀態流程
狀態管理機制預設無狀態,長流程交由外部 Durable 引擎原生 Checkpointing,步驟自動持久化
容錯與中斷恢復依賴外部工作流程引擎(Temporal、Restate 等)內建中斷重啟與 Human-in-the-loop
相依性與架構負擔輕量、僅綁定 Pydantic,無額外抽象負擔較重,深度綁定 LangChain 概念體系
適用情境職責明確的微服務 Agent、精準工具呼叫複雜分支、高度動態迴圈的長流程狀態圖

狀態管理的關鍵分歧:原生 Checkpointing vs 外部 Durable 引擎

這兩者最關鍵的架構差異在於狀態管理。

LangGraph 的強項在於原生 Checkpointing 機制。它會在工作流程的每個步驟自動將完整狀態寫入持久化層;一旦伺服器崩潰或需要人工介入審核,系統能直接從中斷節點續跑。

相較之下,Pydantic AI 預設是「無狀態」的。它的生命週期嚴格約束在單次執行內:若要維護跨輪次對話,應用層需自行傳遞歷史,例如以 result.all_messages() 取出、下一次執行時傳回。官方另提供選用的 ConversationStore 與 conversation= 等持久化選項,但都不是預設行為。

面對需要歷時數天的人工審核、非同步中斷等待或節點崩潰重播的長流程容錯(Durable Execution),框架自身不提供持久化狀態機,而是透過介面整合 Temporal、DBOS、Prefect、Restate 等成熟的外部分散式工作流程引擎。

若系統需要複雜條件跳轉與長時間中斷等待,LangGraph 的原生 Checkpointing 較適合管理長流程狀態;若 Agent 職責明確,且不需要自行管理長流程狀態,Pydantic AI 則不必為此引入工作流程引擎。

TIP

「外層狀態圖、內層型別契約」的互補架構:實務上已出現這類折衷做法。社群也出現混用模式:以 LangGraph 負責跨節點的長流程狀態圖與人工審核,並將「圖中的個別執行節點」改由 Pydantic AI 封裝——長流程歸狀態圖,節點內部執行歸型別契約,分工恰好沿著雙方強項切開。


無法忽視的代價:版本疲勞、生態規模不足與治理缺口

儘管工程品質備受讚譽,在評估架構時,仍不能忽視採用 Pydantic AI 的客觀代價:


演進展望:小核心架構與確定性的工程定位

為了讓核心在高速迭代下保持穩定,同時在激烈競爭中快速擴充能力,Pydantic AI 在 v2 確立了清晰的架構分流策略:

Core stays small and stable… Everything else lives in the Harness, where it can move fast.

團隊以此建立了一套明確的內外層分工:

架構層級職責劃分與核心能力迭代節奏與相容性承諾
Core(核心)型別安全、模型串接、依賴注入等底層基礎設施保持精簡、高相容性與長期穩定
Harness(外圍)記憶管理、Guardrails、子代理、檔案存取等高階能力透過 Capability 封裝規格,允許快速迭代實驗

破壞性變更是否就此收斂,仍取決於三個月相容時間窗在 v2→v3 之間的實際執行。