docs/release.md
The project follows a slightly modified version of semantic versioning using the form 0.Y.Z. The leading 0 indicates the SDK is still evolving rapidly. Increment the components as follows:
Y) versionsWe will increase minor versions Y for breaking changes to any public interfaces that are not marked as beta. For example, going from 0.0.x to 0.1.x might include breaking changes.
If you don't want breaking changes, we recommend pinning to 0.0.x versions in your project.
Z) versionsWe will increment Z for non-breaking changes:
In this version, model refusals are now surfaced explicitly as ModelRefusalError instead of being treated as empty text output or, for structured outputs, causing the run loop to retry until MaxTurnsExceeded.
This affects code that previously expected a refusal-only model response to complete with final_output == "". To handle refusals without raising, provide a model_refusal run error handler:
result = Runner.run_sync(
agent,
input,
error_handlers={"model_refusal": lambda data: data.error.refusal},
)
For structured-output agents, the handler can return a value matching the agent's output schema, and the SDK will validate it like other run error handler final outputs.
This minor release does not introduce a breaking change, but it adds a major new beta feature area: Sandbox Agents, plus the runtime, backend, and documentation support needed to use them across local, containerized, and hosted environments.
Highlights:
SandboxAgent, Manifest, and SandboxRunConfig, letting agents work inside persistent isolated workspaces with files, directories, Git repos, mounts, snapshots, and resume support.UnixLocalSandboxClient and DockerSandboxClient, plus hosted provider integrations for Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel through optional extras.RunState, SandboxSessionState, or saved snapshots.examples/sandbox/, covering coding tasks with skills, handoffs, memory, provider-specific setups, and end-to-end workflows such as code review, dataroom QA, and website cloning.This minor release does not introduce a breaking change, but it includes a notable Realtime default update plus new MCP capabilities and runtime stability fixes.
Highlights:
gpt-realtime-1.5, so new Realtime agent setups use the newer model without extra configuration.MCPServer now exposes list_resources(), list_resource_templates(), and read_resource(), and MCPServerStreamableHttp now exposes session_id so streamable HTTP sessions can be resumed across reconnects or stateless workers.should_replay_reasoning_content, improving provider-specific reasoning/tool-call continuity for adapters such as LiteLLM/DeepSeek.SQLAlchemySession, compaction requests with orphaned assistant message IDs after reasoning stripping, remove_all_tools() leaving MCP/reasoning items behind, and a race in the function-tool batch executor.This minor release does not introduce a breaking change. Check the release notes for major feature additions.
This minor release does not introduce a breaking change. Check the release notes for major feature additions.
This minor release does not introduce a breaking change, but it includes a significant new feature area for OpenAI Responses users: websocket transport support for the Responses API.
Highlights:
responses_websocket_session() helper / ResponsesWebSocketSession for reusing a shared websocket-capable provider and RunConfig across multi-turn runs.examples/basic/stream_ws.py) covering streaming, tools, approvals, and follow-up turns.In this version, Python 3.9 is no longer supported, as this major version reached EOL three months ago. Please upgrade to a newer runtime version.
Additionally, the type hint for the value returned from the Agent#as_tool() method has been narrowed from Tool to FunctionTool. This change should not usually cause breaking issues, but if your code relies on the broader union type, you may need to make some adjustments on your side.
In this version, two runtime behavior changes may require migration work:
asyncio.to_thread(...) instead of running on the event loop thread. If your tool logic depends on thread-local state or thread-affine resources, migrate to an async tool implementation or make thread affinity explicit in your tool code.mcp_config={"failure_error_function": None}. Server-level failure_error_function values override the agent-level setting, so set failure_error_function=None on each local MCP server that has an explicit handler.In this version, there were a few behavior changes that can affect existing applications:
RunConfig(nest_handoff_history=True).reasoning.effort for gpt-5.1 / gpt-5.2 changed to "none" (from the previous default "low" configured by SDK defaults). If your prompts or quality/cost profile relied on "low", set it explicitly in model_settings.In this version, the default handoff history is now packaged into a single assistant message instead of exposing the raw user/assistant turns, giving downstream agents a concise, predictable recap
<CONVERSATION HISTORY> block, so downstream agents get a clearly labeled recapThis version doesn’t introduce any visible breaking changes, but it includes new features and a few significant updates under the hood:
RealtimeRunner to handle SIP protocol connectionsRunner#run_sync for Python 3.14 compatibilityIn this version, openai package v1.x versions are no longer supported. Please use openai v2.x along with this SDK.
In this version, the Realtime API support migrates to gpt-realtime model and its API interface (GA version).
In this version, a few places that used to take Agent as an arg, now take AgentBase as an arg instead. For example, the list_tools() call in MCP servers. This is a purely typing change, you will still receive Agent objects. To update, just fix type errors by replacing Agent with AgentBase.
In this version, [MCPServer.list_tools()][agents.mcp.server.MCPServer] has two new params: run_context and agent. You'll need to add these params to any classes that subclass MCPServer.