pydantic/pydantic-ai 型別安全 Python 代理框架教學:結構化輸出、依賴注入與測試指南

由 Pydantic 與 FastAPI 團隊打造的 pydantic-ai,將型別驗證與依賴注入帶入 AI 代理開發,解決生產環境輸出格式不穩的痛點,一篇學會實戰開發與單元測試。

Share
PydanticAI官方 GitHub 專案封面圖:PydanticAI 教學
PydanticAI官方開源專案視覺圖。 圖片來源:官方原文。

寫過生產環境 AI 應用的後端工程師,一定都對一個問題感到頭痛:語言模型明明在測試時乖乖回傳 JSON,一上線遇到邊界案例就突然多出一句客套話,或者少了一個必填欄位,導致整個 API 服務當場崩潰。

更難受的是很多早期 AI 框架把型別檢查丟到執行期才報錯。開發過程缺乏編輯器自動補全,連要寫單元測試都得自己手寫一大堆模擬回應,測試覆蓋率根本拉不起來。

PydanticAI 就是為了把傳統軟體工程的嚴謹度帶回 AI 開發而生。它由 Pydantic 驗證層與 FastAPI 核心背後的團隊打造,將強型別結構化輸出、類似 FastAPI 的依賴注入系統與內建測試替身整合進同一個框架。

現在幾乎所有主流模型 SDK 都在底層依賴 Pydantic 做資料驗證,所以這個團隊非常清楚開發者卡在哪裡。他們把多年累積的驗證經驗直接往上延伸成完整的代理開發套件,涵蓋從基礎對話、工具呼叫、MCP 整合到 OpenTelemetry 可觀測性追蹤。

這篇 PydanticAI 教學會帶你掌握安裝流程、核心型別架構、銀行客服實戰範例邏輯、無金鑰單元測試寫法,以及正式上線前必須注意的架構限制。

為什麼需要型別安全的 AI 代理?拆解核心架構

要理解這套型別安全框架為什麼在 Python 後端工程師圈迅速普及,關鍵在於它把開發階段的錯誤攔截提早到「寫程式的當下」,而不是等到客戶端請求失敗才發現。

整個框架建立在四個彼此緊密扣合的技術支柱上:

  1. 結構化輸出驗證 output_type:只要定義好一個 Pydantic BaseModel,系統就會自動把資料結構轉成模型看得懂的結構描述。當模型回傳資料時,框架會立刻進行型別與數值範圍驗證;如果格式不合規範,系統會自動把具體的驗證錯誤訊息丟回給模型重試,直到產出完全合規的 Python 物件為止。
  2. 型別安全的依賴注入 deps_type:在真實系統裡,代理呼叫工具時往往需要存取資料庫連線池、HTTP 客戶端或目前登入的使用者權限。透過 RunContext 泛型物件,你可以把這些外部資源乾淨地注入工具與系統指令中,讓編輯器與靜態型別檢查器能精確檢查每個欄位的型別,徹底告別全域變數滿天飛的混亂寫法。
  3. 可組合的 Capabilities 能力模組:新版架構導入了 Capability 概念,可以把一組相關的系統指令、工具函式與模型設定打包成獨立單元。更重要的是它支援 defer_loading 延遲載入機制,讓代理只在對話真正需要時才把特定工具載入上下文,省下可觀的 Token 成本。
  4. 模型無關與統一介面:切換 OpenAI、Anthropic、Google Gemini、Groq、Mistral、Bedrock 或本地 Ollama,通常只需要改一個字串參數。此外還支援自動容錯備援機制,避免單一供應商當機拖垮整個線上服務。

因為這套系統原生內建 OpenTelemetry 追蹤介面,所以只要搭配 Pydantic Logfire 或任何相容的 OTLP 後端,就能即時看到每一次模型呼叫、工具執行耗時與精確費用,不用額外拼裝複雜的監控外掛。

PydanticAI官方 GitHub 專案封面圖:PydanticAI 教學
PydanticAI官方開源專案視覺圖。 圖片來源:官方原文。

安裝步驟與實戰範例:結構化輸出與依賴注入

安裝這個框架非常直接,官方推薦使用 uv 或 pip 將核心套件加入專案:

uv add pydantic-ai

如果只需要特定模型供應商的輕量依賴,也可以安裝 pydantic-ai-slim 並加上對應的選用套件群組,避免把用不到的雲端 SDK 全部裝進容器映像檔裡。

下面我們參考官方的銀行客服代理架構,寫出一個結合「依賴注入」、「工具呼叫」與「強制結構化輸出」的完整範例。這段程式碼能讓代理在回答客戶問題的同時,自動判斷是否需要鎖卡並給出風險評分:

from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: int
    customer_name: str
    balance: float

class SupportOutput(BaseModel):
    support_advice: str = Field(description="給客戶的具體處理建議")
    block_card: bool = Field(description="是否需要立即暫時凍結卡片")
    risk: int = Field(description="本次對話的風險等級,從 0 到 10", ge=0, le=10)

