Pydantic AI：讓 Agent 開發回歸工程本質的 Type-Safe 框架

在 AI 應用開發的早期，許多工程師都經歷過一段「文字解析」的陣痛期。為了讓大型語言模型（LLM）與外部系統互動，我們必須在提示詞中苦苦懇求模型「請務必輸出 JSON 格式」，並在程式碼中寫滿各種 try-except 與正則表達式，來處理模型偶爾出錯的資料結構。

這種充滿「膠水程式碼（Glue Code）」的開發模式，在小型專案中或許還行得通；但當專案規模擴大，缺乏型別驗證的字串拼接，往往會成為系統中最脆弱的一環。

為了解決這個工程痛點，Python 生態系中知名的資料驗證庫 Pydantic 團隊，推出了專為 AI Agent 設計的框架：Pydantic AI。

• 什麼是 Pydantic AI？
• 核心機制與架構
  • 1. 結構化輸出與自動重試 (Structured Outputs)
  • 2. 型別安全的工具呼叫 (Type-Safe Tools)
  • 3. 依賴注入系統 (Dependency Injection)
• 實戰範例：客服信件自動解析
• Pydantic AI 的生態定位與競爭比較
• 實用建議：三個起步行動
  • 步驟 1：安裝環境與套件
  • 步驟 2：從簡單的資料萃取開始
  • 步驟 3：結合 Logfire 進行觀測
• 我的反思
• 參考資料 (References)

什麼是 Pydantic AI？

Pydantic AI 是一個以 Type-Safe（型別安全） 為核心的 Agent 框架。

它的設計理念非常明確：將 Agent 視為結構化的軟體，而不是一個會講話的黑盒子。 如果你曾經使用過 FastAPI 開發網頁後端，你會發現 Pydantic AI 帶來的開發體驗非常相似。它讓開發者能用最熟悉的 Python 型別提示（Type Hints）與 BaseModel，來約束並規範 LLM 的行為與輸出。

核心機制與架構

Pydantic AI 解決了過去 Agent 框架常見的幾個痛點，其運作架構主要由以下幾個核心機制構成：

1. 結構化輸出與自動重試 (Structured Outputs)

這是 Pydantic AI 最核心的功能。你只需要定義一個 Pydantic 的 BaseModel，框架就會自動處理與 LLM 之間的溝通與驗證。

from pydantic import BaseModel
from pydantic_ai import Agent

class UserProfile(BaseModel):
    name: str
    age: int
    interests: list[str]

# 宣告 Agent 並指定預期的回傳型別
agent = Agent('openai:gpt-4o', result_type=UserProfile)

# 執行任務，獲得強型別的物件
result = agent.run_sync('我叫 Harry，今年 30 歲，喜歡寫程式跟看電影')
print(result.data.name) # 編輯器會有自動補齊：Harry

如果 LLM 給出的資料格式錯誤（例如把年齡寫成了字串 "三十"），Pydantic 驗證層會立刻捕捉這個錯誤，並將錯誤訊息與修正要求自動發回給 LLM 進行重試，直到獲得符合規範的資料。

2. 型別安全的工具呼叫 (Type-Safe Tools)

在為 Agent 提供外部工具時，你只需要寫標準的 Python 函式，並加上 Type Hints 與 Docstrings。框架會自動將這些標註轉換為 LLM 能夠理解的工具規格。

@agent.tool_plain
def get_weather(location: str) -> str:
    """取得指定地點的即時天氣資訊。"""
    if location == 'Taipei':
        return '晴天，28度'
    return '未知'

3. 依賴注入系統 (Dependency Injection)

過去許多 Agent 框架在處理資料庫連線或使用者狀態時，往往需要依賴全域變數（Global State），這讓單元測試變得相當棘手。Pydantic AI 引入了類似 FastAPI 的依賴注入，你可以在執行時動態傳入連線物件，確保業務邏輯的封閉性。

實戰範例：客服信件自動解析

