Pydantic AI：从结构化输出到生产应用，Python 智能体怎么做？

本文已于 2026 年 10 月 17 日对照官方文档和代码仓库中的许可证核验。下文的选型依据是输出校验、应用服务接入、工作流由谁管理，以及故障后的恢复方式，不是性能排名。

Pydantic AI 是什么？

Pydantic AI 是 Pydantic 团队开发的 Python 智能体 SDK。 它把模型、指令、可调用的 Python 函数，以及可选的输出类型组合成一个 Agent，由应用负责运行。模型负责生成响应，SDK 则管理围绕模型展开的交互。当前的概览文档介绍了更广泛的 SDK 能力，但要为产品实现一个功能，首先需要理解的就是这个核心。

可以把它理解为：给一个行为难以预测的协作者规定函数契约。应用提供上下文和允许执行的操作，再要求它返回包含指定字段的结果。例如，客服功能需要输出问题类别和下一步建议，供普通 Python 代码继续处理，这套机制就很实用。

Pydantic AI 智能体：可复用的任务单元

Agent 保存完成某项任务所需的配置。一次运行，则是带着具体提示词和运行时依赖去执行这项任务的一次尝试。在同步脚本中可以调用 run_sync()，在异步应用代码中可以使用 await agent.run()；运行完成后，通过结果对象的 .output 读取最终值。这些用法均见于 Agent API 文档。

这里的类型机制承担两项不同的工作。静态类型帮助编辑器或类型检查器发现 Python 代码中的类型不匹配；运行时输出校验则检查模型返回的数据是否符合声明的 schema。无论哪一种，都无法让含糊的客服请求自动变得清晰。

Pydantic AI 工具：让函数访问应用上下文

函数工具让模型能够请求执行代码支持的操作，例如查询订阅信息。需要运行上下文的函数用 @agent.tool 注册，不需要上下文的函数则用 @agent.tool_plain。类型提示描述参数，文档字符串帮助模型理解工具的用途。函数工具文档说明了这些信息如何转化为工具 schema。

依赖注入，就是把某次运行需要的服务传入这次运行。 用 deps_type=CustomerContext 声明预期的 Python 类型，再用 deps=customer_context 传入实际实例。工具接收 RunContext[CustomerContext]，并通过 ctx.deps 读取依赖。上下文可以携带已认证的客户、数据库连接或 API 客户端。依赖指南明确指出，deps_type 用于支持类型检查，而不会对依赖对象执行运行时校验。

对于 SaaS 开发者，这带来的好处很具体：在模型请求查询之前，服务器就能确定客户账户。权限校验仍应放在查询代码中。通过带类型的上下文传入数据库客户端，并不会限制该客户端可以读取哪些数据行。

Pydantic AI 结构化输出：究竟校验了什么？

output_type 定义应用期望接收的结果。 传入一个 Pydantic BaseModel，也就是带有类型字段的 Python 类，Pydantic AI 就会据此生成 schema，并校验模型生成的数据。输出文档还列出了其他受支持的类型，包括 dataclass、列表和联合类型。

三种输出模式的区别，在于如何要求模型生成这些数据：

这是 SDK 文档列出的三种输出模式，并非三个准确率等级。应先选择模型支持的机制，再用自己的任务评估结果。

校验失败时，可以把错误反馈给模型，让它再次尝试。重试次数有上限，输出重试耗尽后可能抛出 UnexpectedModelBehavior。应用需要准备失败处理路径，例如补问缺失信息，或将请求转交人工。具体见重试行为说明。

Pydantic AI 教程：返回经过校验的客服分流结果

先从只读的决策对象开始，再考虑赋予智能体修改数据的权限。 下面的示例基于文档中的 Agent、RunContext 和 output_type 用法，实现一个小型客服分流任务。

当前安装指南要求 Python 3.11 或更高版本。在虚拟环境中安装库：

python -m pip install pydantic-ai

在环境变量中设置 OPENAI_API_KEY，对应账户需有权限访问所用模型。将以下代码保存为 triage.py，然后运行 python triage.py。模型标识沿用当前 Agent 文档中的写法，也可以换成你的账户能够使用且受支持的模型。

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

运行成功后，result.output 是一个 Triage 对象。它的类别和优先级必须属于声明的可选值，model_dump() 则把该对象转换为字典。示例中的上下文工具、带类型的结果，以及拒绝非法类别的行为，都已用 TestModel 离线检查。模型生成的措辞和分流准确率，仍需用你自己的案例评估。

