PydanticAI

PydanticAI 是由 Pydantic 幕后团队构建的 Python 智能体框架，由 Samuel Colvin 领导，他也是创建了在整个 Python 生态系统中广泛使用的 Pydantic 验证库的工程师。该框架于 2024 年 12 月 2 日在 AWS re:Invent 大会期间发布，在获得 1500 万次下载后，于 2025 年 9 月 4 日发布了 1.0 稳定版。该框架采用 MIT 许可证，可免费使用。它的核心承诺是：将使 FastAPI 成为默认 Python Web 框架的相同开发者体验带入 AI 智能体构建中，用适当的类型契约和经过验证的输出取代临时的 JSON 解析和脆弱的提示词工程。

PydanticAI 开箱即用地支持 OpenAI、Anthropic、Google、xAI、Amazon Bedrock、Groq、Mistral、Ollama、Cohere、OpenRouter、Hugging Face 和 Cerebras。主要功能包括通过 Pydantic 模型进行结构化输出验证、使用 RunContext 的依赖注入系统（可将数据库连接和 API 客户端干净地传递到工具中）、带有实时验证的流式传输、模型上下文协议（MCP）支持、人在回路（human-in-the-loop）工具审批、多智能体架构，以及通过 Temporal 集成实现的持久化执行。与 Pydantic Logfire 的紧密集成提供了基于 OpenTelemetry 的可观测性，用于追踪智能体运行、跟踪 Token 成本以及在生产环境中调试工具调用。截至 2026 年 5 月，该代码库在 GitHub 上拥有超过 16,800 颗星，发布了 241 个以上版本，并被在 Amazon Bedrock AgentCore 上进行构建的团队用于生产环境。

PydanticAI 在 2026 年 5 月的实际功能

PydanticAI 以单一的 Agent 类为中心，该类封装了 LLM、一组工具、系统提示词和结构化输出模式。当智能体运行时，它会在每次调用时根据 Pydantic 模型验证模型的输出，如果验证失败，则会自动使用纠正反馈进行重试。这消除了智能体系统中最大的一类生产故障：LLM 返回格式错误、缺失或类型错误的数据，从而导致下游代码崩溃。

依赖注入系统是第二个主要差异化优势。工具在运行时接收一个类型化的 RunContext[Dependencies] 对象，而不是通过全局状态或环境变量传递配置。在实践中，这意味着数据库连接、外部 API 客户端或用户上下文可以在智能体调用时干净地注入，使得工具无需实时 LLM 调用即可进行单元测试。这是借鉴自 FastAPI 依赖系统的设计模式，它解决了团队在将智能体代码库扩展到单个文件之外时遇到的真正痛点。为智能体工具编写测试不再需要实时的 LLM 调用或实时数据库：您只需将模拟的依赖对象传递给 RunContext 并对结果进行断言。

流式传输支持包括对结构化部分输出的实时验证，而不仅仅是 Token 流式传输。这对于渲染增量结构化数据而非纯文本的仪表板和实时 UI 至关重要：框架会在每个部分输出块到达时对其进行验证，因此应用程序永远不必在流完成后处理验证错误。通过 PydanticAI 的 Graph API 添加的基于图的工作流，允许将复杂的智能体流程建模为类型化的状态机，并在状态之间进行 IDE 验证的转换。多智能体通信（智能体之间的交接）、MCP 服务器/客户端支持以及持久化执行（智能体可以暂停、持久化状态并通过 Temporal 在中断后恢复）完善了功能集。截至 2026 年初的路线图包括提示词缓存、嵌入支持、上下文无关语法输出以及扩展的 MCP 资源支持。

这在实践中如何发挥作用的一个具体例子：一个基于 PydanticAI 构建的法律文档分类系统报告了 94% 的准确率，而使用关键字匹配的准确率为 67%。一个电子商务客户支持智能体自动解决了 38% 的传入工单，满意度得分为 96%。一个房地产 CRM 集成在不到 8 秒的时间内处理了 40-60 个并发通知。这些不是 PydanticAI 的营销说辞；它们是由个别开发者公布的数据，这些开发者专门为了摆脱以前工具中的验证失败而切换到该框架。

“当我第四次不得不调试一个默默返回格式错误的 JSON 并导致客户订单处理管道崩溃的 LangChain 智能体时，我决定不再在午夜修补类型错误了。” - jahanzaibai，DEV Community，2025

PydanticAI 与 LangChain 和 smolagents 的定位对比

PydanticAI vs. LangChain：LangChain 拥有超过 9.6 万颗 GitHub 星星、成熟的集成库以及多年的生产部署经验。它不会消失。但该框架带有大量累积的复杂性：约 300MB 的占用空间、多种已弃用的模式（传统的 AgentExecutor 与较新的 LangGraph），以及将 ChatModel、提示词模板、AgentExecutor 和 RunnableWithMessageHistory 分离为必须连接在一起的不同层的架构。对于结构化输出，如果没有自定义的 StructuredResponseTool 变通方法，LangChain 无法在同一个智能体中结合 with_structured_output() 和其他工具。PydanticAI 原生处理这个问题。对于依赖注入，LangChain 需要使用基于类的工具对 BaseTool 进行子类化；PydanticAI 使用带有 RunContext 的普通函数。代价是生态系统的广度：LangChain 拥有 PydanticAI 目前根本没有的连接器。

