如何使用Pydantic AI构建生产级代理
内容提要
本文探讨了使用原始LLM SDK构建AI代理的六大问题：非结构化输出解析脆弱、工具定义样板代码多、运行时上下文传递困难、测试依赖真实API调用、重试验证逻辑重复、切换模型需重写集成代码。文章以收据分析代理为例，展示Pydantic AI框架如何通过类型化输出、自动工具生成、依赖注入、测试模型、自动重试和模型无关设计解决这些问题，使代理逻辑简洁、可测试且生产可靠。
延伸解读
从原始SDK到框架：核心痛点
文章指出，使用原始LLM SDK构建代理时，开发者常陷入非结构化输出解析、工具定义样板代码、运行时上下文传递、测试依赖真实API、重试逻辑重复、模型切换需重写集成代码等六大问题。这些问题单独看都不难，但累积起来会淹没真正的代理逻辑。Pydantic AI通过类型化输出、自动工具生成、依赖注入、测试模型、自动重试和模型无关设计，将LLM边界转化为声明式契约，显著简化了生产级代理的开发。
类型化输出与自动验证的价值
文章强调，使用Pydantic模型定义输出结构，不仅让LLM返回符合预期的JSON，还通过字段约束（如confidence在0到1之间）和枚举类型（如SpendingCategory）实现真正的验证。相比手动解析和if检查，框架自动处理JSON解析、类型强制转换和验证失败重试，减少了静默错误和脆弱解析代码。这种设计让输出格式成为代码中的单一事实来源，而非提示词中的英文描述。
依赖注入与可测试性
Pydantic AI的依赖注入系统允许工具通过RunContext访问数据库连接、用户ID等运行时依赖，避免了全局变量和闭包的复杂性。测试时，通过TestModel和FunctionModel替换真实LLM，无需网络和API密钥，即可快速、确定性地验证代理逻辑。文章强调，这种设计让测试聚焦于行为而非LLM措辞，同时保持工具代码不变，提升了CI环境的可靠性。
模型切换与生产可靠性
文章指出，Pydantic AI的模型无关设计让切换提供商只需更改模型字符串，无需重写SDK调用、工具格式或响应解析。框架自动将工具定义转换为各提供商的原生格式，并统一响应结构。此外，通过result_validator和ModelRetry，业务规则验证（如总额与明细不符）可自动触发重试，将错误信息反馈给LLM自我修正，减少了手写重试逻辑的重复劳动。
Q&A
使用原始LLM SDK构建AI代理时，主要会遇到哪些问题？
主要问题包括：非结构化输出解析脆弱、工具定义样板代码多、运行时上下文传递困难、测试依赖真实API调用、重试验证逻辑重复、切换模型需重写集成代码。
Pydantic AI如何解决LLM输出解析脆弱的问题？
Pydantic AI允许你定义Pydantic模型作为输出类型，框架自动生成JSON schema、注入到LLM请求中，并解析和验证响应。如果验证失败，会自动重试，无需手动解析JSON或处理格式问题。
在Pydantic AI中，如何定义工具？与原始SDK相比有什么优势？
在Pydantic AI中，工具是通过在函数上添加@agent.tool_plain装饰器定义的，框架从函数签名和docstring自动生成JSON schema，并自动调度。相比原始SDK需要手写约70行JSON schema和调度代码，Pydantic AI只需约25行，且保持同步。
Pydantic AI如何实现依赖注入？
Pydantic AI通过deps_type定义依赖类型，工具函数接收RunContext参数，通过ctx.deps访问依赖。在运行agent时，通过deps参数传入具体依赖实例，如数据库连接、用户ID等。这样避免了全局变量和闭包，便于测试和并发。
如何在不调用真实LLM的情况下测试Pydantic AI代理？
Pydantic AI提供了TestModel和FunctionModel。TestModel自动生成符合schema的响应，FunctionModel允许你模拟特定行为。通过override方法替换模型，测试无需网络和API密钥，运行快速且确定性高。
Pydantic AI如何处理重试和验证？
Pydantic AI通过Pydantic模型进行schema验证，并通过result_validator装饰器添加业务规则验证。如果验证失败，可以抛出ModelRetry异常，框架会自动将错误信息反馈给LLM并重试，重试次数由retries参数控制。
Pydantic AI如何实现模型无关性？
Pydantic AI的agent定义与模型无关，只需更改模型字符串标识符，如从'openai:gpt-4o'改为'anthropic:claude-sonnet-4-20250514'，框架会自动处理不同提供商的工具格式和响应解析，无需修改其他代码。
