用 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