為了讓你感受 Pydantic AI 真正的實用價值，想像一個企業極度常見的需求：「收到客戶抱怨信時，自動判定緊急程度並萃取關鍵資訊存入資料庫」。

過去你可能要寫一長串的 Prompt，還要擔心模型偶爾忘了輸出某個必填欄位導致程式當機。使用 Pydantic AI，你只需要定義好資料結構：

from pydantic import BaseModel, Field
from pydantic_ai import Agent

# 1. 透過 Pydantic 定義我們期望的絕對嚴謹格式
class TicketAnalysis(BaseModel):
    category: str = Field(description="分類：退款、技術支援、或客訴")
    is_urgent: bool = Field(description="是否提到法律行動或情緒極度憤怒")
    summary: str = Field(description="用一句話總結核心問題")

# 2. 建立 Agent 並綁定型別
agent = Agent('openai:gpt-4o', result_type=TicketAnalysis)

# 3. 丟入充滿情緒且凌亂的真實客戶信件
email_content = "你們的軟體昨天更新後一直閃退！我報告打到一半全沒了，再不修好我明天就去投訴你們，立刻退費給我！"
result = agent.run_sync(email_content)

# 4. 獲得穩定、可直接存入資料庫的 Python 物件
print(result.data.is_urgent) # 輸出: True
print(result.data.category)  # 輸出: 退款
print(result.data.summary)   # 輸出: 軟體更新後導致閃退且資料遺失，要求退費。

這段不到 20 行的程式碼展示了 Pydantic AI 的最大殺傷力：無論輸入的自然語言多麼沒有結構，它最後都會被「強制轉化」成 100% 符合你程式碼規格的強型別物件。 這讓你在串接後端 API 或寫入 SQL 資料庫時，完全沒有後顧之憂。

Pydantic AI 的生態定位與競爭比較

自 2024 年底由 Pydantic 官方團隊正式開源推出以來，Pydantic AI 迅速在開發者社群中獲得高度關注，並成為構建生產級 AI 應用的熱門選擇。

為了更清楚理解它的定位，我們可以用一個簡單的對照表，來比較它與目前市面上主流 Agent 框架的差異：

從表格中可以看出，Pydantic AI 提供了一個非常獨特的切入點。多數框架著重於提供廣泛的第三方工具整合或是多智能體對話；而 Pydantic AI 則專注於「模型互動的工程品質」。它不強制你使用特定的記憶體管理套件，也支援多種底層 LLM（如 OpenAI、Gemini、Groq 等），單純給你一個極度穩定、不會因為 JSON 解析失敗而當機的核心執行環境。

實用建議：三個起步行動

如果你想親自體驗 Type-Safe Agent 的開發流程，可以嘗試以下步驟：

步驟 1：安裝環境與套件

在你的 Python 環境中，只需一行指令即可安裝：

pip install pydantic-ai

步驟 2：從簡單的資料萃取開始

不要一開始就寫會自動操作電腦的複雜 Agent。先嘗試把一篇雜亂的部落格文章，透過 Pydantic AI 加上 BaseModel，精準地萃取出標題、作者與核心觀點。這能讓你立刻感受到「結構化輸出」的穩定性。

步驟 3：結合 Logfire 進行觀測

Pydantic 團隊也推出了配套的觀測工具 Logfire。只要簡單的設定，你就能在儀表板上清楚看到 Agent 每一次重試的過程、呼叫工具的耗時，這對於生產環境的除錯非常有幫助。

我的反思

Pydantic AI 認為把邏輯寫在容易產生幻覺的自然語言裡，不如把約束寫在強型別的程式碼裡。

這種「Code as Constraints（程式碼即約束）」的思維轉變，不僅降低了執行期的不可預期性，也讓工程師能用習慣的 IDE 自動補齊與單元測試來維護 AI 系統。這絕對是走向企業級 AI 應用的正確道路。

參考資料 (References)

官方資源與文件

• Pydantic AI 官方文件
• Pydantic 官方 GitHub 存放庫