
bug: instructions parameter (OpenAI Responses API) not captured/displayed properly
快速结论:该报错出现在使用 OpenAI Responses API 并通过 Langfuse 进行追踪时,`instructions` 参数无法被正确捕获或在前端显示。优先排查 Langfuse Python SDK 版本是否为 4.9.1 或更高。
问题场景
用户在 Langfuse 中通过以下两种方式使用 OpenAI Responses API 时触发:
- 通过 Pydantic AI agent 调用时,使用 `Agent.instrument_all()` 进行 OpenTelemetry 埋点,生成的 span 中包含两个 generation,但 `instructions` 参数显示不完整或在 UI 中渲染异常。
- 直接通过 Langfuse 封装的 OpenAI 客户端调用 `client.responses.create()` 时,`instructions` 参数在 trace 中完全不显示。
报错原文
No explicit error message, but observed behavioral issues:
1. langfuse's automatic generation (via @observe()) does not contain instructions
2. When enabling open-telemetry instrumentation (via Agent.instrument_all()), instructions appear in gen_ai.system_instructions metadata but do not render input, output, or instructions nicely
3. When directly calling the langfuse wrapped openai client, instructions shows up nowhere in the trace
原因分析
可能原因:该问题是由于 Langfuse Python SDK 对 OpenAI Responses API 中新增的 `instructions` 参数支持不完整导致的。在 issue 讨论中,此问题被标记为重复/相关 issue(#8763, #7435),最终确认在 SDK 4.9.1 版本中已修复。低于此版本的 SDK 无法正确解析或传递 `instructions` 参数到生成 spans 中。
环境排查
- Langfuse Python SDK 版本:需确认版本号是否 >= 4.9.1(原始环境为 3.6.1)。
- pydantic-ai 版本:原始环境为 1.0.17,可尝试保持或更新。
- openai 版本:原始环境为 2.1.0。
- Langfuse 后端版本:原始环境为自部署 3.116.1,另有用户报告在 Cloud v3.123.1 上同样存在问题。
解决步骤
- 升级 Langfuse Python SDK 至 4.9.1 或更高版本(原始环境为 3.6.1)。
- 升级后重新运行原有代码,检查 `instructions` 参数是否在 UI 中正常显示。
- 如果仍存在问题,请确认 OpenTelemetry 埋点方式是否与 SDK 版本兼容,例如确保 `Agent.instrument_all()` 调用顺序正确。
- 如果使用的是直接调用方式(`client.responses.create(instructions=…)`),升级后应能自动捕获 instructions。
验证方法
在升级 SDK 后,运行原始示例代码(直接调用方式或 Pydantic AI agent),在 Langfuse UI 中检查对应 trace 的 generation 是否包含 `instructions` 参数,并且输入和输出是否正常渲染。如果问题已修复,应该能看到完整的 `instructions` 内容显示于正确的字段中。



