Pydantic AI 的 V2 已经发布三个月了，但很多人还没搞清楚它到底适合什么场景

星火·GitHub 快讯技术创作者 2026-10-01 32 阅读

pydantic/pydantic-ai 是 GitHub 上最受关注的 Python Agent 框架之一，2026 年 10 月 1 日数据：20,299 颗星 · 2,834 个 Fork · 15M+ 下载量 · MIT 许可证，最新稳定版 v2.52.0（2026-09-30） 昨天刚刚发布。

光看数字容易错过一个关键问题：它到底是干什么的，什么场景下值得选，什么场景下该避开？

它解决的核心问题：LLM 输出的可靠性

Pydantic AI 来自 Pydantic 团队——也就是写了 FastAPI 底层那个数据验证库的小组。他们发现了一个不对等：Python 工程师已经在用 Pydantic 验证 API 请求和响应，但到了 AI Agent 层，LLM 返回的”JSON”却被盲目信任。

解决方案很直接：把 Pydantic v2 的验证引擎直接接到每一次 LLM 输出上。

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class Sentiment(BaseModel):
    label: Literal['positive', 'negative', 'neutral']
    score: float = Field(ge=-1, le=1)

agent = Agent('openai:gpt-5-sol', output_type=Sentiment)
result = agent.run_sync('I love the new design!')
# result.output 保证是合法的 Sentiment 对象
# 如果模型输出不合规，Pydantic 会返回验证错误并触发重试

这不是噱头，是架构上的硬约束。工具参数、结构化输出、上下文注入——全部经过类型检查，IDE 能在写代码时就告诉你”这个 agent 返回的字段不匹配”。

V2 的核心变化：Capability 原语

V2（2026-06-23 稳定发布）最大的设计演进是把”围绕 Agent 的所有能力”统一成一个概念：Capability。

一个 Capability 可以包含：指令、工具、生命周期钩子、模型设置，打包成可组合、可复用、可延迟加载的单元。

from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability, Thinking, WebSearch, ToolSearch
from pydantic_ai_harness import Coder

agent = Agent(
    'anthropic:claude-opus-4-7',
    instructions='Research thoroughly and cite your sources.',
    capabilities=[
        Thinking(effort='high'),      # 扩展思考，统一跨 provider
        Coder(),                       # 文件访问 + 沙箱执行 + 子 agent
        WebSearch(),                   # 原生支持 provider web search
        ToolSearch(),                  # 按需发现工具而非预先列出数百个
        Capability(
            id='github',
            description='Look up GitHub issues and PRs.',
            instructions='Use GitHub tools for repository questions.',
            defer_loading=True,        # 模型只在需要时加载完整 capability
        ),
    ],
)

这解决了 V1 时代”每加一个功能就多一个抽象”的问题。现在 Harness（官方能力库）里的 Coder、Memory、Guardrails、FileSystem 全部是 Capability，连 Logfire 的链路追踪也是——你自己写的 capability 和官方能力用同一套 API。

竞品对比：谁该用 Pydantic AI，谁不该用

基于官方文档和多个独立评测：

选 Pydantic AI 当：

输出结构化程度直接影响下游系统可靠性（比如从非结构化文本里提取订单数据）
团队已经在用 Pydantic + FastAPI，类型安全是默认要求
需要在 CI 里离线测试 agent（TestModel / FunctionModel，无 API 调用）
需要 OpenTelemetry 链路追踪，且已有 Datadog / Grafana / Honeycomb

选 LangGraph 当：

工作流是真正的状态机，有分支、循环、检查点
需要复杂的多 agent 协作和显式图结构
需要 LangSmith 的可视化追踪和评估体系

选 CrewAI 当：

团队协作场景，每个 agent 有明确的角色和 mandate
需要基于角色的 agent 编排而非函数式组合

选 OpenAI Agents SDK 当：

100% OpenAI 技术栈，handoffs / tracing / sessions 与现有工作流对齐

不选 Pydantic AI 当：

需要拖拽式可视化构建器（Pydantic AI 是纯代码优先）
主要做 RAG + 向量检索（LlamaIndex / LangChain 更成熟）
在多语言技术栈（C# / Java / Python 并用）里需要跨语言 SDK（看 Semantic Kernel）

适合谁：真实使用门槛

门槛确实存在：

Python ≥ 3.10，异步优先——在 FastAPI endpoint 里调用 agent.run() 会出问题，需要 await agent.run() 或用 run_sync() 明确上下文
代码优先，无 GUI——没有 Flowise / LangFlow 那样的可视化构建器
多 agent 编排能力存在但轻量——subagent 模式支持团队协作，但不如 CrewAI 的 role-based 原语直接
V2 升级有 breaking changes——官方有完整升级指南，V1 到 V2 有明确路径，但需要时间

门槛没有那么大：

学习曲线比 LangChain 低很多——核心 API 就是 Agent(...).run()
TestModel 让测试不需要 API key，CI 里面直接跑毫秒级单元测试
Provider 切换改一个字符串就行，OpenAI / Anthropic / Gemini / Ollama / DeepSeek 全支持
Logfire 有 EU 区域（2025 年 3 月上线）和自托管选项，数据主权有保障

现状：谁在用

官方展示了几个生产案例：

Datalayer：一个 Python 代码库对接四种 agent 协议，从 LangChain 迁到 Pydantic AI，用它做 Jupyter agents
Overjoy：从客户对话到后台任务跑在同一个 agent 栈上，包括长时运行的工作流
Mixam：在保持面向客户的打印助手稳定性的同时，灵活测试不同模型

这些案例的共同点：不是”AI 黑客松项目”，而是真实的 Python 后端服务，把 agent 作为一种受控的运行时而非实验性玩具。

下一步：怎么开始

如果你是 Python 后端工程师，想在现有服务里加一个可靠的 agent 环节：

第一步（5 分钟）： 找一个现在用 json.loads(model_output) 做解析的地方，换成 Pydantic AI agent + output_type。看看验证日志里出现了多少次”模型输出不合规被拦截”。

uv add pydantic-ai

第二步（今天）： 把这个 agent 的链路接上 Logfire（免费层够用），看一次 run 里面的 token 消耗、工具调用次数、验证重试次数。

import logfire
logfire.configure(token='your-token')
logfire.instrument_pydantic_ai()

第三步（这周）： 如果已有 FastAPI 服务，把 agent 做成依赖注入的单例而不是每次请求重建——这能省去每次重建 schema 的开销。

第四步（如果你需要多 agent）： 去看 Pydantic AI Harness 的 Coder / Researcher 组合，了解 subagent 如何在同一个 parent run 里协作，然后再评估是否真的需要 LangGraph 的图结构。

Pydantic AI 不是那种”帮你快速搭一个 demo”的框架。它的价值在于：把 LLM 的输出变成一个你在写代码时就知道形状的数据结构，而不是等到线上才发现模型给你返回了意料之外的东西。

如果你所在的项目对输出可靠性要求高、Python 是主要语言、工程纪律是默认选项——这值得 20 分钟快速上手验证。

仓库：https://github.com/pydantic/pydantic-ai
文档：https://pydantic.dev/docs/ai
官方竞品对比：

vs LangChain & LangGraph
vs OpenAI Agents SDK
vs CrewAI
vs Agno
独立评测参考：PromptQuorum 评测（2026-09） · Alice Labs 生产指南（2026-05）

评论区

0 条评论

登录后可评论。