pypi openai-agents 0.25.0
v0.25.0

one hour ago

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

v0.24.0...4cd46a6

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 main at fd78fa038f853598ed849e25eec78bab1e49aa00, #5394 changes only six release metadata files. The frozen API snapshot records its generating commit e03c7157f7629ff60aa3e434f2f083f72e4c7ba9, the candidate's parent.

Risk assessment (ordered by impact)

  1. 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 runloop extra, 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 in SandboxRunConfig, adapt mounts, and restore data into a new sandbox. Existing Runloop session IDs and snapshots cannot be resumed directly by Modal.
  2. Checkpoint readers and Pydantic context serialization

    • Risk: 🟢 LOW with ordered deployment. A v0.24.0 worker rejects a new 1.22 checkpoint. 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.21 and writes 1.22 to 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_serializer to exclude or transform process-local fields and context_deserializer or context_override to restore the application context.
  3. 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: OpenAIResponsesCompactionSession changes its default from gpt-4.1 to gpt-6-luna. MCP now requires >=1.30.0,<3,!=2.0.*,!=2.1.*. The Daytona extra requires daytona>=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 the 1.22 reader-before-writer rollout order and a Pydantic example that excludes a process-local field.
    • In docs/sessions/index.md and docs/models/index.md, distinguish the new compaction default from the agent model default, show the model= 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. In docs/handoffs.md, document the Runner-only failure_error_function and its default exception behavior.
    • In docs/sandbox/clients.md, link the Runloop migration, record the Daytona range and refresh the localized provider tables. In examples/sandbox/external_provider/README.md, qualify the local co-install command: the standalone example declares >=0.24.0,<0.25.0 and cannot be installed alongside this candidate with that constraint.
  • 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.
  • OpenAIResponsesCompactionSession now defaults to gpt-6-luna. Set model="gpt-4.1" to keep the previous choice. Agent model settings also follow the selected model more closely. Native Chat Completions tool requests for gpt-6-sol and gpt-6-luna default 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.

Don't miss a new openai-agents release

NewReleases is sending notifications on new releases.