PydanticAI vs. smolagents：Hugging Face 的 smolagents 采取了相反的架构押注。它的整个核心大约只有 1,000 行 Python 代码。智能体直接编写和执行 Python 代码（代码智能体），而不是通过 JSON 模式调用预定义的工具。这带来了效率的提升：smolagents 声称在复杂的基准测试中，与 JSON 风格的工具使用相比，LLM 调用减少了约 30%。代价是 smolagents 没有内置的结构化输出验证，没有原生的异步支持，并且内存处理能力有限。PydanticAI 在每个边界强制执行数据一致性；smolagents 则针对实验速度和最小占用空间进行了优化。如果您正在 Hugging Face 托管的模型上进行原型设计，并希望在一个小时内运行起来，smolagents 胜出。如果您正在构建一个对合规性敏感的生产系统，其中每个输出都必须根据模式进行验证，那么 PydanticAI 胜出。

值得注意的是：DSPy 占据了不同的相邻空间，它通过算法优化提示词程序，而不是提供运行时执行层。LangGraph（LangChain 生态系统的一部分）是有状态多智能体编排的最直接竞争对手。LiteLLM 是互补的：一个与提供商无关的路由层，PydanticAI 可以构建在其之上。CrewAI 针对基于角色的多智能体系统，具有更高层次的抽象，以控制力换取简单性。

智能体循环的实际情况

典型的 PydanticAI 工作流从为预期输出定义 Pydantic 模型开始，创建一个带有系统提示词和模型后端的 Agent，然后将 Python 函数装饰为工具。运行智能体会返回一个类型化的结果对象，而不是字符串。IDE 在代码运行之前就知道每个工具参数和每个输出字段的形状。

对于可观测性，调用 logfire.configure() 和 logfire.instrument_pydantic_ai() 会激活对每次 LLM 调用、每次工具调用和每次验证尝试的自动追踪。OpenTelemetry 基础意味着追踪数据可以导出到任何兼容的后端，而不仅仅是 Logfire 的商业平台。这是一个有意义的区别：一些团队已经在使用 Datadog 或 Grafana，并且不希望引入第二个可观测性供应商。

生产团队报告了可靠的结果。一位开发者记录了法律文档分类的准确率达到 94%（高于关键字匹配的 67%），电子商务支持工单的自动解决率达到 38%，满意度得分为 96%，并在不到 8 秒的时间内处理了 40-60 个并发的房地产 CRM 通知。这些数字来自专门切换到 PydanticAI 以停止在凌晨 2 点追踪 JSON 解析失败的团队。

“在花了太多时间在动态类型的智能体链中寻找属性访问错误之后，这比任何基准测试数字都重要。” - jahanzaibai，DEV Community，2025

PydanticAI 是为谁构建的

最清晰的信号：如果您使用过 FastAPI，并且将 Python 的类型系统视为基础设施而不是文档，那么 PydanticAI 会让您立刻感到熟悉。该框架面向那些希望将智能体开发视为常规软件工程（具有单元测试、类型契约和 IDE 支持）的工程师，而不是将其视为提示词技巧与运气的结合。

它非常适合已经使用 Pydantic 的团队（考虑到 OpenAI SDK、Google ADK 和 LangChain 本身都依赖 Pydantic 进行验证，目前大多数使用 LLM 的 Python 团队都是如此）。采用 PydanticAI 是附加的，而不是完全重写。它也适合对合规性敏感的领域：金融、医疗保健、法律，在这些领域，每个 AI 输出都必须是可审计和结构化的。Thoughtworks 在 2025 年 11 月将其移至“试用（Trial）”阶段，这是他们发出的信号，表明企业应该在实际项目中使用它，以建立对该类别的理解。

对于使用 Amazon Bedrock AgentCore 的团队来说，这是一个合理的选择，因为 PydanticAI 是第一方支持的框架。对于跨多个提供商进行路由的团队，它可以与 LiteLLM 自然集成。

PydanticAI 不是什么

PydanticAI 并不是适用于所有技术栈的通用智能体瑞士军刀。一些诚实的限制：

它仅支持 Python。没有 JavaScript、TypeScript 或其他语言的 SDK。如果您的后端是 Go、Java 或 Node.js，您需要寻找不同的框架。

截至 2026 年中，智能体核心不支持多模态输入（图像、音频、视频）。该框架处理文本和结构化数据；将图像传递到工具中需要在框架的验证层之外进行手动处理。

对于具有复杂状态图的大规模多智能体编排，LangGraph 拥有更成熟的工具。PydanticAI 的 Graph API 功能完备但较新，开发者报告称，对于庞大的多智能体系统，其人体工程学设计仍在完善中。

对 Logfire 依赖的担忧值得注意。可观测性集成非常出色且真正有用，但 Pydantic 团队有商业动机引导用户使用 Logfire 的付费层。该框架会发出 OpenTelemetry 数据，因此您不会被硬性锁定，但已经拥有可观测性技术栈（Datadog、Honeycomb、Grafana）的团队在做出承诺之前应验证导出路径。

还有一些值得注意的已知问题：v1.30.0 版本意外引入了对 openai v2.8.0 的硬依赖，破坏了现有项目（GitHub issue #3707），重试逻辑并不总是能如预期解决验证失败（issue #739），并且 DeepSeek 模型支持存在映射错误。一个活跃的开发团队和 364 个未解决的 issue 意味着该框架响应迅速，但仍有一些粗糙之处。

在以下情况下请跳过 PydanticAI：您希望在一个下午就能运行起来且无需 Pydantic 知识，您的技术栈不是 Python，您需要成熟的多模态智能体工具，或者您需要 LangChain 300 多个集成的广度。