PydanticAI 详解用“类型安全”重新定义 AI Agent 开发关键词PydanticAI、AI Agent、类型安全、结构化输出、Python 框架 目录一个让 LLM 输出“守规矩”的故事PydanticAI 是什么为什么偏偏是 PydanticAI—— 它解决了什么痛点核心特性速览十分钟快速上手深入核心概念实际应用场景PydanticAI vs LangChain怎么选2026 最新动态V2 时代来了总结与学习路线1. 一个让 LLM 输出“守规矩”的故事想象一下这个场景你开发了一个 AI 客服 Agent让它从用户邮件中提取“姓名”、“订单号”和“问题描述”。你信心满满地上线了。然后第一个用户来了。Agent 返回了这样一串 JSON{name:张三,order_id:ABC123,issue:快递还没到}完美你松了一口气。第二个用户来了。Agent 返回了{customer_name:李四,id:XYZ789,problem:我要退货}字段名变了类型也变了。你的代码直接崩溃。第三个用户更离谱Agent 返回了订单号是 12345用户叫王五他说东西坏了。纯文本连 JSON 都不是。这就是当前 AI Agent 开发中最常见的噩梦LLM 的输出不可预测。主流做法是“先让 LLM 返回 JSON然后祈祷它遵循你定义的 schema不行就加重试逻辑最后发现还是得手写验证器”。这套流程在 demo 里能跑通到了生产环境就是定时炸弹。PydanticAI 就是为了终结这种噩梦而生的。一句话理解PydanticAI 让 LLM 的输出必须符合你定义的 Python 类型不符合就直接报错——没有残缺数据没有静默失败没有靠猜。2. PydanticAI 是什么PydanticAI是一个 Python Agent 框架旨在帮助开发者快速、自信且轻松地构建生产级的生成式 AI 应用程序和工作流。它的创造者是Pydantic 团队——没错就是那个写 Pydantic 验证库的团队。你可能不知道的是几乎所有的 Python Agent 框架和 LLM 库OpenAI SDK、Google ADK、Anthropic SDK、LangChain、LlamaIndex、AutoGPT、CrewAI 等都在用 Pydantic 做数据验证。PydanticAI 的定位很明确既然大家都在用 Pydantic为什么不直接用 Pydantic 团队亲手打造的 Agent 框架如果把 PydanticAI 比作一个人那它就是“那个出身名门、从小就在数据验证领域泡大的家伙”——它继承了 Pydantic 强大的数据验证能力同时为 AI 模型集成、提示词管理和 Agent 开发添加了专门的工具。3. 为什么偏偏是 PydanticAI—— 它解决了什么痛点在 PydanticAI 出现之前市面上已经有 LangChain、CrewAI、AutoGen 等众多 Agent 框架。为什么 Pydantic 团队还要再造一个答案很简单没有一个现成的框架能同时满足他们对开发者体验、工程质量和生产就绪的要求。具体来说PydanticAI 解决了以下几个核心痛点痛点一LLM 输出不可预测这是最根本的问题。LLM 本质上是“概率模型”每次输出都可能不同。传统的处理方式是“后处理”——等 LLM 输出完了再解析、再验证、再重试。PydanticAI 的做法是“前置约束”——在请求发出之前就告诉 LLM“你必须按这个格式输出否则重来”。痛点二类型安全缺失大多数 Agent 框架对类型安全不够重视。字段名拼错了、数据类型不对了、多了一个莫名其妙的 key——这些问题在运行时才会暴露。PydanticAI 把类型检查从“运行时”搬到了“编写时”——你的 IDE 就能提前发现错误。痛点三可观测性不足生产环境中的 AI Agent 像一个“黑盒子”——你不知道它为什么这么回答、花了多少钱、哪里出了问题。PydanticAI 原生集成了 OpenTelemetry 可观测性标准可以实时追踪、调试、监控成本和性能。痛点四缺乏生产级特性很多 Agent 框架只适合做 demo一到生产环境就暴露出各种问题没有断点续跑、没有人机审批、没有依赖注入。PydanticAI 从设计之初就瞄准了“生产级”。4. 核心特性速览特性说明类型安全的 LLM 响应LLM 输出必须符合 Pydantic 模型否则自动重试或报错模型无关支持 OpenAI、Anthropic、Gemini、DeepSeek、Grok 等几乎所有主流模型和提供商无缝可观测性与 Pydantic Logfire 深度集成支持 OpenTelemetry 标准人在回路工具审批标记某些工具调用需要人工审批后才能执行持久化执行Agent 可以在故障或重启后恢复进度支持长时间运行的工作流流式输出支持实时流式传输响应依赖注入优雅地管理数据库连接、用户偏好等运行时上下文100% 测试覆盖率每个文档示例都经过单元测试MCP / A2A / AG-UI 集成支持模型上下文协议、Agent 间通信和 UI 事件流标准5. 十分钟快速上手5.1 安装pipinstallpydantic-ai如果你还想运行官方示例pipinstallpydantic-ai[examples]5.2 第一个 Agent类型化响应这是 PydanticAI 最核心的能力展示——让 LLM 的输出变成一个经过验证的 Python 对象。frompydanticimportBaseModelfrompydantic_aiimportAgentfrompydantic_ai.models.openaiimportOpenAIModel# 1. 定义输出模型——这不是注释这是硬性契约classSummary(BaseModel):title:strkey_points:list[str]confidence:float# 2. 创建 Agent指定输出类型modelOpenAIModel(gpt-4o-mini)agentAgent(modelmodel,result_typeSummary# 关键LLM 必须返回 Summary 类型)# 3. 运行 Agentresultagent.run_sync(Summarize the benefits of typed AI agents)# 4. 结果直接就是 Python 对象类型安全print(result.title)print(result.key_points)print(result.confidence)这里发生了什么LLM 被强制返回符合Summary结构的数据验证自动进行无需手写任何解析代码输出不合法会自动触发重试或直接失败5.3 给 Agent 加“系统提示词”frompydantic_aiimportAgent agentAgent(modelmodel,result_typeSummary,system_prompt你是一个专业的技术文档分析师擅长提取核心观点。)resultagent.run_sync(请总结这篇文章...)5.4 让 Agent 使用工具Function Toolfrompydantic_aiimportAgent,RunContextimportrandom# 定义一个工具函数用 agent.tool 装饰器注册agent.tooldefget_random_fact(ctx:RunContext,topic:str)-str:获取关于某个主题的随机事实facts{python:Python 是 1991 年由 Guido van Rossum 创建的。,ai:人工智能一词最早在 1956 年达特茅斯会议上提出。,}returnfacts.get(topic,f关于{topic}的事实还在整理中...)# Agent 现在可以在对话中调用这个工具了resultagent.run_sync(给我一个关于 Python 的随机事实)print(result.data)工具的核心价值让 LLM 能够调用你的 Python 函数访问真实数据和计算能力。6. 深入核心概念6.1 Agent代理Agent是 PydanticAI 中最核心的接口。它封装了一个 LLM 模型系统提示词输出类型Pydantic 模型可用的工具函数依赖注入配置一个 Agent 就是一个“AI 工人”你告诉它“用什么模型”、“输出什么格式”、“能用什么工具”它就能帮你干活。6.2 结构化输出Structured Output这是 PydanticAI 的“杀手锏”。传统方式下LLM 返回的是字符串你需要自己解析。PydanticAI 的做法是你定义一个 PydanticBaseModel把它传给Agent的result_type参数PydanticAI 自动通过工具调用tool calling或 Provider 托管的结构化输出功能强制 LLM 返回符合该模型的数据返回给你的直接就是 Python 对象6.3 依赖注入Dependency Injection在复杂的 Agent 系统中你可能需要共享数据库连接、用户信息、配置等上下文。PydanticAI 提供了类型安全的依赖注入方案fromdataclassesimportdataclassdataclassclassMyDeps:user_id:strdb_connection:stragentAgent(modelmodel,deps_typeMyDeps,# 声明依赖类型)agent.tooldefget_user_info(ctx:RunContext[MyDeps])-str:# ctx.deps 就是类型安全的依赖对象returnf用户{ctx.deps.user_id}的信息...6.4 人在回路Human-in-the-Loop有些操作不能让 AI 自作主张——比如“转账”、“删除数据”、“发送邮件”。PydanticAI 支持标记某些工具调用需要人工审批后才能执行agent.tool_plain(require_approvalTrue)# 需要审批deftransfer_money(amount:float,to_account:str)-str:# 这个函数不会立即执行会先等待用户确认returnf已转账{amount}元到{to_account}7. 实际应用场景场景一AI 客服 Agent银行可以用 PydanticAI 构建一级客服 Agent——从用户消息中提取结构化信息账户类型、问题分类、紧急程度然后路由到对应的人工或自动化处理流程。场景二多 Agent 协作两个 Agent 之间需要传递数据时数据契约至关重要# 研究 Agent 的输出classResearchResult(BaseModel):topic:strfindings:list[str]research_agentAgent(modelmodel,result_typeResearchResult)# 写作 Agent 直接消费 ResearchResultclassWritingResult(BaseModel):title:strcontent:strreferences:list[str]writing_agentAgent(modelmodel,result_typeWritingResult)场景三数据抽取与清洗从非结构化文本邮件、文档、聊天记录中抽取结构化数据classOrderInfo(BaseModel):customer_name:strorder_id:strissue_type:Literal[退货,换货,查询,投诉]urgency:Literal[高,中,低]extractorAgent(modelmodel,result_typeOrderInfo,system_prompt从用户消息中提取订单信息。)8. PydanticAI vs LangChain怎么选这是开发者最常问的问题。两者不是“谁替代谁”的关系而是“各有侧重”的关系。对比维度PydanticAILangChain出身Pydantic 团队官方出品开源社区驱动核心优势类型安全、结构化输出、开发体验生态系统庞大、预集成丰富学习曲线平缓FastAPI 风格陡峭概念多、抽象多模型兼容性支持主流模型但部分小众模型支持较弱兼容性更广支持 Gemini 等更多提供商预集成生态较新生态在成长中极为丰富向量库、检索器、存储器等代码量少简洁 API多需要较多样板代码最佳场景需要结构化输出的生产级 Agent需要大量预集成组件的复杂 RAG 系统选型建议✅用 PydanticAI你需要结构化、类型安全的 LLM 输出你已经在用 Pydantic 或 FastAPI你想快速构建生产级 Agent✅用 LangChain你需要大量预集成的向量库、检索器、存储器你需要支持非常小众的模型提供商你已经有 LangChain 技术栈⚠️两者可以混用你可以在 LangGraph 的节点内部用 PydanticAI 来处理结构化输出——各取所长。9. 2026 最新动态V2 时代来了PydanticAI 的发展速度非常快。截至 2026 年 6 月V1 版本已累计超过1500 万次下载V2.0.0 稳定版已于 2026 年 6 月 23 日正式发布V2 带来了更精简的核心、更强的能力以及一个名为“Harness”的无头编码 Agent——Pydantic 团队正在用自己的框架来重构自己的代码库V1 将继续提供至少 6 个月的安全修复方便用户平滑升级V2 的核心变化Python 3.9 支持与主流版本保持一致更完善的类型系统更强的持久化执行能力10. 总结与学习路线核心知识点回顾✅PydanticAI Pydantic 团队出品的 Python Agent 框架✅核心价值 让 LLM 输出变成类型安全的 Python 对象✅核心机制 定义 Pydantic 模型 → 传给 Agent → 自动验证 自动重试✅主要特性 结构化输出、工具调用、依赖注入、人在回路、持久化执行✅与 LangChain 的关系 不是替代而是各有侧重——PydanticAI 强在类型安全和开发体验LangChain 强在生态广度学习路线图阶段目标实践任务第 1 天理解核心概念读完本文运行 5.2 节的第一个示例第 3 天掌握 Agent 基础创建带系统提示词和工具的 Agent第 1 周结构化输出实战构建一个从邮件中抽取订单信息的 Agent第 2 周多 Agent 协作实现“研究员 分析师”的双 Agent 系统第 3 周生产级部署集成 Pydantic Logfire 做可观测性配置人在回路审批推荐资源PydanticAI 官方文档PydanticAI 官方示例Real Python PydanticAI 教程DataCamp PydanticAI 入门指南