把 AI 當一般工程對待:Pydantic AI 憑什麼在 2026 年突圍?
Pydantic 團隊推出 Pydantic AI 時,將型別驗證、重試與測試等工程實務帶入 Agent 開發。
正如 Pydantic 團隊在發布文中所強調:
開發生成式 AI 應用終究是一般工程。把不確定性高的語言模型,當成隨時可能出錯的遠端 API 時,工程重點便回歸到嚴謹的型別驗證、可靠的重試機制與單元測試。
Pydantic AI 在兩年內累積了超過 2 萬顆 GitHub 星數,月下載量突破數百萬次。作為建立在 Pydantic 之上的 Agent 框架,它有哪些工程優勢?採用時又需要考慮哪些代價?
核心定位:以 Pydantic 模型整合 AI 應用
Pydantic AI 使用 Pydantic 模型驗證資料,將型別契約帶入 AI 應用。
官方在發布文中直言自建框架的初衷:
這份初衷也確立了 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 指出核心痛點:
他們放棄的是由模型自主決定行動路徑的代理迴圈(Agentic Loop),改採由程式碼主控的工作流程(Code-first workflow),僅在單一步驟仰賴 Pydantic AI 進行局部、確定性的資料契約驗證與重試。
每個步驟產出經驗證的 Pydantic 物件,使後續路由邏輯能建立在經驗證、確定的契約上,同時移除了以 GB 計的龐雜相依套件。
在 Speakeasy 引用的 Nextbuild 90 天實測中,這套執行期型別系統在進入正式環境前,就攔截了 23 個若缺乏嚴格驗證便會直接流向生產線的資料契約缺陷。
NOTE
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 AI | LangGraph |
|---|---|---|
| 核心哲學 | 軟體工程優先、型別強制約束 | 圖狀計算優先、靈活編排狀態流程 |
| 狀態管理機制 | 預設無狀態,長流程交由外部 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 採取極高頻率的發布節奏,平均每 1 至 2 天便有一次 Release,且官方將大版本間的 API 相容承諾時間窗縮短至 3 個月。頻繁的破壞性變更(例如提高最低 Python 版本基線、拆分 Provider 套件)對於以季度為維運週期的企業而言,會轉化為真實的升級與維護摩擦。
- 生態規模的結構性落後:據 Speakeasy 評估,其第三方工具與整合生態規模遠小於累積多年的 LangChain。開發者在串接小眾模型或冷門服務時,容易遇上尚未被社群踩平的邊角問題。
- 企業治理功能的缺口:截至 2026 年 3 月 Speakeasy 評測的時點,框架層面尚未內建開箱即用的 Agent 治理原語,例如工具呼叫層級的權限邊界(Tool-level permission boundaries)、敏感資訊遮蔽(PII redaction)與輸入端的 Prompt Injection 主動防護。v2 之後,官方已將 Guardrails(含 PII 與金鑰遮蔽 detector)、Prompt Injection Defender 與 Permissions(寫檔與執行指令前徵詢的三種權限模式)收進第一方 Harness,但屬 opt-in 附加 Capability,預設不啟用;稽核仍靠 OTel 追蹤而非專屬日誌原語,框架自身也沒有合規認證——需要嚴格滿足合規審查的企業,仍須自行補上治理閘道與合規對應。
演進展望:小核心架構與確定性的工程定位
為了讓核心在高速迭代下保持穩定,同時在激烈競爭中快速擴充能力,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 之間的實際執行。