这里的客户上下文仅作示意。用于产品时，应根据已认证的请求和账户记录构造上下文。还需要定义什么情况算紧急：schema 只列出了合法标签，并没有包含紧急程度的判定规则。补上这条业务规则，比再加一个智能体更重要。

Pydantic AI 模型接入：换服务商，也要重新验证行为

Pydantic AI 减少了对接不同服务商的代码，但更换模型仍会改变行为。 许多接入方式使用 <provider>:<model> 标识；有些则需要显式配置模型或客户端、相应凭据，以及额外的安装依赖。服务商目录也明确说明，功能支持取决于所选模型和 API。

该目录包括 OpenAI、Anthropic、Google/Gemini、AWS Bedrock、Groq、Mistral、xAI 和 Ollama。文档列出的其他接入方式还包括：

• 模型与推理服务： Alibaba Cloud/Qwen、Cerebras、Cohere、Crusoe、DeepSeek、Fireworks AI、Heroku AI、Hugging Face、Meta、Moonshot AI/Kimi、Nebius AI Studio、OVHcloud AI Endpoints、SambaNova、Snowflake Cortex、Together AI 和 Z.AI。
• 云平台、网关与自托管方案： Google Cloud/Vertex AI、Microsoft Azure/Foundry、Pydantic AI Gateway、LiteLLM、OpenRouter、Vercel AI Gateway 和 vLLM。
• 其他访问方式与决策模型接入： GitHub Copilot、OpenAI Codex、OpenAI Decisions API、System One API 和 TypeSafe (Jev)。

这些名称代表不同的模型接入方式，并不意味着功能可以等价替换。本地模型的工具行为可能与托管的前沿模型不同；即便 API 兼容，对 schema 的限制也可能不同。

对创业者而言，可迁移性意味着保留替换路径和试验空间。对负责落地的开发者而言，验收标准没有改变：替代模型能否选对工具、遵守输出 schema，并在同一组案例上给出可接受的判断？在更改生产环境的默认配置之前，先留存这些验证结果。

MCP 与持久化执行：接入工具，保留运行进度

MCP 负责把智能体连接到工具服务器；持久化执行帮助运行在中断后继续。 两者解决的是不同的问题。

Model Context Protocol（模型上下文协议，简称 MCP）为应用向 AI 客户端提供工具和上下文定义了统一规范。Pydantic AI 的 MCP 能力支持传入服务器 URL、客户端或工具集，在服务商支持的情况下，也可使用其原生 MCP 选项。这让你能够复用工具服务器，无须为每个智能体重新编写集成代码。但它不会替你决定哪些客户有权执行该服务器上的操作。

持久化执行会保存进度，让任务在故障、重启或长时间等待后继续。当前的持久化执行文档列出了 9 种方案：

• 与供应商团队共同维护： Temporal、DBOS、Prefect、Restate 和 AWS Lambda。
• 外部 SDK 集成： Kitaru、Apache Airflow、Absurd 和 pgtask。

此外，还提供用于接入其他引擎的后端构建器。如果智能体需要在发起它的请求或进程结束后继续运行，应选择文档列出的集成方案。这些集成的存在，并不意味着单独调用一次 Agent 就构成了支持持久化执行的部署。

设想一个客服任务：先给出退款建议，等待审批，再执行退款。保存运行状态可以保留等待中的任务，但支付操作仍需保证幂等性，也就是重复请求不应再次产生退款。你需要决定如何识别已经完成的操作，以及如何核对结果不明的操作。这部分责任仍在应用，不能只交给引擎。

Pydantic AI 评估：检查对象背后的判断

Pydantic Evals 检验的是智能体是否完成了可接受的工作，而不只是输出能否被解析。 它是一个独立、以代码为中心的评估包，不依赖 Pydantic AI。你定义案例和评估器，用这些案例运行任务，再查看报告。文档介绍了如何为最终输出和工具调用轨迹评分；后者指一次运行中采取的一系列行动。

针对前面的分流示例，可以构造重复扣款、登录失败、缺少账户上下文，以及要求助手忽略自身指令的消息等案例。检查问题类别、是否需要升级处理，以及是否完成了必要的账户查询。也要包含那些应当通过追问来回应的案例。

对运维人员而言，调用链追踪解释单次运行，评估则衡量多个案例上的行为。 Pydantic AI 使用应用遥测标准 OpenTelemetry，并通过其插桩机制支持其他可观测性后端。某个案例失败时，检查模型请求和工具调用，再把该案例保留在评估集中。

