用 PydanticAI 讓 LLM 輸出變成可信賴的 Python 對象

構建過 AI agent 的人大概都遇到過這種情況：LLM 返回的數據"差不多"是你要的但又不完全對。比如會遇到字段名拼錯了數據類型不對，或者干脆多了幾個莫名其妙的 key。

這是問題出在哪？當前主流的 agentic AI 系統處理輸出的方式太原始了，比如說脆弱的 JSON 解析、基于 prompt 的 schema 約束、各種后處理 hack。這套東西在 demo 里能跑通，到了生產環境就是定時炸彈。

PydanticAI 提供了一個根本性的解決方案：類型安全的 LLM 響應。它能把 AI 輸出直接轉換成經過驗證的 Python 對象，配合 CrewAI 這類 agent 框架使用效果是相當不錯的。

本文會介紹 PydanticAI 的核心概念，解釋為什么類型化響應對 agent 系統如此重要并給出與 CrewAI 集成的實際代碼示例。

LLM 輸出的核心問題

Agentic 框架功能很強，但在最基礎的環節：數據契約上，表現得相當糟糕。

典型的 agent 開發流程是這樣的：先讓 LLM 返回 JSON，然后祈禱它遵循你定義的 schema，不行就加重試邏輯，最后發現還是得手寫驗證器。這套流程走下來，agent 變得不穩定，失敗時沒有任何提示，調試起來痛苦萬分。

類型化系統正是為了解決這個問題而存在的。

PydanticAI 是什么

PydanticAI 把 LLM、Python 類型系統和 Pydantic 模型組合在一起。核心理念很簡單：LLM 響應必須符合預定義的 Python 類型，不符合就直接報錯。

沒有殘缺數據，沒有靜默失敗，沒有靠猜。

為什么 CrewAI 需要這個

CrewAI 的強項在于多 agent 協調、角色分配和任務分解。但 agent 之間的數據傳遞、工具調用、記憶持久化，都需要結構化輸出作為基礎。這正是 PydanticAI 填補的空白——它提供了一個可靠的契約層。

安裝

pip install pydantic-ai crewai openai

設置 OpenAI API key：

export OPENAI_API_KEY="your-key"

第一個示例：類型化響應

從最簡單的場景開始。

定義一個響應模型：

from pydantic import BaseModel
class Summary(BaseModel):
title: str
key_points: list[str]
confidence: float

這不是注釋或文檔，這是硬性契約。

創建 agent：

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel
model = OpenAIModel("gpt-5-mini")
agent = Agent(
model=model,
result_type=Summary
)

運行：

result = agent.run_sync(
"Summarize the benefits of typed AI agents"
)
print(result.title)
print(result.key_points)
print(result.confidence)

這里發生了什么？LLM 被強制返回符合 Summary 結構的數據，驗證自動進行，輸出不合法會觸發重試或直接失敗。這才是可以上生產的 LLM 輸出。

Agent 間的數據契約

來看一個更實際的例子：兩個 agent 協作。

研究 agent：

class ResearchResult(BaseModel):
topic: str
findings: list[str]
research_agent = Agent(
model=model,
result_type=ResearchResult
)

寫作 agent，負責消費研究 agent 的輸出：

class BlogDraft(BaseModel):
headline: str
sections: list[str]
writer_agent = Agent(
model=model,
result_type=BlogDraft
)

協作流程：

research = research_agent.run_sync(
"Research typed LLM outputs in AI agents"
)
draft = writer_agent.run_sync(
f"Write a blog using these findings: {research.findings}"
)

整個過程沒有 JSON 解析，不用猜測 schema，Python 對象在 agent 之間直接流轉。

與 CrewAI 集成

CrewAI 負責編排，PydanticAI 負責類型正確性，這種組合越來越常見。

from crewai import Agent as CrewAgent, Task
analysis_agent = CrewAgent(
role="Analyst",
goal="Generate structured insights"
)
task = Task(
description="Analyze market trends in AI tooling",
agent=analysis_agent
)

加入類型化執行層：

typed_agent = Agent(
model=model,
result_type=ResearchResult
)
result = typed_agent.run_sync(task.description)

CrewAI 處理 agent 的角色和任務分配，PydanticAI 保證輸出的結構正確。

類型化如何改變可靠性

沒有類型約束的 agent 系統會出現各種問題：agent 憑空生成不存在的 key，下游步驟因為數據格式錯誤而靜默失敗，排查問題時無從下手。

用了 PydanticAI 之后，無效輸出會被立即拒絕，重試自動觸發，這樣bug 在早期就會暴露出來。這其實是軟件工程領域早就有的實踐：API 用 schema 約束，數據庫用約束條件，編譯器做類型檢查，Agentic AI 只不過是終于跟上了這個標準。

生產環境用例

PydanticAI 加 CrewAI 的組合適合這些場景：研究類 agent、內容生成流水線、數據提取任務、業務流程自動化、AI 輔助決策系統。只要你的應用對輸出結構有要求，這套方案就值得考慮。

不過有幾個做法應該避免：讓 agent 返回原始字符串然后自己解析，用 eval() 處理 JSON（安全隱患太大），盲目相信"格式良好"的 prompt 能約束輸出，在 agent 之間傳遞未經驗證的數據。

類型化不是額外負擔，是風險控制。

總結

Agentic AI 發展很快，但速度如果沒有結構做支撐，系統就會變得脆弱。PydanticAI 把軟件工程的類型規范帶入了 LLM 系統，讓 agent 更安全、更可預測、更容易擴展。

當 AI 輸出變成真正的 Python 對象，agent 就不再只是 demo，而是可以正式投入使用的系統。

https://avoid.overfit.cn/post/2a20c5c4c1394c92a252a04388f8e26e

作者：Er.Muruganantham