Pydantic AI 完整指南 2026：型別安全的 AI Agent 開發框架

在 2026 年的 AI Agent 開發生態中，Pydantic AI 以其獨特的型別安全理念和簡潔的 API 設計脫穎而出。作為 Pydantic 團隊的最新力作，它將資料驗證的嚴謹性與 LLM 的靈活性完美結合，成為構建生產級 AI 應用首選框架。

為什麼選擇 Pydantic AI？

核心優勢

型別安全是第一公民。與 LangGraph、CrewAI 等框架不同，Pydantic AI 從底層就建立在 Pydantic 的型別系統之上。這意味著：

• ✅ 函數引數和返回值自動驗證
• ✅ LLM 輸出結構化，避免解析錯誤
• ✅ IDE 自動補全和型別檢查
• ✅ 執行時錯誤大幅減少

簡潔的 API 設計。無需學習複雜的狀態機或圖論概念，用純 Python 程式碼即可構建強大的 Agent。

原生流式支援。內建 SSE 和流式響應，輕鬆實現打字機效果。

多模型相容。支援 OpenAI、Anthropic、Google、Ollama 以及任何相容 OpenAI API 的模型。

快速開始

安裝

pip install pydantic-ai

基礎示例：第一個 Agent

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

# 初始化模型
model = OpenAIModel('gpt-4o')

# 建立 Agent
agent = Agent(model)

# 執行對話
result = agent.run_sync('解釋量子糾纏，用高中生能理解的語言')
print(result.data)

結構化輸出

這是 Pydantic AI 最強大的功能之一：

from pydantic import BaseModel
from pydantic_ai import Agent

class WeatherReport(BaseModel):
    temperature: float
    condition: str
    humidity: int
    recommendation: str

agent = Agent('openai:gpt-4o', result_type=WeatherReport)
result = agent.run_sync('北京今天的天氣如何？')

# 直接獲得 Pydantic 模型例項
weather: WeatherReport = result.data
print(f"溫度：{weather.temperature}°C")
print(f"建議：{weather.recommendation}")

核心概念詳解

1. 依賴注入系統

Pydantic AI 提供優雅的依賴注入，讓 Agent 可以存取外部工具和服務：

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    user_id: str
    api_key: str

agent = Agent('openai:gpt-4o', deps_type=AppDeps)

@agent.tool
async def get_user_profile(ctx: RunContext[AppDeps]) -> str:
    """獲取當前使用者資料"""
    # ctx.deps.user_id 和 ctx.deps.api_key 可用
    return f"使用者 {ctx.deps.user_id} 的資料..."

# 執行時傳入依賴
result = await agent.run(
    '顯示我的個人資料',
    deps=AppDeps(user_id='12345', api_key='secret')
)

2. 多步驟對話

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

# 第一輪
result1 = agent.run_sync('我想學習 Python，給我制定一個學習計劃')
print(result1.data)

# 繼續對話（保持上下文）
result2 = agent.run_sync('第二週應該重點學什麼？', message_history=result1.history)
print(result2.data)

3. 流式響應

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

async def stream_response():
    async with agent.run_stream('寫一首關於 AI 的短詩') as result:
        async for message in result.stream_text():
            print(message, end='', flush=True)

# 或使用 run_stream_sync
for message in agent.run_stream_sync('講個程式設計師笑話'):
    print(message, end='')

實戰案例：智慧客服 Agent

from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
from typing import Literal

class SupportTicket(BaseModel):
    category: Literal['技術', '賬單', '產品諮詢', '其他']
    priority: Literal['低', '中', '高', '緊急']
    summary: str = Field(description='問題摘要，50 字以內')
    suggested_action: str

class SupportDeps:
    def __init__(self, customer_id: str):
        self.customer_id = customer_id
        self.tier = 'premium'  # 從資料庫獲取

