升级指南
在2025年9月，Pydantic AI 达到了 V1 版本，这意味着我们承诺保持 API 的稳定性：直到 V2 版本，我们不会引入会破坏您代码的变更（如果我们这样做了，您可以尽管指责我们，因为这绝对是个错误）。一旦我们发布 V2（最早在2026年4月），我们将继续为 V1 提供至少6个月的安全修复，以便您有时间升级您的应用程序。
重大变更
这里是每个版本的重大变更筛选列表，以帮助您升级 Pydantic AI。
v1.0.0 (2025-09-04)
- 请参阅 #2725 - 放弃对 Python 3.9 的支持
- 请参阅 #2738 - 使许多数据类（dataclass）需要关键字参数
- 请参阅 #2715 - 从
pydantic_evalsspans 中移除cases和averages属性 - 请参阅 #2798 - 将
ModelRequest.parts和ModelResponse.parts的类型从list更改为Sequence - 请参阅 #2726 - 将
InstrumentationSettings的默认版本设置为 2 - 请参阅 #2717 - 移除了当向
AsyncTenacityTransport或TenacityTransport传递AsyncRetrying或Retrying对象而非RetryConfig时产生的错误
v0.x.x
在 V1 之前，次要版本曾被用来引入重大变更
v0.8.0 (2025-08-26)
请参阅 #2689 - AgentStreamEvent 被扩展为 ModelResponseStreamEvent 和 HandleResponseEvent 的联合类型，简化了 event_stream_handler 函数的签名。现有接受 AgentStreamEvent | HandleResponseEvent 的代码将继续工作。
v0.7.6 (2025-08-26)
以下重大变更被无意中发布在一个补丁版本中，而非次要版本
请参阅 #2670 - TenacityTransport 和 AsyncTenacityTransport 现在要求使用 pydantic_ai.retries.RetryConfig（它只是一个包含传递给 tenacity.retry 的关键字参数的 TypedDict），而不是 tenacity.Retrying 或 tenacity.AsyncRetrying。
v0.7.0 (2025-08-12)
请参阅 #2458 - pydantic_ai.models.StreamedResponse 现在会随现有的 PartStartEvent 和 PartDeltaEvent 一起产生一个 FinalResultEvent。如果您正在使用 pydantic_ai.direct.model_request_stream 或 pydantic_ai.direct.model_request_stream_sync，您可能需要更新您的代码以适应此变更。
请参阅 #2458 - pydantic_ai.models.Model.request_stream 现在接收一个 run_context 参数。如果您实现了自定义的 Model 子类，您需要考虑此变更。
请参阅 #2458 - pydantic_ai.models.StreamedResponse 现在需要一个 model_request_parameters 字段和构造函数参数。如果您实现了自定义的 Model 子类并实现了 request_stream，您需要考虑此变更。
v0.6.0 (2025-08-06)
此版本旨在清理一些旧的已弃用代码，以便我们能更接近 V1。
请参阅 #2440 - 从 Graph 类中移除了 next 方法。请改用 async with graph.iter(...) as run: run.next()。
请参阅 #2441 - 从 Agent 类中移除了 result_type、result_tool_name 和 result_tool_description 参数。请改用 output_type。
请参阅 #2441 - result_retries 参数也从 Agent 类中移除。请改用 output_retries。
请参阅 #2443 - 从 FinalResult 类中移除了 data 属性。请改用 output。
请参阅 #2445 - 从 StreamedRunResult 类中移除了 get_data 和 validate_structured_result 方法。请改用 get_output 和 validate_structured_output。
请参阅 #2446 - format_as_xml 函数已移至 pydantic_ai.format_as_xml 模块。请改用 from pydantic_ai import format_as_xml 导入。
请参阅 #2451 - 移除了已弃用的 Agent.result_validator 方法、Agent.last_run_messages 属性、AgentRunResult.data 属性以及结果类中的 result_tool_return_content 参数。
v0.5.0 (2025-08-04)
请参阅 #2388 - EvaluationResult 的 source 字段现在是 EvaluatorSpec 类型，而不是实际的源 Evaluator 实例，以帮助序列化/反序列化。
请参阅 #2163 - EvaluationReport.print 和 EvaluationReport.console_table 方法现在要求大多数参数通过关键字传递。
v0.4.0 (2025-07-08)
请参阅 #1799 - Pydantic Evals 的 EvaluationReport 和 ReportCase 现在是泛型数据类（generic dataclasses），而不是 Pydantic 模型。如果您之前使用 model_dump() 对它们进行序列化，现在需要改用 EvaluationReportAdapter 和 ReportCaseAdapter 类型适配器。
请参阅 #1507 - ToolDefinition 的 description 参数现在是可选的，并且位置参数的顺序已从 name, description, parameters_json_schema, ... 更改为 name, parameters_json_schema, description, ... 以适应此变更。
v0.3.0 (2025-06-18)
请参阅 #1142 — 增加对思考部分（thinking parts）的支持。
我们现在将特定于提供商的文本部分中的思考块（"<think>..."</think>"）转换为 Pydantic AI 的 ThinkingPart。此外，作为此版本的一部分，我们决定不将 ThinkingPart 发回给提供商——其目的是为用户节省成本。未来，我们打算增加一个设置来定制此行为。
v0.2.0 (2025-05-12)
请参阅 #1647 — usage 作为 ModelResponse 的一部分更有意义，并且在“消息”（实际上是请求和响应的序列）中可能非常有用。在此 PR 中：
- 向
ModelResponse添加usage（该字段有一个默认工厂Usage()，因此加载不含 usage 的数据时也能正常工作） - 将
Model.request的返回类型从tuple[ModelResponse, Usage]更改为仅ModelResponse
v0.1.0 (2025-04-15)
请参阅 #1248 — 属性/参数名称 result 在多处被重命名为 output。希望所有的变更都保留了使用旧名称的已弃用属性或参数，因此您应该会收到许多弃用警告。
请参阅 #1484 — format_as_xml 被移动并可以从包的根目录导入，例如 from pydantic_ai import format_as_xml。