OpenAI Agents Python项目中嵌套对象参数传递问题的解决方案

在OpenAI Agents Python项目的实际开发中，开发者可能会遇到一个典型问题：当使用Pydantic模型定义嵌套数据结构时，嵌套的数组或对象在函数工具调用时出现空值情况。这个问题看似简单，但涉及到模型定义、参数传递和提示工程等多个技术环节。

问题现象分析

开发者通常会定义类似如下的数据结构模型：

class Exercise(BaseModel):
    ...

class Workout(BaseModel):
    exercises: List[Exercise]

class TrainingProgram(BaseModel):
    workouts: List[Workout]

当这些模型作为函数工具的输入参数时，嵌套的workouts列表经常出现空值情况，即使模型的其他字段如daysPerWeek和notes能够正确填充。更奇怪的是，当数据被传递给其他代理时，虽然函数调用中显示为空，但代理却能够正确显示完整数据。

根本原因探究

这种现象的根本原因在于模型对参数完整性的理解不足。大语言模型（如GPT-4.1）在处理复杂嵌套结构时，可能会认为某些字段是可选的，或者在没有明确指示的情况下选择性地忽略部分数据。

解决方案：提示工程优化

通过为模型类和函数工具添加详细的描述信息，可以显著改善这种情况：

1. 为每个模型类添加文档字符串：

class Exercise(BaseModel):
    """单个训练项目，包含..."""
    ...

class Workout(BaseModel):
    """一次训练课程，包含多个训练项目"""
    exercises: List[Exercise] = Field(..., description="训练项目列表。不要传递空列表，必须包含所有已知的训练项目")

2. 为函数工具添加详细说明：

@function_tool
async def create_training_program(wrapper: RunContextWrapper[ChatContext], training_program: TrainingProgram):
    """创建训练计划。必须传递完整的训练计划，包含所有参数"""

技术原理

这种解决方案有效的技术原理在于：

1. 文档字符串会被传递给语言模型，成为其理解参数要求的重要上下文
2. 明确的指令（如"不要传递空列表"）可以覆盖模型的默认行为
3. 详细的字段描述能帮助模型更好地理解数据结构关系

最佳实践建议

1. 对于复杂嵌套结构，始终为每个模型和字段添加描述性文档
2. 在函数工具描述中明确参数完整性要求
3. 对于关键字段，使用Field的description参数提供额外说明
4. 测试时注意验证嵌套结构的完整性，而不仅仅是顶层字段

通过这种提示工程的方法，开发者可以确保复杂数据结构在函数工具调用时能够完整传递，避免数据丢失的问题。这种方法不仅适用于训练计划场景，也可以推广到其他需要处理复杂嵌套数据的应用场景中。