OpenAI SDK v3.37.0 Released: Breaking Changes to Decisions Types

Core Changes in OpenAI SDK v3.37.0

The official OpenAI SDK repository (openai-sdks) has released version v3.37.0. Although the version number is only a minor increment, this release is explicitly flagged as containing a breaking change, with the impact concentrated on the Decisions types of the Live API.

According to the changelog, this release includes 1 feature update and 4 maintenance items: at the feature level, the Decisions input and question types were extended; at the maintenance level, changes involve the file/video polling helper methods, upload helper methods, Live connection defaults, and a version bump of the astral-sh/setup-uv dependency.

What Exactly Changed in the Breaking Change

According to the release notes, in the Live response model, the instructions field of a question can now be a string or a list composed of structured text, image, or JSON fragments. This means that code which previously performed string operations directly on instructions (such as concatenation, slicing, or regex matching) may encounter type errors in the new version. The recommended approach is to first check the type via isinstance(question.instructions, str) before performing string operations, and handle the structured form separately.

This change reflects that multimodal interaction is becoming the norm in Live scenarios—user instructions are no longer just plain text but may carry images, structured JSON, and other content. The SDK's type system needs to be relaxed accordingly to accommodate richer input forms.

Structured text, image, or JSON fragments are typically modeled in the SDK type system as "content blocks": each block has a type field (such as text, image, or json), image blocks carry base64 data or a URL, and text blocks carry plain text. This design originates from the message format conventions of multimodal models, with the goal of allowing a single instruction to mix multiple modalities without having to split it into multiple messages. For developers, the key difference is that a string is an immutable contiguous sequence that can be sliced and regex-matched directly, whereas a block list is a structured object that requires iteration, dispatch by type, and behaves differently in serialization and logging. Therefore, type checking must precede any string operations.

Tool-history items refer to the call records and return results produced after the model invokes tools (function calls, retrieval, etc.) during a conversation. They are passed back to the model as part of the input messages to maintain context for multi-turn tool calls. The addition of new history item types means the model can receive richer tool interaction traces (for example, parallel calls, results with structured parameters), but it also requires developers to add new branches when performing exhaustive role/type checks; otherwise, new items will be silently ignored or fall into the default branch.

Knock-on Effects of the Input Type Extension

In addition to the instructions field, the Decisions request input types also add additional message roles and tool-history items. This means that when developers write exhaustive type checks (for example, switch/if-else branches over message roles), they need to update the branch logic accordingly; otherwise, new roles or new history items may be missed, causing runtime behavior to deviate from expectations.

The good news is that compatibility is not fully broken: the existing string form of instructions and the user message input in DecisionInputMessageParam remain supported. For existing projects that do not use structured instructions, the upgrade risk is relatively manageable.

Maintenance Changes and Dependency Upgrades

The chore items in this release mainly "preserve" existing capabilities: preserving the file and video polling helper methods, preserving the upload helper methods and the Live connection defaults. Such changes usually appear during refactoring or type adjustments, with the goal of ensuring that helper utilities remain available after core type changes.

On the dependency side, astral-sh/setup-uv was upgraded from 10.2.0 to 10.3.0, which is a routine CI toolchain update with no direct impact on business code.

Upgrade Recommendations

For projects using the Live API and Decisions types, it is recommended to do three things before upgrading: first, globally search for string operations on question.instructions; second, check all exhaustive checks on Decisions input message roles; third, add test cases for structured instructions. If the project does not currently involve multimodal instructions, you can also pin the current version first and follow up after the official migration documentation is expanded.

Key Takeaways

• v3.37.0 is a minor version with breaking changes affecting the Decisions types of the Live response model
• question.instructions is expanded from a plain string to a string or a list of structured fragments
• Decisions input adds new message roles and tool-history items; exhaustive type checks need to be updated accordingly
• String instructions and DecisionInputMessageParam user message input remain backward compatible
• The dependency upgrade is routine CI toolchain maintenance with no direct impact on business code

One-line Summary

OpenAI SDK v3.37.0 is a minor version containing breaking changes affecting the Live API's Decisions types.

Paragraph Summary

The official OpenAI SDK has released v3.37.0. Although it is a minor version increment, it is explicitly flagged as a breaking change, with the impact concentrated on the Live API's Decisions types. The core change is that question.instructions is expanded from a plain string to a string or a list composed of structured text, image, and JSON fragments. Code that directly performs string operations may raise type errors, and the official recommendation is to check with isinstance first. Decisions request input also adds new message roles and tool-history items, so exhaustive type checks need to be updated accordingly. In terms of compatibility, the string form of instructions and DecisionInputMessageParam user message input remain supported, so projects that do not use structured instructions face manageable upgrade risk. The rest consists of maintenance work such as preserving helper methods and upgrading astral-sh/setup-uv, with no direct impact on business code. The author recommends searching for string operations, checking exhaustive role checks, and adding structured instruction tests before upgrading.