NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #1050 most downloaded on PyPI
OpenAI Agents SDK
Last release 3 days ago
02 Oct 2026
Ships fairly regularly
a new release about every 1 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
2 years old
123 releases · first in 2025
One column per month.
restore release tests and refresh required readiness check
This is a release readiness report done by $final-release-review skill.
🟢 GREEN LIGHT TO SHIP this exact candidate. No concrete release-blocking regression was identified. Human approval and normal repository protections still apply.
a575a6e637feb9aea1b591237b007dd4991ddfba plus only six release-owned metadata files. Package, lockfile, manifest, source version and API baseline agree on 0.23.1. Snapshot source b31b9f8d13d49142a64f8873f2cc2ee40441a795 is an ancestor of the candidate.First PyPI publication of the 0.23 series includes earlier migration requirements
CHANGELOG.md, src/agents/version.py; unchanged 0.23.0 runtime contracts assessed in #5226.Release checks recover without changing package behavior
tests/sandbox/test_unix_local_user_file_io.py, .github/scripts/release_automation.py, .github/workflows/release-readiness-refresh.yml, .github/workflows/release-readiness.yml.External-provider coverage now requires explicit maintainer intent
.github/scripts/run_integration_tests.py, integration_tests/conftest.py, Makefile, examples/run_examples.py, integration_tests/README.md.make integration-tests-providers-external, adding -- --all when direct-provider coverage is intended. Do not interpret default coverage as external-provider validation.fa2c43bc9e252c75d76d60c06959a725f1dc0205 has no release documentation coverage. No separate open docs/ PR was found after inspecting the current file lists..github/RELEASING.md explains readiness refresh and retry; integration_tests/README.md explains explicit external-provider execution and credential behavior.docs/voice/quickstart.md and docs/voice/pipeline.md with the new default and explicit prior-model override; docs/human_in_the_loop.md with legacy approval/MCP restoration guidance; docs/tools.md and docs/realtime/transport.md with callback/message limits and overrides; docs/sessions/encrypted_session.md with trusted plaintext migration through add_items(). The inherited MCP, sandbox, tracing and SQLAlchemy guidance remains part of that separate documentation handoff.fix(deps): update vulnerable dependencies without changing SDK APIs by @jbeckwith-oai in #4963
Full Changelog: v0.22.2...v0.22.3
feat: support current image generation tool options by @seratch in #4932
Full Changelog: v0.22.1...v0.22.2
feat(core): support image results in web search tools by @seratch in #4898
Full Changelog: v0.22.0...v0.22.1
Version 0.22.0 is a minor release because it adds substantial runtime hardening and tightens an existing provider configuration contract. Applications
Version 0.22.0 is a minor release because it adds substantial runtime hardening and tightens an existing provider configuration contract. Applications that combine an explicit openai_client with organization or project must move those values to the AsyncOpenAI client.
ModelBehaviorError for non-streaming Responses with terminal status failed or incomplete.OpenAIProvider receives an explicit client.RunState checkpoints while preserving nested-agent aggregation.handoff(agent) in generated graphs.Agent.clone() and RealtimeAgent.clone().Full Changelog: v0.21.1...v0.22.0
feat(core): add model call timeouts by @seratch in #4428
Full Changelog: v0.21.0...v0.21.1
This minor release does not introduce a known breaking SDK behavior change. The minor version bump is for the new provider-neutral testing APIs and th
This minor release does not introduce a known breaking SDK behavior change. The minor version bump is for the new provider-neutral testing APIs and the OpenAI Python v3 compatibility update.
agents.testing, agents.realtime.testing, and agents.voice.testing utilities for deterministic Agent, Sandbox, Realtime, and Voice workflow tests without provider requests.openai>=3.0.0,<4, including HTTPX2-aware request, response, transport, and exception handling.Full Changelog: v0.20.0...v0.21.0
Version 0.20.0 is a minor release because it changes the implicit default model and includes a potentially breaking MCP dependency migration for appli
Version 0.20.0 is a minor release because it changes the implicit default model and includes a potentially breaking MCP dependency migration for applications with customized local HTTP transports. MCP v1 remains supported, and affected applications can migrate to httpx2 or pin mcp<2.
gpt-5.6-luna; explicit models, run-level overrides, and OPENAI_DEFAULT_MODEL continue to take precedence.mcp<2.RunState.add_input() can stage durable user input before a resumed model call, with guardrail, persistence, and serialization support.gpt-live-transcribe, gpt-transcribe, and gpt-realtime-whisper.Runner.run is given a context by @ojassharma7 in #4245Full Changelog: v0.19.4...v0.20.0
fix: preserve completed tool guardrail results by @seratch in #4180
Full Changelog: v0.19.3...v0.19.4
fix: resolve agent tool name collisions consistently by @seratch in #4137
Full Changelog: v0.19.2...v0.19.3
feat: expose original callable through wrapped by @seratch in #4038
Full Changelog: v0.19.1...v0.19.2
feat(sandbox): support native host paths in path grants by @seratch in #4009
Full Changelog: v0.19.0...v0.19.1
This minor release does not introduce a breaking change. The minor version bump reflects a significant new OpenAI Responses feature area: Programmatic…
This minor release does not introduce a breaking change. The minor version bump reflects a significant new OpenAI Responses feature area: Programmatic Tool Calling.
agents.tool.ProgrammaticToolCallingTool, which lets supported OpenAI Responses models generate JavaScript to coordinate eligible tools. It supports per-tool allowed_callers, structured function-tool outputs, and integration with Runner streaming, guardrails, approvals, sessions, and RunState. See Programmatic Tool Calling for setup and constraints.agents.decorators module and the shorter @tool alias alongside the existing function and guardrail decorators. Function tools 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.Full Changelog: v0.18.3...v0.19.0
feat: make task and turn tracing spans configurable by @seratch in #3834
Full Changelog: v0.18.2...v0.18.3
feat: support GPT-5.6 request controls by @seratch in https://github.com/openai/openai-agents-python/pull/3794
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.18.1...v0.18.2
feat: add GPT-5.6 model defaults and migrate examples by @seratch in https://github.com/openai/openai-agents-python/pull/3774
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.18.0...v0.18.1
Since this version, the default model for RealtimeAgents is gpt-realtime-2.1: https://developers.openai.com/api/docs/models/gpt-realtime-2.1
Since this version, the default model for RealtimeAgents is gpt-realtime-2.1: https://developers.openai.com/api/docs/models/gpt-realtime-2.1
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.8...v0.18.0
feat: add invalid final output recovery handler by @seratch in https://github.com/openai/openai-agents-python/pull/3736
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.7...v0.17.8
feat: expose configurable websocket max_size limit by @anneheartrecord in https://github.com/openai/openai-agents-python/pull/3645
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.6...v0.17.7
feat: add pre-approval tool input guardrails by @seratch in https://github.com/openai/openai-agents-python/pull/3487
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.5...v0.17.6
fix: expose sandbox error retryability by @qiyaoq-oai in https://github.com/openai/openai-agents-python/pull/3581
__slots__ by @jluocsa in https://github.com/openai/openai-agents-python/pull/3534Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.4...v0.17.5
feat: support Realtime custom voice objects by @lionel-oai in https://github.com/openai/openai-agents-python/pull/3473
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.3...v0.17.4
fix: keep mountpoint credentials out of sandbox commands by @seratch in https://github.com/openai/openai-agents-python/pull/3429
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.2...v0.17.3
fix: #3268 fix OpenAI Conversations reasoning persistence by @seratch in https://github.com/openai/openai-agents-python/pull/3352
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.1...v0.17.2
fix: include sandbox provider error details by @seratch in https://github.com/openai/openai-agents-python/pull/3326
__post_init__ by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3234__call__ by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3211Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.17.0...v0.17.1
Since this version, the default model for RealtimeAgents is gpt-realtime-2: https://developers.openai.com/api/docs/models/gpt-realtime-2
Since this version, the default model for RealtimeAgents is gpt-realtime-2: https://developers.openai.com/api/docs/models/gpt-realtime-2
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.Expand commentComment on line R24Resolved
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.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.16.1...v0.17.0
fix: #3109 stabilize chat completions stream output indexes by @seratch in https://github.com/openai/openai-agents-python/pull/3176
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.16.0...v0.16.1
In this version, the SDK default model is now gpt-5.4-mini instead of gpt-4.1. This could affect agents and runs that do not explicitly set a model. B
In this version, the SDK default model is now gpt-5.4-mini instead of gpt-4.1. This could affect 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".
The new default model should work better for most use cases (see the report at https://github.com/openai/openai-agents-python/pull/3147), but if you need to keep the previous default model behavior for some reasons, set a model explicitly on the agent or run config like Agent(name="Assistant", model="gpt-4.1"), or set the OPENAI_DEFAULT_MODEL environment variable.
This version adds a new option max_turns=None to disable the Agents SDK run turn limit while preserving the existing default of DEFAULT_MAX_TURNS (10) when max_turns is omitted.
This version adds a new SDK-side runtime configuration for local function tool execution concurrency: ToolExecutionConfig(max_function_tool_concurrency=...) on RunConfig, preserves default behavior when unset. The change keeps provider-side ModelSettings.parallel_tool_calls separate from SDK-side local execution scheduling.
This version adds a new option include_server_in_tool_names to MCPConfig. When it is set to True, the SDK includes the MCP server name in the tool name to prevent tool name conflicts with other MCP servers.
agent = Agent(
name="Assistant",
mcp_servers=[my_mcp_server],
mcp_config={"include_server_in_tool_names": True},
)
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.3...v0.16.0
fix(mcp): avoid mutating tool input schemas by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3134
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.2...v0.15.3
feat: add context management model setting by @seratch in https://github.com/openai/openai-agents-python/pull/3128
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.1...v0.15.2
feat: expose Responses WebSocket keepalive options by @seratch in https://github.com/openai/openai-agents-python/pull/3080
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.0...v0.15.1
In this version, model refusals are now surfaced explicitly as ModelRefusalError instead of being treated as empty text output or, for structured outp
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.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.8...v0.15.0
fix: #3046 preserve MCP re-export import errors by @seratch in https://github.com/openai/openai-agents-python/pull/3048
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.7...v0.14.8
feat: #2886 add convenience properties (tool_name, call_id) to tool items by @jawwad-ali in https://github.com/openai/openai-agents-python/pull/3027
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.6...v0.14.7
fix: update examples and defaults to GPT-5.5 by @alfozan in https://github.com/openai/openai-agents-python/pull/3016
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.5...v0.14.6
feat: #3001 add Modal sandbox idle timeout option by @seratch in https://github.com/openai/openai-agents-python/pull/3005
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.4...v0.14.5
feat: add BoxMount support by @alfozan in https://github.com/openai/openai-agents-python/pull/2988
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.3...v0.14.4
fix: #2962 normalize sandbox paths and add Windows CI by @seratch in https://github.com/openai/openai-agents-python/pull/2963
handoff_filters.py so it is assigned to __doc__ by @kuishou68 in https://github.com/openai/openai-agents-python/pull/2950Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.2...v0.14.3
feat: support sandbox extra path grants by @qiyaoq-oai in https://github.com/openai/openai-agents-python/pull/2920
temporalio Dep in Temporal example by @JasonSteving99 in https://github.com/openai/openai-agents-python/pull/2918Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.1...v0.14.2
fix: sanitize OpenAI tracing export payloads by @alfozan in https://github.com/openai/openai-agents-python/pull/2896
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.0...v0.14.1
This release adds Sandbox Agents, a beta SDK surface for running agents with a persistent, isolated workspace. Sandbox agents keep the normal Agent an
This release adds Sandbox Agents, a beta SDK surface for running agents with a persistent, isolated workspace. Sandbox agents keep the normal Agent and Runner flow, but add workspace manifests, sandbox-native capabilities, sandbox clients, snapshots, and resume support so agents can work over real files, run commands, edit repositories, generate artifacts, and continue work across runs.
Key pieces:
SandboxAgent: an Agent with sandbox defaults such as default_manifest, sandbox instructions, capabilities, and run_as.Manifest: a fresh-workspace contract for files, directories, local files, local directories, Git repos, environment, users, groups, and mounts.SandboxRunConfig: per-run sandbox wiring for client creation, live session injection, serialized session resume, manifest overrides, snapshots, and materialization concurrency limits.Sandbox agents now support local, containerized, and hosted execution backends:
UnixLocalSandboxClient for fast local development.DockerSandboxClient for container isolation and image parity.The release also adds provider-specific examples and mount strategies for common storage backends, including S3, Cloudflare R2, Google Cloud Storage, Azure Blob Storage, and S3 Files where supported by the selected backend.
Adds a sandbox memory capability that lets future sandbox-agent runs learn from prior runs. Memory stores extracted lessons in the sandbox workspace, injects a concise summary into later runs, and uses progressive disclosure so agents can search deeper rollout summaries only when useful.
Memory supports:
conversation_id, SDK Session, RunConfig.group_id, or generated run IDs.This release adds a full workspace entry and mount model for sandbox sessions:
RunState, explicit SandboxSessionState, or saved snapshots.Adds a large examples/sandbox/ suite covering:
The release includes the runtime plumbing needed to make sandbox agents work naturally inside the existing SDK:
RunState serialization.fix: #2863 lazy-load SQLiteSession exports by @seratch in https://github.com/openai/openai-agents-python/pull/2864
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.5...v0.13.6
feat: #2807 support callable approval policies for local MCP servers by @seratch in https://github.com/openai/openai-agents-python/pull/2818
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.4...v0.13.5
fix: #2806 sanitize AnyLLM responses replay input before validation by @seratch in https://github.com/openai/openai-agents-python/pull/2813
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.3...v0.13.4
fix: #2798 avoid stale hydrated input ids in server conversation tracker by @seratch in https://github.com/openai/openai-agents-python/pull/2800
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.2...v0.13.3
fix: #2783 depend on griffelib directly for docstring parsing by @seratch in https://github.com/openai/openai-agents-python/pull/2791
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.1...v0.13.2
Since this version, the extension module includes a new any-llm adapter as well. Please refer to the updated documentation and examples at https://git
Since this version, the extension module includes a new any-llm adapter as well. Please refer to the updated documentation and examples at https://github.com/openai/openai-agents-python/tree/main/examples/model_providers
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.13.0...v0.13.1
This minor release does not introduce a breaking change, but it includes a notable Realtime default update plus new MCP capabilities and runtime stabi…
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 are:
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.Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.5...v0.13.0
feat(mcp): expose auth and httpx_client_factory in SSE/StreamableHttp params by @adityasingh2400 in https://github.com/openai/openai-agents-python/pul
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.4...v0.12.5
fix: normalize cancelled MCP invocations into tool errors by @elainegan-openai in https://github.com/openai/openai-agents-python/pull/2704
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.3...v0.12.4
fix: handle inner MCP tool cancellations as tool errors by @elainegan-openai in https://github.com/openai/openai-agents-python/pull/2681
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.2...v0.12.3
fix: #2664 drop orphan hosted shell calls before multi-turn replay by @seratch in https://github.com/openai/openai-agents-python/pull/2665
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.1...v0.12.2
feat: #2658 preserve explicit approval rejection messages across resume flows by @seratch in https://github.com/openai/openai-agents-python/pull/2660
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.0...v0.12.1
New opt-in settings for retries of model API calls is available in this version. The new configuration is available as part of ModelSettings and it ca
New opt-in settings for retries of model API calls is available in this version. The new configuration is available as part of ModelSettings and it can be passed either as run config or model settings per an agent.
Refer to the following code examples for details:
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.11.1...v0.12.0
fix: show the GA computer alias in tracing by @seratch in https://github.com/openai/openai-agents-python/pull/2641
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.11.0...v0.11.1
As of this version, the Agents SDK supports the tool search tool, including namespaces: https://developers.openai.com/api/docs/guides/tools-tool-searc
As of this version, the Agents SDK supports the tool search tool, including namespaces: https://developers.openai.com/api/docs/guides/tools-tool-search/
Please refer to this concrete example, as well as the updated documentation.
As of this version, you can use the gpt-5.4 model for the computer use tool, in addition to the existing computer-use-preview model: https://developers.openai.com/api/docs/guides/tools-computer-use/
Please refer to this concrete example, as well as the updated documentation.
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.5...v0.11.0
docs: fix deprecated capwords import for Python 3.11+ compatibility by @Jah-yee in https://github.com/openai/openai-agents-python/pull/2605
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.4...v0.10.5
fix: isolate parallel function tool failures by @seratch in https://github.com/openai/openai-agents-python/pull/2584
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.3...v0.10.4
feat: expose immutable agent tool invocation metadata on run results (ref #2575) by @seratch in https://github.com/openai/openai-agents-python/pull/25
nest_handoff_history to Handoffs docs by @Hammad-Noman in https://github.com/openai/openai-agents-python/pull/2560Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.2...v0.10.3
fix: #2540 reattach resumed traces without duplicate trace starts by @seratch in https://github.com/openai/openai-agents-python/pull/2547
Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.1...v0.10.2
Your coding agent can read these notes before it upgrades. Set up the MCP server →