support_agent = Agent(
    "openai:gpt-4o",
    deps_type=SupportDeps,
    output_type=SupportOutput,
    instructions="你是銀行客服代理,請根據客戶資料提供協助並評估風險等級。",
)

@support_agent.instructions
def add_customer_context(ctx: RunContext[SupportDeps]) -> str:
    return f"目前服務的客戶姓名為 {ctx.deps.customer_name},編號為 {ctx.deps.customer_id}。"

@support_agent.tool
def get_balance(ctx: RunContext[SupportDeps]) -> float:
    """查詢目前客戶的帳戶餘額。"""
    return ctx.deps.balance

執行代理時,呼叫 await support_agent.run 並傳入使用者的抱怨訊息與 deps 依賴物件後,拿到的 result.output 不再是一段難以解析的純文字,而是一個貨真價實的 SupportOutput 實例。

因此,你可以直接存取 result.output.block_card 與 result.output.risk,而且這些欄位名稱與型別都能完全通過靜態型別檢查器驗證,大幅減少線上環境因為拼錯字典鍵值而當機的機率。

延伸閱讀:LangChain 完成 3 億美元 C 輪融資!CapitalG 領投、估值衝上 30 億美元,企業級 AI 代理基礎設施拼什麼?

不用燒錢也能跑 CI:TestModel 單元測試與 Evals 評估

許多開發團隊不敢對 AI 代理寫自動化測試,原因是每次跑 pytest 都要呼叫真實雲端 API。這不僅讓測試速度變慢、花費變高,還會因為模型輸出具有隨機性而導致測試三不五時假性失敗。

這個框架直接在核心層級解決了這個難題。它提供了一個內建的 'test' 模型與 TestModel 測試類別,不需要任何 API 金鑰就能在本地端驗證工具註冊、依賴注入與結構化輸出流程:

from pydantic_ai.models.test import TestModel

def test_support_agent_structure():
    deps = SupportDeps(customer_id=101, customer_name="王小明", balance=5000.0)
    with support_agent.override(model=TestModel()):
        result = support_agent.run_sync("查詢餘額", deps=deps)
        assert isinstance(result.output, SupportOutput)
        assert 0 <= result.output.risk <= 10

透過 override 覆寫方法搭配 TestModel 測試物件,你可以在 CI 管線裡零成本驗證所有型別契約、系統指令組裝邏輯與工具參數轉換是否正常。

不過單元測試通過並不代表模型在真實語意上回答得夠好。因此,團隊若想進一步驗證真實模型的回答品質,還可以搭配生態系裡的 Pydantic Evals 套件,針對輸出結果與工具呼叫軌跡進行自動化評分與回歸測試。

與其他主流 Python 代理框架比較

在評估是否導入這套架構時,很多團隊會拿它跟 smolagents 或多角色編排框架比較。以下從工程實務角度整理核心差異:

比較項目 PydanticAI smolagents 多角色編排框架
核心設計哲學 強型別契約、依賴注入與軟體工程體驗 極簡程式碼優先、模型直接寫 Python 角色扮演、任務分工與團隊協作隱喻
靜態型別檢查支援 頂尖,IDE 與型別檢查器完整推斷輸出與依賴 基礎,偏重動態 Python 執行 中等,多數設定依賴字典或設定檔
無金鑰單元測試 內建 TestModel 與 override 機制,原生友善 需自行模擬模型物件或寫測試替身 測試通常需自行抽換底層 LLM 呼叫
持久化長流程支援 支援整合 Temporal、Prefect、DBOS 等九種引擎 需自行處理狀態儲存與斷點續跑 內建基本狀態紀錄,複雜場景需搭配外部引擎
學習曲線對誰友善 熟悉 FastAPI 與 Pydantic 的後端工程師 喜歡讀百行原始碼、做快速原型的研究者 想快速套用現成角色範本的自動化開發者

生產環境部署的實務邊界與注意事項

把這套框架放進正式生產環境前,有幾個邊界條件必須先掌握,否則上線後容易遇到預期外的瓶頸。

首先是「結構化驗證重試帶來的延遲與成本」。當模型輸出的格式不符合 BaseModel 限制時,框架會自動發起驗證失敗重試。如果沒有設定合理的 retries 上限,或是選擇了完全不擅長遵從結構描述的小型模型,單次請求可能會意外多跑好幾輪推論,進而拉高延遲與帳單。

其次是「複雜狀態圖與單一代理的界線」。如果你的業務邏輯是一條高度確定、包含大量分支跳轉與人工審核關卡的多步驟流程,光靠單一 Agent 的對話迴圈會變得難以維護。

這時應該搭配生態系裡的 Pydantic Graph 來明確定義狀態轉移圖,或是整合 Temporal、DBOS、Prefect 等九種持久化執行引擎,確保服務重啟或系統當機時,執行中的代理任務不會半途遺失。

