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:
Version 0.20.0 includes a potentially breaking MCP dependency migration for applications that customize local MCP HTTP transports. It also updates the SDK default model used when an agent or run does not explicitly select one.
Highlights:
gpt-5.6-luna instead of gpt-5.4-mini. The default reasoning.effort="none" and verbosity="low" settings are unchanged.OPENAI_DEFAULT_MODEL environment variable continue to take precedence over the SDK default.gpt-transcribe, gpt-live-transcribe, and gpt-realtime-whisper. For low-latency gpt-live-transcribe sessions, nested audio.input.transcription settings can supply prompt, keywords, and multiple expected languages. The OpenAI client version pinned by this SDK supports the delay latency/accuracy level only with gpt-realtime-whisper. Use gpt-transcribe over WebSocket for transcription after a committed audio turn or for detected-language output. Setting audio.input.turn_detection=None explicitly disables automatic turn detection. See Input transcription settings.mcp>=1.19.0,<3. The Agents SDK adapts ordinary stdio, SSE, and Streamable HTTP connections automatically. With MCP v2 installed, these connections use mcp.Client(mode="auto") to probe the newest supported protocol and fall back to the legacy initialize handshake for older servers. If dependency resolution selects MCP v2, applications that supply custom httpx.Auth objects or httpx.AsyncClient factories must migrate those values to httpx2, or pin mcp<2 to retain the v1 HTTP stack. MCPServerStreamableHttp's params["ignore_initialized_notification_failure"] = True option also remains v1-only. See MCP Python SDK v1 and v2 for migration details.MountConfigError can also retain an SDK-generated safe validation message. Otherwise, the SDK returns a fresh generic redacted error. Provider-controlled or otherwise unapproved messages, command data, notes, context, causes, and source traceback state are not retained. See Mounts and remote storage and Resume from session state.RetryDecision(approve_unsafe_replay=True) for a non-streaming request that the provider marked unsafe. This approval does not bypass aborts, emitted streamed output, or separate local-side-effect vetoes such as Programmatic Tool Calling. See Runner-managed retries.RunState objects can now stage durable user input with add_input() before the next model call. Staged input survives serialization, runs through input guardrails, and produces one durable SDK input occurrence across local sessions and server-managed conversations. An explicitly approved unsafe replay can still resend the input to the provider and repeat provider-side work. See Add input before resuming.FunctionTool subclasses during copying and namespacing, and raise an explicit error for unsupported Chat Completions audio output instead of silently completing an empty stream. The OpenAIResponsesCompactionSession wrapper attempts and awaits pre-compaction history recovery before cancellation reaches the caller. A VoicePipeline consumer now receives transcription-session close failures after a clean run, while an earlier turn failure retains precedence over a later close failure. RunState round trips now preserve local shell output, acknowledged computer safety checks, default-valued tool output fields, and Pydantic model or dataclass outputs encountered while traversing dictionaries, lists, or tuples. MCP conversion preserves free-form object schemas and image output, and serializes other raw content blocks such as audio and resource blocks as valid JSON text. MCPServerManager serializes overlapping lifecycle operations and applies finite default timeouts to connection and cleanup. Model replay removes server-owned created_by metadata from output items before using them as input.This minor release does not introduce a breaking change. The minor version bump reflects a significant new OpenAI Responses feature area: Programmatic Tool Calling.
Highlights:
ProgrammaticToolCallingTool][agents.tool.ProgrammaticToolCallingTool], which lets supported OpenAI Responses models generate JavaScript to coordinate tools eligible for Programmatic Tool Calling. It supports per-tool allowed_callers, structured outputs from FunctionTool instances, and integration with Runner streaming, guardrails, approvals, sessions, and RunState. See Programmatic Tool Calling for setup and constraints.agents.decorators module and @tool as a shorter alias for the existing @function_tool decorator, alongside the existing guardrail decorators. FunctionTool instances now also support async callable objects.VercelCloudBucketMountStrategy. Mounted sessions exclude bucket contents from workspace persistence and intentionally do not support dynamic mount changes or session resume.This minor release does not introduce a breaking change. The minor version bump is for the Realtime agents default model update only.
Highlights:
gpt-realtime-2.1 as the default model, so new Realtime setups use the latest recommended model without extra configuration.In this version, sandbox local source materialization keeps LocalFile.src and LocalDir.src within the materialization base_dir unless the source path is covered by Manifest.extra_path_grants. The base_dir is the SDK process current working directory when the manifest is applied; relative local sources are resolved from that directory, while absolute local sources must already be inside it or under an explicit grant. This closes a local artifact boundary issue, but it can affect applications that intentionally copy trusted host files or directories from outside that base directory into a sandbox workspace.
To migrate, grant trusted host roots at the manifest level with SandboxPathGrant, preferably as read-only when the sandbox only needs to read those files:
from pathlib import Path
from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir
# This is an absolute host path outside the SDK process base_dir.
TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")
manifest = Manifest(
extra_path_grants=(
# This host root is outside the SDK process base_dir, so the manifest must grant it.
SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
),
entries={
# No grant is needed for local sources that stay under the SDK process base_dir.
"fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
# This entry reads from the granted host root and copies it into the sandbox workspace.
"docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
# Dir creates a sandbox workspace directory; it does not read from the host filesystem.
"output": Dir(description="Generated artifacts."),
},
)
Treat extra_path_grants as trusted application configuration. Do not populate grants from model output or other untrusted manifest input unless your application has already approved those host paths.
In this version, the SDK default model is now gpt-5.4-mini instead of gpt-4.1. This affects agents and runs that do not explicitly set a model. Because the new default is a GPT-5 model, implicit default model settings now include GPT-5 defaults such as reasoning.effort="none" and verbosity="low".
If you need to keep the previous default model behavior, set a model explicitly on the agent or run config, or set the OPENAI_DEFAULT_MODEL environment variable:
agent = Agent(name="Assistant", model="gpt-4.1")
Highlights:
Runner.run, Runner.run_sync, and Runner.run_streamed now accept max_turns=None to disable the turn limit.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 dependency extras in the Python package.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 sessions using the MCP Streamable HTTP transport 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 batch executor for FunctionTool instances.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:
FunctionTool instances wrapping synchronous Python callables now execute on worker threads via 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 rather than passing the user and assistant turns as separate messages, giving downstream agents a concise, predictable recap
For context, here is the conversation so far between the user and the previous agent: before the <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 for handling SIP protocol connections.Runner#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, this applies to the list_tools() method signature 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 every overridden MCPServer.list_tools() method in subclasses of MCPServer.