Pydantic AI 中 NonRecordingSpan 序列化问题的分析与解决

问题背景

在 Pydantic AI 项目的最新版本(0.1.2)中，部分开发者遇到了一个与 OpenTelemetry 相关的序列化错误。当尝试序列化 OpenTelemetry 的 NonRecordingSpan 类型时，系统会抛出 PydanticSerializationError: Unable to serialize unknown type: <class 'opentelemetry.trace.span.NonRecordingSpan'> 异常。

问题根源分析

经过技术团队深入调查，发现该问题主要出现在以下场景：

1. 当开发者使用工具(Tool)调用代理(Agent)运行时
2. 直接返回了完整的 AgentRunResult 对象而非其输出内容
3. 系统尝试序列化整个运行结果对象时，包含了不应被序列化的 OpenTelemetry 跟踪信息

解决方案

正确的做法应该是只返回代理运行的输出内容，而非整个运行结果对象。以下是修正前后的代码对比：

错误写法：

return await agent.run(...)

正确写法：

result = await agent.run(...)
return result.output

技术原理

这个问题的本质在于 Pydantic 的序列化机制。当系统尝试序列化一个包含 OpenTelemetry Span 的复杂对象时：

1. Pydantic 会递归地尝试序列化对象的所有属性
2. 遇到 OpenTelemetry 的 NonRecordingSpan 类型时，由于这不是一个 Pydantic 已知的可序列化类型
3. 系统无法找到合适的序列化器，因此抛出异常

最佳实践建议

1. 明确返回类型：工具(Tool)应该始终返回明确的数据类型，而非复杂的框架对象
2. 数据最小化：只返回LLM真正需要处理的数据，避免传递内部状态信息
3. 类型检查：在开发阶段可以使用类型提示来确保返回值的正确性
4. 版本兼容性：注意不同版本间的行为差异，及时更新使用方式

总结

这个问题虽然表现为序列化错误，但本质上是一个API使用规范问题。Pydantic AI 框架在后续版本中可能会对此类用法进行更严格的检查或提供更友好的错误提示。开发者应当遵循框架设计的最佳实践，只返回必要的业务数据，避免传递框架内部对象。