Pydantic-AI 项目中 datetime 参数严格模式兼容性问题解析

在 Pydantic-AI 项目的最新版本迭代中，开发者发现了一个关于 datetime 类型参数在严格模式下的兼容性回归问题。这个问题从 0.0.53 版本开始出现，影响了使用 datetime 作为工具函数参数的用户体验。

问题现象

当开发者使用 @agent.tool 装饰器定义一个包含 datetime 类型参数的工具函数时，在 0.0.52 版本中可以正常工作：

@agent.tool
def get_all_infos(ctx: RunContext, today: datetime) -> str:
    out = f"TODAY: {today}"
    print(out)
    return out

但在 0.0.53 及更高版本中，同样的代码会抛出 ModelHTTPError 异常，错误信息明确指出 'format' 属性在严格模式下不被允许。

技术背景

这个问题源于 OpenAI API 对 JSON Schema 的严格模式支持限制。在严格模式下，OpenAI 的 API 不接受某些额外的模式属性，包括 datetime 类型自动转换时添加的 'format' 属性。Pydantic-AI 在 0.0.53 版本中引入了更严格的模式验证，导致这个兼容性问题显现出来。

临时解决方案

目前开发者可以采用以下两种临时解决方案：

1. 在 @tool 装饰器中显式设置 strict=False 参数
2. 避免直接使用 datetime 类型作为参数，改用其他类型表示日期时间

深层原因分析

这个问题实际上反映了 Pydantic-AI 在严格模式兼容性判断逻辑上的不足。项目团队已经意识到需要改进对 OpenAI API 文档中明确指出的不兼容特性的预处理，同时也需要处理那些未在文档中明确说明的限制。

项目进展

Pydantic-AI 团队已经将这个问题与另一个相关的严格模式问题合并跟踪，计划在未来的版本中统一解决。解决方案将包括：

1. 预处理已知的 OpenAI API 不兼容特性
2. 增强对严格模式兼容性的自动检测
3. 提供更清晰的错误提示

最佳实践建议

对于当前版本的用户，建议：

1. 仔细检查工具函数中使用的参数类型
2. 对于日期时间参数，考虑使用字符串类型并手动处理转换
3. 关注项目更新，及时升级到包含修复的版本

这个问题虽然看起来是一个简单的兼容性问题，但实际上涉及到 API 设计、类型系统和严格模式验证等多个技术层面的考量，值得开发者深入理解。