最後是「執行模型生成程式碼的安全隔離」。如果你在代理中啟用了讓模型動態執行 Python 程式碼的能力,務必搭配沙盒環境,例如 Pydantic 團隊開發的沙盒直譯器 Monty 或獨立容器,絕不能在持有資料庫憑證的主程序中直接執行未知程式碼。

延伸閱讀:Anthropic AI 安全評估 10 項建議:模型更安全的分數怎麼來?

進階實戰技巧:多輪對話記憶、串流輸出與人工審核關卡

在真實的後端系統開發中,代理很少只跑一輪問答就結束,往往需要處理連續對話、即時串流回饋,甚至在高風險動作前暫停等待人類確認。

首先是「多輪對話狀態傳遞」。每次呼叫執行代理後,回傳結果物件裡的 message_history 屬性會完整保留該次對話的系統提示、使用者提問、工具呼叫與模型回應。

當使用者發送下一則訊息時,只要把這份歷史紀錄傳入下一次呼叫的 message_history 參數,代理就能無縫接續上下文,而且開發者可以自由選擇把這些紀錄序列化存進 Redis 或關聯式資料庫裡。

其次是「結構化資料的串流輸出」。對於前端互動介面而言,等待完整結構化物件生成往往需要好幾秒鐘。這個框架支援在模型還在生成欄位內容時,就即時驗證並推送已經完成的部分欄位到前端,兼顧即時體感與型別安全。

第三是「人工介入審核機制」。當代理準備執行資料庫刪除、發送外部郵件或進行金流操作時,可以利用框架支援的延遲工具呼叫機制先暫停執行流程,把即將呼叫的工具名稱與參數回傳給系統介面,等管理員按下核准按鈕後才恢復執行。

最後別忘了設定使用量上限。透過 UsageLimits 物件可以精準限制單次任務允許的最大請求次數與 Token 消耗總量,搭配標準的 OpenTelemetry 追蹤指標,就能為線上服務加上最後一道預算防線。

對於已經使用其他代理框架的團隊,官方也提供了遷移對照指南與輔助技能,協助把既有的 LangChain、Google ADK 或其他框架程式碼平滑移植過來。實務上建議先從專案中最容易因為 JSON 格式錯誤而失敗的單一 API 端點開始替換,驗證完型別檢查、單元測試與可觀測性指標都符合預期後,再逐步擴展到複雜的多代理工作流。

此外,在多人協作的後端專案中,把所有代理的 Output 模型集中在獨立的型別模組管理,能讓前端工程師、測試團隊與資料科學家共享同一份資料契約,大幅減少跨團隊溝通誤差。同時善用 Capability 模組封裝共通的權限檢查與資料庫查詢工具,新建立的代理只要掛載該模組就能立刻具備標準安全防護,不必每次都從頭複製貼上驗證邏輯,也能在審查程式碼時一眼看清每個代理擁有哪些系統權限與外部連線資源。

常見問題

這篇 PydanticAI 教學介紹的框架必須搭配 FastAPI 才能使用嗎?

不需要。它是完全獨立的 Python 套件,你可以把它用在命令列工具、背景排程、Django、Flask 或任何非同步服務中。只是它的依賴注入語法與設計理念跟 FastAPI 高度一致,所以用過 FastAPI 的工程師會覺得非常順手。

為什麼使用時常看到大家討論 Pydantic Logfire?

Logfire 並非強制綁定,因為這套框架輸出的是完全標準的 OpenTelemetry 遙測資料,你可以送到任何現有的監控平台。不過 Logfire 對代理的提示詞、結構化輸出驗證過程與 Token 費用做了專門的視覺化呈現,開發階段用來除錯會省事很多。

如果我只想讓代理回傳純文字,還可以使用這套框架嗎?

可以。只要在建立 Agent 時不指定 output_type,預設回傳型別就是標準字串 str。而且框架同樣支援以串流方式輸出純文字或結構化物件,非常適合拿來打造即時回應的對話介面。

除了純 Python 程式碼外,支援用設定檔定義代理嗎?

支援。根據官方最新文件,除了純 Python 寫法外,系統也支援透過 YAML 或 JSON 規格檔來宣告代理定義,方便需要動態調整提示詞或交由非開發人員管理的團隊使用。

結語

PydanticAI 把寫 AI 代理從「靠感覺調提示詞」拉回「有型別檢查、有依賴注入、有單元測試」的標準軟體工程軌道,讓 AI 功能真正具備長期維護與團隊協作的體質。

適合誰:正在開發正式生產環境服務、重視程式碼可維護性與自動化測試,並且已經習慣使用 Pydantic 與現代 Python 型別標註的後端及全端工程師。

不適合誰:只想寫幾行一次性腳本做資料實驗,或是完全不希望受限於類別定義與型別檢查的新手開發者。

想持續追蹤更多生產級 AI 工程框架、可觀測性工具與評測實戰教學,歡迎立即免費訂閱 AI 郵報,每週幫你把關最值得投入的開源技術。

資料來源