pydantic-ai,一个严谨的 Python 库

大家好，我是木木。

今天给大家分享一个严谨的 Python 库，pydantic-ai。

pydantic-ai

看到名字时很容易误会：它不是普通的 Pydantic 插件，而是一个明确面向 AI Agent 的框架。它把 Pydantic 擅长的类型校验、结构化输出和开发体验，放进了 Agent、工具调用和模型交互流程里。

如果你的 Agent 不只是聊天，而是要返回稳定结构、调用业务工具、写入数据库或进入审批流程，pydantic-ai 的价值会很明显：它让“模型输出”更接近工程里能信任的数据。

项目地址：https://github.com/pydantic/pydantic-ai
官方文档：https://ai.pydantic.dev

三大特点

类型优先

输出类型、依赖类型、工具参数都可以用 Python 类型和 Pydantic 模型表达，减少自然语言解析的不确定性。

测试友好

内置 TestModel 等测试能力，可以在不访问真实 LLM 的情况下验证 Agent 流程。

工具清晰

工具函数可以直接注册到 Agent 上，参数 schema 会跟着类型生成，适合接订单、知识库、内部接口等业务能力。

最佳实践

安装方式：python -m pip install pydantic-ai==1.92.0

下面的 Demo 使用 TestModel，不会请求外部模型，也不会消耗 API 额度。

功能一：用测试模型跑通 Agent

这段代码解决什么问题：先把 Agent 的输入、系统提示、模型返回和消息历史跑通。真实项目里，测试模型可以帮助你在 CI 里验证流程，而不是每次都依赖真实模型。

importwarningswarnings.filterwarnings('ignore')frompydantic_aiimportAgentfrompydantic_ai.models.testimportTestModelagent=Agent(TestModel(custom_output_text='可以把类型、工具和模型调用放进同一条 Agent 流程。'),system_prompt='你是一个技术选型助手。',)result=agent.run_sync('介绍 Pydantic AI')print('output type:',type(result.output).__name__)print('output:',result.output)print('messages:',len(result.all_messages()))print('model:',result.all_messages()[1].model_name)

写 Agent 最怕的是一上来就接真实模型和真实业务工具。先用测试模型把输入输出、消息历史和异常分支跑稳，后面替换模型会安全很多。

功能二：注册一个带类型的工具

这段代码解决什么问题：把业务函数挂到 Agent 上，同时保留参数类型。工具 schema 会从函数签名里生成，后续模型调用工具时边界更清楚。

importwarningswarnings.filterwarnings('ignore')frompydantic_aiimportAgentfrompydantic_ai.models.testimportTestModelagent=Agent(TestModel(call_tools='all'),system_prompt='你会查询订单状态。')@agent.tool_plaindeforder_status(order_id:str)->str:"""Return a local order status."""return{'A-1001':'paid','A-1002':'review'}.get(order_id,'missing')result=agent.run_sync('查询订单 A-1001')tool=agent._function_toolset.tools['order_status']print('tool name:',tool.name)print('tool params:',', '.join(tool.function_schema.json_schema['properties']))print('manual call:',order_status('A-1001'))print('registered tools:',len(agent._function_toolset.tools))

工具函数要尽量小而明确：参数少、返回稳定、错误可解释。不要让 Agent 直接拿数据库密码或用户隐私拼进 Prompt，凭证和权限仍然要由本地配置或密钥系统管理。

环境与版本信息

Demo 环境：Windows 11，Python 3.11
本文安装的 pydantic-ai 版本：1.92.0
当前包要求 Python：>=3.10
关键依赖版本：pydantic-ai-slim 1.92.0、pydantic-graph 1.92.0
官方定位：GenAI Agent Framework，the Pydantic way

高级功能

这段代码解决什么问题：Agent 最终返回的不应该总是一段自然语言。通过 output_type，可以要求返回 Pydantic 模型，让后续入库、审批和接口调用更稳。

importwarningswarnings.filterwarnings('ignore')frompydanticimportBaseModel,Fieldfrompydantic_aiimportAgentfrompydantic_ai.models.testimportTestModelclassLaunchPlan(BaseModel):title:str=Field(description='计划标题')checks:list[str]=Field(description='上线检查项')agent=Agent(TestModel(custom_output_args={'title':'上线检查','checks':['类型校验','工具权限','日志审计']}),output_type=LaunchPlan,)result=agent.run_sync('返回一份结构化上线计划')plan=result.outputprint('output type:',type(plan).__name__)print('title:',plan.title)print('checks:',', '.join(plan.checks))print('field count:',len(LaunchPlan.model_fields))

这也是它和普通 Pydantic 的区别：Pydantic 负责数据结构，pydantic-ai 则把这种结构约束推进到 Agent 运行过程里。

适用场景

你要写 Agent，并且非常重视类型、结构化输出和测试
工具调用会进入真实业务系统，需要清楚的参数 schema 和结果校验
团队已经熟悉 Pydantic，希望 AI 应用也保持类似开发体验

不适用场景

只是简单调用模型生成文本，不需要 Agent、工具和结构化结果
输出可以完全人工阅读，不进入任何下游系统
团队没有测试和类型约束习惯，只想快速堆 Prompt

上线检查

给关键输出定义 Pydantic 模型，不要把自然语言直接交给下游业务系统。
工具函数要有参数类型、权限边界、错误处理和日志记录。
用 TestModel 覆盖正常、异常和边界输入，再接真实模型。

总结

pydantic-ai 适合把 Agent 做得更可靠。它不是“给 Pydantic 加一点 AI”，而是用 Pydantic 的工程思路去约束 Agent、工具和模型输出，让 AI 应用更容易测试、更容易维护。