可选的 Pydantic Logfire 提供智能体、模型和工具追踪。根据其定价页面，Personal 套餐免费，Team 套餐 $49/月起，额外用量和席位另行计费。

什么情况下该选 Pydantic AI？

选抽象层，要看功能最难的部分在哪里。 对于已有领域模型和服务的 Python 开发者，如果主要集成难点是带类型的输入、工具和输出，Pydantic AI 值得列入候选。技术型创业者则应进一步追问：哪种选择能让业务保留一个足够精简、解释得清且维护得动的运行系统？

Pydantic AI 与 LangGraph 怎么选？

如果你希望明确设计智能体外围的工作流，LangGraph 更适合作为起点。 它的文档围绕长期运行的有状态智能体、持久化执行和人工介入展开。典型场景是具有必经阶段的应用：收集证据、取得审批、执行已授权操作，再核对结果。

如果应用已经控制了整个流程，只需把带类型的智能体作为其中一个组件，Pydantic AI 就很有吸引力。它也能参与持久化工作流，因此能否持久化并不足以决定选型。关键在于：你想围绕智能体建模整个业务流程，还是主要配置智能体自身的行为？LangGraph 的门槛，是你必须负责工作流设计和状态管理；Pydantic AI 的边界，则在于方便的智能体契约不会替你设计完整流程。

Pydantic AI 与 LangChain 怎么选？

如果 LangChain 现有的模型与工具集成、智能体架构已经契合应用，选择它就有充分理由。 根据 LangChain 概览，LangChain 智能体建立在 LangGraph 之上，使用它的高层智能体 API，并不意味着放弃这层运行时基础。

如果 Pydantic AI 的依赖和输出契约契合你现有的编码方式，可以在 Python 服务中选择它。已经正常运行的 LangChain 功能应继续保留，除非你能指出迁移具体消除了哪一处复杂性。当行为跨越智能体层与工作流层时，仍需理解 LangChain 的抽象；换库只会把这项工作转移到别处。两者更深入的关系，见 LangChain 与 LangGraph 对比。

OpenAI Agents SDK 与直接调用 API

OpenAI Agents SDK 适合由应用掌控智能体循环，并需要工具、任务交接和追踪的场景。 SDK 在你的应用内运行，支持结构化输出；它的服务商接口也能接入非 OpenAI 模型。因此，不能把带类型的输出或服务商选择说成 Pydantic AI 独有的能力。

如果该 SDK 的智能体与交接机制契合你准备维护的 OpenAI 集成，可以选择它。如果 Pydantic AI 的 Python 依赖模型和服务商配置更合适，就选 Pydantic AI。两者都把部署、工具授权和应用正确性留给你负责。

如果任务只是一次模型请求，外围只有少量确定性代码，直接调用 API 即可。 原生 API 已经能够返回受 schema 约束的输出。收据提取功能不必仅仅因为结果是 Pydantic 对象，就引入智能体框架。真正需要重新考虑的时刻，是你开始在不同功能中反复搭建工具调用循环、校验重试和观测埋点。

更全面的选型可以参考现有的 AI 智能体框架指南。如果你还在权衡显式的工作流控制与分工明确的智能体角色，可以继续阅读 LangGraph 与 CrewAI 对比。

带类型的智能体，哪些期待被夸大了？

最被夸大的说法，是带类型的智能体天然就是正确可靠的生产系统。 有些边界，库无法替你消除：

• 类型安全不等于事实准确。 格式完好的答案仍可能误解用户请求。你需要决定哪些内容必须对照权威记录核验。
• 模型可迁移不等于质量一致。 更换服务商配置，与更换提示词一样，都需要用同样的任务评估来检验。
• 支持持久化执行不等于自动完成部署。 仍需选择并运维功能所需的引擎、存储和恢复路径。
• 重试会增加工作量。 再发一次模型请求，就会增加延迟和用量。重试耗尽后，应用应有明确的处理结果。

如果下一个 Python 功能已经需要工具和结构化决策，现在就值得动手。如果现有系统运行良好，而迁移的收益只是演示代码看起来更整洁，可以先缓一缓。如果功能只是直接的信息提取调用，并且已有充分的校验和错误处理，那么是否采用这类框架，对你影响不大。

Pydantic AI 常见问题

下周可以先上线什么？

先为一个小型只读功能设定明确的验收边界，再扩大它的自主权限。 对客服产品，可以从示例中的分流对象起步，把最终的账户操作保留在普通应用代码中。

想获取构建 AI 功能的实用笔记，可以订阅邮件通讯。