Pydantic AI 项目中 OpenTelemetry 序列化问题的分析与解决

问题背景

在使用 Pydantic AI 框架构建 AI 辅助系统时，开发者遇到了一个关于 OpenTelemetry 跟踪 span 序列化的技术难题。当尝试通过 agent.iter() 方法流式处理最终输出时，系统抛出了 PydanticSerializationError 异常，提示无法序列化 opentelemetry.trace.span.NonRecordingSpan 类型。

问题现象

在流式处理辅助工作流的最终节点输出时，系统尝试将结果转换为字符串形式，但在序列化过程中失败。错误堆栈显示，问题源于 OpenTelemetry 的非记录型 span 对象无法被 Pydantic 的序列化器正确处理。

技术分析

根本原因

1. 序列化机制冲突：Pydantic 的序列化器无法识别 OpenTelemetry 的 NonRecordingSpan 类型
2. 辅助运行结果处理不当：工具函数直接返回了完整的 AgentRunResult 对象，而非仅返回所需的输出内容
3. 流式处理特殊性：问题仅在流式处理场景下出现，常规非流式调用可正常工作

架构层面影响

这个问题暴露了 Pydantic AI 框架在以下方面的设计考量：

1. 组件间通信协议：辅助工具间的数据交换应遵循最小化原则
2. 序列化边界：需要明确哪些内部状态应该暴露给序列化过程
3. 观测性集成：如何平衡功能需求与可观测性需求的实现

解决方案

推荐实践

根据项目维护者的建议，正确的工具函数实现方式应为：

async def example_tool(self, input):
    result = await self.agent.run(input)
    return result.output  # 仅返回输出内容，而非整个结果对象

技术要点

1. 数据最小化原则：工具函数应只返回业务逻辑需要的输出数据
2. 类型安全：确保返回的数据结构可以被 Pydantic 正确序列化
3. 明确接口契约：工具函数的返回类型应该与其文档声明严格一致

最佳实践建议

1. 工具函数设计：

   • 始终明确声明返回类型
   • 避免返回包含框架内部状态的复合对象
   • 优先使用基本类型或简单的 Pydantic 模型

2. 错误处理：

   • 对工具函数的返回值进行类型检查
   • 考虑添加序列化验证步骤
   • 实现适当的错误处理机制

3. 可观测性集成：

   • 明确区分业务数据与观测数据
   • 考虑使用专门的字段携带跟踪信息
   • 避免观测性数据污染业务数据流

总结

这个案例展示了在构建复杂 AI 辅助系统时，正确处理数据序列化边界的重要性。通过遵循最小化返回原则和明确的接口契约，开发者可以避免类似的序列化问题，同时提高系统的稳定性和可维护性。Pydantic AI 框架通过这个问题的解决，进一步明确了工具函数的设计规范，为开发者提供了更清晰的指导。