Repository navigation
0.25.0 (2026-11-17)
Features
- expose utilities for third-party session adapters (#5428) (16fdb20)
- sandbox: remove Runloop provider (#5369) (12ce34d)
Bug Fixes
- add opt-in handoff error recovery (#5418) (a6ed84f)
- align implicit settings with provider-selected models (#5425) (a88d291)
- align model defaults with TS SDK (#6064) (d5287b7)
- allow concurrent Streamable HTTP requests on MCP v2 (#5641) (2b90566)
- default GPT-6 Chat Completions tool requests to non-reasoning (#5420) (3396dca)
- deps-dev: bump aiohttp from 3.14.3 to 3.14.5 (#5403) (442d0ea)
- deps-dev: bump dapr from 1.18.3 to 1.19.0 (#5711) (25e7b2e)
- deps-dev: bump fastapi from 0.141.1 to 0.162.2 (#6053) (494c0c0)
- deps-dev: bump playwright from 1.50.0 to 1.63.0 (#5402) (0dc4cf1)
- deps-dev: bump pytest from 9.0.3 to 9.2.0 (#5710) (b0051a7)
- deps-dev: bump rich from 14.3.3 to 15.0.0 (#6055) (18d979b)
- deps-dev: bump ruff from 0.16.8 to 0.17.1 (#5439) (5bb6fb7)
- deps-dev: bump twilio from 9.11.1 to 9.12.0 (#5486) (465583d)
- deps-dev: bump websockets from 15.0.1 to 16.1.1 (#5484) (86bd298)
- deps: allow websockets 17 (#6044) (9d0f5e8)
- deps: bump actions/create-github-app-token from 3.2.0 to 3.3.0 (#5464) (b8df4ff)
- deps: bump actions/download-artifact from 8.0.1 to 8.0.2 (#5466) (eccd8c8)
- deps: bump actions/setup-python from 7.0.0 to 7.1.0 (#5465) (18d233b)
- deps: bump astral-sh/setup-uv from 10.2.0 to 10.3.2 (#5463) (1ed8268)
- deps: bump certifi from 2026.10.19 to 2026.10.23 (#5709) (976f2f1)
- deps: bump daytona from 0.155.0 to 0.226.1 (#5487) (d4f07df)
- deps: bump httpx2 from 2.12.0 to 2.14.0 (#5438) (0c55458)
- deps: bump mcp from 2.0.0 to 2.2.0 (#5393) (97c8288)
- deps: bump mcp from 2.0.0 to 2.3.0 (#5404) (e2de6a8)
- deps: bump openai from 3.29.0 to 3.48.0 (#6054) (a4a4fa4)
- deps: bump opentelemetry-api from 1.40.0 to 1.45.1 (#5410) (2964f77)
- deps: bump opentelemetry-api from 1.45.1 to 1.45.2 (#5983) (cdc8d58)
- deps: bump pydantic from 2.14.2 to 2.14.3 (#6052) (4bb2637)
- deps: bump starlette from 1.6.0 to 1.7.0 (#5708) (82483dd)
- deps: bump the codeql group with 2 updates (#5462) (775707e)
- deps: require certifi 2026.10.19 or later (#5429) (6295010)
- deps: require pymongo 4.18.3 or later (#5445) (57027de)
- deps: update fastapi requirement from >=0.142.2 to >=0.143.0 in /examples/realtime/twilio_sip (#5399) (6bfa5ff)
- deps: update fastapi requirement from >=0.143.0 to >=0.150.0 in /examples/realtime/twilio_sip (#5435) (56df6b4)
- deps: update fastapi requirement from >=0.150.0 to >=0.162.0 in /examples/realtime/twilio_sip (#5482) (803fbf2)
- deps: update fastapi requirement from >=0.162.0 to >=0.162.2 in /examples/realtime/twilio_sip (#6051) (9a3bce3)
- deps: update fastapi requirement in /examples/realtime/twilio_sip (9a3bce3)
- deps: update fastapi requirement in /examples/realtime/twilio_sip (803fbf2)
- deps: update fastapi requirement in /examples/realtime/twilio_sip (56df6b4)
- deps: update fastapi requirement in /examples/realtime/twilio_sip (6bfa5ff)
- deps: update httpx2 requirement from >=2.13.1 to >=2.15.1 in /examples/realtime/twilio (#5432) (4134643)
- deps: update httpx2 requirement from >=2.13.1 to >=2.15.1 in /examples/realtime/twilio_sip (#5436) (a91f0bf)
- deps: update httpx2 requirement from >=2.15.1 to >=2.16.0 in /examples/realtime/twilio (#5478) (16c3a3f)
- deps: update httpx2 requirement from >=2.15.1 to >=2.16.0 in /examples/realtime/twilio_sip (#5483) (39a123b)
- deps: update httpx2 requirement in /examples/realtime/twilio (16c3a3f)
- deps: update httpx2 requirement in /examples/realtime/twilio_sip (39a123b)
- deps: update openai requirement from <4,>=3.26.0 to >=3.29.0,<4 in /examples/realtime/twilio_sip (#5398) (0e54e4b)
- deps: update openai requirement from <4,>=3.29.0 to >=3.35.1,<4 in /examples/realtime/twilio_sip (#5434) (2350082)
- deps: update openai requirement from <4,>=3.35.1 to >=3.39.0,<4 in /examples/realtime/twilio_sip (#5480) (13dbaa3)
- deps: update openai requirement from <4,>=3.39.0 to >=3.42.1,<4 in /examples/realtime/twilio_sip (#5707) (6e590a0)
- deps: update openai requirement from <4,>=3.42.1 to >=3.48.0,<4 in /examples/realtime/twilio_sip (#6050) (5e0f944)
- deps: update openai requirement in /examples/realtime/twilio_sip (5e0f944)
- deps: update openai requirement in /examples/realtime/twilio_sip (6e590a0)
- deps: update openai requirement in /examples/realtime/twilio_sip (13dbaa3)
- deps: update openai requirement in /examples/realtime/twilio_sip (2350082)
- deps: update openai requirement in /examples/realtime/twilio_sip (0e54e4b)
- deps: update python-multipart requirement from >=0.0.32 to >=0.0.33 in /examples/realtime/twilio (#5706) (64fbde5)
- deps: update starlette requirement from >=1.7.0 to >=1.9.0 in /examples/realtime/twilio (#5433) (26c762a)
- deps: update starlette requirement from >=1.7.0 to >=1.9.0 in /examples/realtime/twilio_sip (#5437) (b6966fa)
- deps: update starlette requirement from >=1.9.0 to >=1.10.0 in /examples/realtime/twilio (#5479) (f137418)
- deps: update starlette requirement from >=1.9.0 to >=1.10.0 in /examples/realtime/twilio_sip (#5481) (814de8b)
- deps: update starlette requirement in /examples/realtime/twilio (f137418)
- deps: update starlette requirement in /examples/realtime/twilio_sip (814de8b)
- deps: update twilio requirement from <10,>=9.11.2 to >=9.12.0,<10 in /examples/realtime/twilio (#5397) (452c5bd)
- deps: update twilio requirement from <10,>=9.12.0 to >=9.13.0,<10 in /examples/realtime/twilio (#6049) (e27451c)
- deps: update twilio requirement in /examples/realtime/twilio (e27451c)
- deps: update twilio requirement in /examples/realtime/twilio (452c5bd)
- flatten restored handoff history summaries (#6041) (7635b81)
- improve missing stream completion diagnostics (#5457) (e355d69)
- limit the Daytona extra to the supported 0.x SDK (#6065) (fd78fa0)
- preserve append order in SQLAlchemy sessions (#5645) (89a3ea4)
- preserve empty structured shell results (#5423) (963d032)
- Preserve nested handoff record boundaries (b040da5)
- preserve nested handoff record boundaries (#5430) (b040da5)
- preserve pending async calls in committed sessions (#6039) (f48003a)
- preserve pending input history across streamed retries (#6042) (9e05bd5)
- preserve Pydantic run context snapshots (#5444) (bc4c6e1)
- preserve structured tool input in agent lifecycle hooks (#6037) (e3538bd)
- preserve usage from failed and incomplete Responses calls (#6046) (6e6707c)
- preserve wire aliases when reading Conversations session history (#6047) (5789c7c)
- preserve wire aliases when replaying Responses items (#5638) (71bab8c)
- raise MCP minimum to 1.21.2 for Pydantic and OAuth compatibility (#5384) (970db99)
- realtime: honor explicit interruption with automatic VAD (#5427) (addc737)
- remove retry advice from the default tool error message (#5632) (fa7f312)
- remove unused EFS installer from sandbox mount example (#6038) (0777ee6)
- replay ID-less assistant output in Chat Completions sessions (#5419) (28c29bc)
- report completed input guardrails when a tripwire fires (#5634) (2cc15af)
- report completed output guardrails when a tripwire fires (#6040) (4bab6ea)
- report missing function approval owners during RunState restore (#5630) (788fb99)
- require patched MCP dependency versions (#5431) (b235388)
- Responses tool choice for functions named after hosted tools (#5639) (3ac005f)
- Restore checkpointed assistant text in Chat Completions (8ffdf21)
- restore checkpointed assistant text in Chat Completions (#5628) (8ffdf21)
- resume nested approval checkpoints with output guardrails (#5629) (3599632)
- retain tool guardrail results after approval and resume (#5643) (3a0c89c)
- sessions: bounded session replay and isolate the Cloudflare mount test (#5637) (4920e5b)
- skip streamed model attempts after an input guardrail trips (#5644) (8ea4333)
- stop native tool queues during function failure cleanup (#5446) (cd26bbb)
- tool approval handling in the demo REPL (#6045) (d4d835e)
- trace offered tools on Chat Completions generation spans (#5635) (bb36fae)
- use gpt-6-luna for session compaction by default (#5646) (1fc77bb)
Release readiness review (v0.24.0 -> TARGET 4cd46a6)
This is a release readiness report done by $final-release-review skill.
Diff
Release intent
- Review mode: final candidate
- Intended release: minor, 0.25.0
- Minimum required release type: minor. Existing Pydantic checkpoint callers can need a serializer where v0.24.0 omitted an unset field, and previously supported MCP dependency pins can require an upgrade.
- Versioning verdict: compatible
Release call
🟢 GREEN LIGHT TO SHIP. The candidate provides migration paths for the compatibility changes. The package metadata, editable lock entry, Release Please manifest, source version and frozen API baseline agree on 0.25.0.
Scope summary
- 261 files changed (+14,052/-17,143) across the SDK, tests, examples, documentation and release workflows. Relative to current
mainatfd78fa038f853598ed849e25eec78bab1e49aa00, #5394 changes only six release metadata files. The frozen API snapshot records its generating commite03c7157f7629ff60aa3e434f2f083f72e4c7ba9, the candidate's parent.
Risk assessment (ordered by impact)
-
Runloop sandbox migration
- Risk: 🟢 LOW with migration. Applications using the beta Runloop integration must switch providers before upgrading or stay on 0.24.0 during migration.
- Evidence: The candidate removes the
runloopextra,agents.extensions.sandbox.runloop, and the Runloop exports. The migration guide identifies the supported Modal client and explains how provider-specific state affects the move. - Files:
pyproject.toml,src/agents/extensions/sandbox/__init__.py,examples/sandbox/extensions/README.md - Action: Preserve needed workspace data first. For Modal, install
openai-agents[modal], replace the client and options inSandboxRunConfig, adapt mounts, and restore data into a new sandbox. Existing Runloop session IDs and snapshots cannot be resumed directly by Modal.
-
Checkpoint readers and Pydantic context serialization
- Risk: 🟢 LOW with ordered deployment. A v0.24.0 worker rejects a new
1.22checkpoint. A Pydantic context with a process-local default, such as a client object, can now require an explicit serializer. - Evidence: v0.25.0 still reads
1.21and writes1.22to track approvals owned by nested agent tools. Pydantic context snapshots now include default values and in-place edits using JSON serialization. - Files:
src/agents/run_state.py,tests/test_run_state_pydantic_context.py - Action: Upgrade resume workers before enabling new writers, or route checkpoints by SDK version. Use
context_serializerto exclude or transform process-local fields andcontext_deserializerorcontext_overrideto restore the application context.
- Risk: 🟢 LOW with ordered deployment. A v0.24.0 worker rejects a new
-
Model defaults and dependency pins
- Risk: 🟢 LOW with explicit configuration. Applications that leave the compaction model unset will use a different model. Dependency locks may also need updates.
- Evidence:
OpenAIResponsesCompactionSessionchanges its default fromgpt-4.1togpt-6-luna. MCP now requires>=1.30.0,<3,!=2.0.*,!=2.1.*. The Daytona extra requiresdaytona>=0.226.1,<1. - Files:
src/agents/memory/openai_responses_compaction_session.py,src/agents/models/default_models.py,pyproject.toml - Action: Set
model="gpt-4.1"on the compaction session to retain its previous model. Refresh incompatible dependency pins. With MCP v2 Streamable HTTP, enable tool retries only when replaying a call is safe.
Documentation coverage (non-blocking)
- Coverage source: Reviewed the current open PRs. No separate open PR covers the 0.25.0 user-guide updates below.
- Status: partially covered.
- Covered obligations: The sandbox extension examples document the Runloop-to-Modal migration and data preservation. The human-in-the-loop guide already describes context serializers and version-aware resume routing.
- Post-release updates:
- In
docs/human_in_the_loop.md, add the1.22reader-before-writer rollout order and a Pydantic example that excludes a process-local field. - In
docs/sessions/index.mdanddocs/models/index.md, distinguish the new compaction default from the agent model default, show themodel=override, and update GPT-5-and-newer reasoning model guidance. - In
docs/mcp.md, correct the dependency range and explain when retrying concurrent Streamable HTTP tool requests is safe. Indocs/handoffs.md, document the Runner-onlyfailure_error_functionand its default exception behavior. - In
docs/sandbox/clients.md, link the Runloop migration, record the Daytona range and refresh the localized provider tables. Inexamples/sandbox/external_provider/README.md, qualify the local co-install command: the standalone example declares>=0.24.0,<0.25.0and cannot be installed alongside this candidate with that constraint.
- In
- Publication timing: Publish the 0.25.0 guidance after the package is available.
Key Changes draft
Key Changes
Version 0.25.0 removes the beta Runloop sandbox provider and changes how Pydantic run contexts are checkpointed. Runloop users should preserve their workspace data before switching providers. Applications that share checkpoints across workers should upgrade readers first.
Highlights:
- Migrate Runloop workloads to another supported sandbox provider, such as Modal, or remain on 0.24.0 while migrating. Provider-specific sessions and snapshots require a separate data migration.
- Resume nested agent-tool approvals with output guardrails using RunState schema
1.22. Pydantic checkpoints now preserve default values and in-place edits. Use a custom serializer for process-local resources. OpenAIResponsesCompactionSessionnow defaults togpt-6-luna. Setmodel="gpt-4.1"to keep the previous choice. Agent model settings also follow the selected model more closely. Native Chat Completions tool requests forgpt-6-solandgpt-6-lunadefault to non-reasoning mode when no effort is supplied.- Runner handoffs can opt into recovery with
failure_error_function. Omitting it preserves exception propagation. The demo REPL can now approve or reject individual tool calls. - MCP v2 Streamable HTTP supports concurrent requests. MCP v1 retains serialized requests. Failed and incomplete Responses calls now retain provider-reported token usage.