[BOT ISSUE] OpenAI Responses API instrumentation uses wrong token-limit parameter name and is missing several metadata fields

[braintrust-bot]

Summary

The Responses API instrumentation in both the openai and ruby-openai integrations has an incorrect parameter name (max_tokens instead of max_output_tokens) and is missing several parameters that are part of the stable upstream API. Users who set max_output_tokens, service_tier, include, text, or background on their Responses API calls get no visibility into these values in their Braintrust span metadata.

What is missing

The METADATA_FIELDS constant in both Responses API instrumentations currently includes:

METADATA_FIELDS = %i[
  model instructions modalities tools parallel_tool_calls
  tool_choice temperature max_tokens top_p frequency_penalty
  presence_penalty seed user metadata store response_format
  reasoning previous_response_id truncation
].freeze

Wrong parameter name

Current field	Correct field	Why it matters
max_tokens	max_output_tokens	The Responses API uses max_output_tokens, not max_tokens. The SDK captures a field that doesn't exist in the Responses API, and misses the one users actually pass.

Missing parameters

Parameter	Why it matters
service_tier	Controls processing priority (auto, default, flex, priority). Already captured in the Chat Completions instrumentation — this is an inconsistency within the SDK.
include	Array controlling what additional data is returned (e.g., web_search_call.action.sources, code_interpreter_call.outputs). Important for understanding what data the user requested.
text	Text response format configuration for structured outputs. The newer alternative to response_format for the Responses API.
background	Boolean for async/background response execution. Changes how the response is processed — users need to see this in traces to understand response behavior.

Braintrust docs status

not_found — The Braintrust docs at https://www.braintrust.dev/docs/instrument/wrap-providers do not mention max_output_tokens, service_tier, include, text, or background for the Responses API.

Upstream sources

• Official OpenAI Ruby SDK: https://github.com/openai/openai-ruby — OpenAI::Models::Responses::ResponseCreateParams defines max_output_tokens (not max_tokens), service_tier, include, text, background, and other parameters in lib/openai/models/responses/response_create_params.rb
• OpenAI Responses API docs: https://platform.openai.com/docs/api-reference/responses/create — documents all parameters

Local repo files inspected

• lib/braintrust/contrib/openai/instrumentation/responses.rb (lines 26–31) — METADATA_FIELDS uses max_tokens (wrong) and is missing max_output_tokens, service_tier, include, text, background
• lib/braintrust/contrib/ruby_openai/instrumentation/responses.rb (lines 32–37) — identical METADATA_FIELDS, same issues
• lib/braintrust/contrib/openai/instrumentation/chat.rb (lines 27–32) — Chat Completions already captures service_tier, showing this is an oversight in the Responses instrumentation

[starfolkai]

Drop into this session: sfk devbox session 75

---

Summary

Issue #145 — OpenAI Responses API instrumentation uses wrong token-limit parameter name and is missing several metadata fields

Root Cause Confirmed — Code reading + real execution.

Both METADATA_FIELDS constants in:

• lib/braintrust/contrib/openai/instrumentation/responses.rb:26-31
• lib/braintrust/contrib/ruby_openai/instrumentation/responses.rb:32-37

had two distinct bugs:

Problem	Before	After
Wrong parameter name	:max_tokens	:max_output_tokens
Missing service_tier	absent	present
Missing include	absent	present
Missing text	absent	present
Missing background	absent	present

The Responses API uses max_output_tokens, not max_tokens (which is Chat Completions). The 4 missing fields were already tracked in Chat Completions (service_tier) or are part of the stable Responses API spec (include, text, background).

Test Results

Before fix:

openai responses_test:   18 runs, 5 failures, 0 errors
ruby_openai responses_test: 13 runs, 5 failures, 0 errors

After fix:

openai responses_test:   18 runs, 0 failures, 0 errors
ruby_openai responses_test: 13 runs, 0 failures, 0 errors

Artifacts

• 10 new failing→passing unit tests added (5 per test file), no E2E / mocking required
• 2 source files patched — identical change in both: swap max_tokens → max_output_tokens, add service_tier, include, text, background
• Real code executed against loaded modules; METADATA_FIELDS content verified directly