agent = Agent(
    'anthropic:claude-3-7-sonnet',
    result_type=SupportTicket,
    deps_type=SupportDeps
)

@agent.tool
async def check_customer_history(ctx: RunContext[SupportDeps]) -> str:
    """查詢客戶歷史工單"""
    return f"客戶 {ctx.deps.customer_id} 歷史：3 個已解決工單"

@agent.tool
async def escalate_ticket(ctx: RunContext[SupportDeps], reason: str) -> str:
    """升級工單到人工客服"""
    return f"工單已升級，原因：{reason}"

# 使用
deps = SupportDeps(customer_id='CUST-789')
result = agent.run_sync(
    '我的賬戶被錯誤扣費了，這已經是第三次發生！',
    deps=deps
)

ticket: SupportTicket = result.data
print(f"分類：{ticket.category}")
print(f"優先順序：{ticket.priority}")
print(f"建議操作：{ticket.suggested_action}")

高階特性

1. 結果驗證器

from pydantic_ai import Agent, ResultValidator

def validate_length(result):
    if len(result.data) < 10:
        raise ValueError('回覆太短，請詳細說明')
    return result

agent = Agent('openai:gpt-4o')
agent.result_validator(validate_length)

2. 自訂模型提供者

from pydantic_ai.models import Model
from pydantic_ai.messages import ModelRequest, ModelResponse

class CustomModel(Model):
    async def request(self, request: ModelRequest) -> ModelResponse:
        # 實現自訂推理邏輯
        pass

agent = Agent(CustomModel())

3. 批次處理

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o')

prompts = [
    '總結這篇文章',
    '提取關鍵詞',
    '生成標題',
]

results = agent.run_sync_multiple(prompts)
for i, result in enumerate(results):
    print(f"任務 {i+1}: {result.data}")

效能對比

根據 2026 年 Q1 的基準測試：

框架	首次 Token 延遲	型別安全	學習曲線	生產就緒度
Pydantic AI	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
LangGraph	⭐⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
CrewAI	⭐⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
AutoGen	⭐⭐	⭐⭐⭐	⭐⭐	⭐⭐⭐

最佳實踐

1. 始終定義結果型別

# ❌ 不推薦
agent = Agent('openai:gpt-4o')

# ✅ 推薦
class Response(BaseModel):
    answer: str
    sources: list[str]

agent = Agent('openai:gpt-4o', result_type=Response)

2. 合理使用工具

# ❌ 避免過多工具
@agent.tool
@agent.tool
@agent.tool
@agent.tool  # 太多工具會降低效能

# ✅ 聚焦核心功能
@agent.tool
@agent.tool  # 2-3 個關鍵工具

3. 錯誤處理

from pydantic_ai.exceptions import ModelRetry

@agent.tool
async def search_database(query: str) -> str:
    try:
        # 搜尋邏輯
        pass
    except Exception as e:
        raise ModelRetry(f'搜尋失敗：{str(e)}')

生態整合

與 FastAPI 整合

from fastapi import FastAPI
from pydantic_ai import Agent

app = FastAPI()
agent = Agent('openai:gpt-4o')

@app.post('/chat')
async def chat(prompt: str):
    result = await agent.run(prompt)
    return {'response': result.data}

與 LangChain 互操作

from langchain.pydantic_ai import PydanticAIWrapper

wrapper = PydanticAIWrapper(agent)
chain = wrapper | output_parser

總結

Pydantic AI 代表了 AI Agent 開發的未來方向：型別安全、簡潔優雅、生產就緒。如果你正在尋找：

• 🎯 減少執行時錯誤
• 🎯 提高程式碼可維護性
• 🎯 快速迭代原型
• 🎯 無縫整合現有 Python 專案

那麼 Pydantic AI 值得你投入時間學習。

參考資源

• Pydantic AI 官方文件
• GitHub 倉庫
• Pydantic 官方文件
• 示例專案集合
• 社群討論

---

最後更新：2026-03-28