OpenAI Agents Python项目中自定义JSON Schema输出的解决方案

背景介绍

在OpenAI Agents Python项目中，开发者经常需要为Agent的输出定义特定的数据结构格式。传统方法是使用Pydantic模型来生成JSON Schema，但这种方法存在一些局限性，特别是在处理复杂数据结构时。

问题分析

开发者在使用过程中遇到了几个典型问题：

1. 多层嵌套引用问题：当数据结构中存在多层$defs引用时，某些第三方LLM模型无法正确解析这种复杂的JSON Schema结构。

2. Optional类型转换问题：Pydantic生成的Schema中包含{"type": "null"}这样的定义，部分模型不支持这种语法。

3. 字典类型限制：Structured Outputs要求所有键都必须预先定义，无法使用完全动态的dict[str, str]这样的类型。

4. 默认值问题：Schema中的默认值设置有时会导致模型解析错误。

解决方案演进

项目维护者提供了几种逐步完善的解决方案：

初始方案：使用dataclass替代Pydantic

开发者可以使用Python标准库中的dataclass来定义输出结构，这比Pydantic模型更加轻量级：

from dataclasses import dataclass

@dataclass
class Output:
    joke: str

进阶方案：处理复杂数据结构

对于更复杂的数据结构，如包含嵌套类和列表的情况：

@dataclass
class OnError:
    error_type: str
    next: str = ""

@dataclass 
class BaseNode:
    on_error: list[OnError] = field(default_factory=list)
    action: Optional[str] = ""

最终方案：非严格Schema模式

项目最新版本引入了output_schema_strict=False参数，允许开发者绕过严格的Schema验证：

agent = Agent(
    name="Assistant",
    output_type=ComplexOutputModel,
    output_schema_strict=False
)

技术实现细节

1. Schema生成机制：项目内部使用TypeAdapter将Python类型转换为JSON Schema，支持dataclass、Pydantic模型等多种类型。

2. Schema优化：通过output_schema_strict参数可以控制是否生成严格模式的Schema，避免某些模型不支持的语法特性。

3. 错误处理：当Schema不符合要求时，会抛出明确的错误信息，帮助开发者快速定位问题。

最佳实践建议

1. 对于简单数据结构，优先使用dataclass定义输出类型。

2. 当遇到模型不支持的特性时，尝试使用output_schema_strict=False选项。

3. 避免在Schema中使用完全动态的字典类型，尽可能明确定义所有字段。

4. 谨慎使用默认值，某些模型可能对默认值的处理存在限制。

总结

OpenAI Agents Python项目通过不断迭代，提供了灵活的输出Schema定义方式，使开发者能够根据实际需求和使用场景选择最适合的方案。理解这些技术细节有助于开发者更高效地构建基于LLM的智能代理应用。