openai/openai-agents-python v0.24.0 on GitHub

0.24.0 (2026-10-15)

Features

expose MCP annotations on converted tools (#5356) (75813f8)
support run-wide tool exception formatting (#5326) (8fd9a7c)

Bug Fixes

batch OpenAI conversation session writes within the API limit (#5334) (26345c1)
defer automatic compaction for pending approvals (#5363) (5eb47a5)
deps-dev: bump fastapi from 0.139.2 to 0.141.1 (#5312) (cdf23bd)
deps-dev: bump grpcio from 1.83.1 to 1.84.0 (#5310) (a85487e)
deps-dev: bump pymdown-extensions from 11.0.2 to 12.1 (#5314) (d9758b0)
deps-dev: bump pymongo from 4.18.1 to 4.18.2 (#5313) (858856f)
deps: bump boto3 from 1.42.75 to 1.43.109 (#5378) (7da6a92)
deps: bump filelock from 3.20.3 to 4.0.12 (#5375) (14f4553)
deps: bump fsspec from 2025.7.0 to 2026.6.0 (#5317) (66504e9)
deps: bump redis from 7.0.1 to 8.1.0 (#5379) (24ebf1c)
deps: bump temporalio from 1.33.0 to 1.34.0 (#5377) (c148280)
deps: bump vercel-sandbox from 0.7.0 to 0.8.0 (#5374) (2938d87)
deps: update fastapi requirement from >=0.141.1 to >=0.142.2 in /examples/realtime/twilio_sip (#5372) (f47d2c3)
deps: update fastapi requirement in /examples/realtime/twilio_sip (f47d2c3)
deps: update openai requirement from <4,>=3.19.1 to >=3.20.0,<4 in /examples/realtime/twilio_sip (#5308) (f346950)
deps: update openai requirement from <4,>=3.20.0 to >=3.26.0,<4 in /examples/realtime/twilio_sip (#5376) (172ff5e)
deps: update openai requirement in /examples/realtime/twilio_sip (172ff5e)
deps: update openai requirement in /examples/realtime/twilio_sip (f346950)
deps: update pyjwt requirement from >=2.15.0 to >=2.15.1 in /examples/realtime/twilio (#5306) (7ca3c44)
deps: update pyjwt requirement in /examples/realtime/twilio (7ca3c44)
deps: update python-dotenv requirement (408c33f)
deps: update python-dotenv requirement from >=1.2.3 to >=1.2.4 in /examples/realtime/twilio (#5373) (c4cc409)
deps: update python-dotenv requirement from >=1.2.3 to >=1.2.4 in /examples/realtime/twilio_sip (#5371) (408c33f)
deps: update python-dotenv requirement in /examples/realtime/twilio (c4cc409)
deps: update twilio requirement from <10,>=9.11.1 to >=9.11.2,<10 in /examples/realtime/twilio (#5307) (cb03652)
deps: update twilio requirement in /examples/realtime/twilio (cb03652)
deps: update uvicorn requirement from >=0.53.0 to >=0.54.0 in /examples/realtime/twilio_sip (#5309) (f84fe73)
deps: update uvicorn requirement in /examples/realtime/twilio_sip (f84fe73)
examples: render realtime tool events as text (#5283) (81f0ccf)
honor Runner tracing opt-out inside caller traces (#5296) (8c4aa08)
memory: replace Redis compaction history atomically (#5354) (f50525c)
omit unserializable dataclass run contexts (#5303) (d7e52c3)
preserve caller-owned exceptions during sandbox redaction (#5367) (2244e9f)
preserve completed tool outputs when a sibling fails (#5332) (1c1a28d)
preserve embedded separators in sandbox patches (#5365) (67d4f8a)
preserve function-call aliases across RunState restoration (#5358) (f093ced)
Preserve parameter descriptions in Args-only docstrings (#5302) (a726a9c)
preserve RunState agent ownership across hook state changes (#5362) (d8e0a76)
preserve tool outputs after callback failures (#5318) (71c2da4)
recover from invalid sandbox tool arguments (#5321) (6ba967b)
reject pending input when completed stop tools end resume (#5366) (5a30187)
reject unsupported Redis Cluster session clients early (#5323) (911f106)
scope Redis Cluster rejection to transactional writes (#5361) (8068c37)
sessions: persist deferred approval history across resumes (#4828) (c757a43)
trace approved tools inside the resumed agent span (#5294) (cf89d7e)
tracing: omit caller data from lifecycle debug logs (#5299) (d27abe8)
warn about unhandled computer safety checks (#5305) (2c11c22)

Release readiness review (v0.23.1 -> TARGET `0f44a46`)

This is a release readiness report done by $final-release-review skill.

Diff

v0.23.1...0f44a46

Release intent

Review mode: final candidate, Release Please PR #5285.
Intended release: minor, 0.24.0.
Minimum required release type: minor. Existing tool error formatters receive a new category, and the RunState reader restricts some legacy agent identities.
Versioning verdict: compatible with the required minor release.

Release call

🟢 GREEN LIGHT TO SHIP. The prepared 0.24.0 candidate has no unresolved release blocker. Its compatibility changes have supported migration or fallback paths described below.

Scope summary

111 files changed (+15,444/-1,412). Main areas: tool execution and failure recovery, durable RunState and session history, sandbox safety, tracing, examples, dependencies, and release metadata.
The candidate contains current main and #5335. Changes beyond main are limited to release-owned metadata.

Risk assessment (ordered by impact)

Route affected saved runs to their original SDK and agent code.
- Risk: 🟢 LOW, with a required upgrade precaution. Some previously readable checkpoints now fail safely instead of risking incorrect agent ownership.
- Evidence: the writer advances from schema 1.18 to 1.21. The reader rejects certain older graphs with same-name non-root agents whose saved identity ordering could have depended on hook attributes, even when those attributes remained unchanged. New identity generation excludes all hook instance attributes and retains the hook type. Graphs distinguishable only by those attributes cannot be serialized. Other supported historical schemas remain readable.
- Files: src/agents/run_state.py, src/agents/_run_state_agent_identity.py, tests/test_run_state.py.
- Action: finish affected legacy tasks with the original SDK, unchanged agent definitions, and hook ordering used when the snapshot was written. Use unique agent names before starting new durable runs. Do not rename a stored graph or change its schema label to force migration. Older SDKs cannot read new 1.21 snapshots.
Update existing custom tool error formatters for a third category.
- Risk: 🟢 LOW, with an explicit migration for exhaustive callbacks. A formatter that treats every non-rejection as a missing tool can now return misleading text for a crashed function.
- Evidence: ToolErrorFormatterArgs.kind adds "tool_exception"; the optional error field is appended. The run-wide callback now handles eligible decorated function failures. Explicit per-tool handlers, including explicit None or the default handler, keep precedence. Factory-created MCP and Agent.as_tool failures, timeouts, cancellation, and schema-backed program calls keep their separate behavior.
- Files: src/agents/run_config.py, src/agents/tool.py, src/agents/run_internal/tool_execution.py, tests/test_tool_exception_formatter.py.
- Action: handle "tool_exception" explicitly or return None for it to retain the default message. Keep exception details out of model-visible output unless deliberately sanitized. With no custom formatter, default behavior stays unchanged.
Preserve completed work without promising automatic replay.
- Risk: 🟢 LOW. Recovery retains more completed work, but applications must still reconcile external side effects and partially committed history.
- Evidence: deferred approval history waits for the output guardrail boundary. For client-managed runs, accepted call/output pairs survive sibling or callback failures after input and tool-output guardrails permit publication. Server-managed conversations retain their separate recovery path. Pending writes retain session identity and compaction state. Automatic compaction waits for pending approvals; standalone Redis replacement uses a transaction. Conversations writes use batches of at most 20 items and can commit partially across requests.
- Files: src/agents/run_internal/session_persistence.py, src/agents/run_internal/tool_execution.py, src/agents/memory/openai_conversations_session.py, src/agents/memory/openai_responses_compaction_session.py, src/agents/extensions/memory/redis_session.py.
- Action: resume supported nonterminal failures with the original session backend and ID, using returned state and history instead of replaying completed tools. After a partial Conversations append, inspect and repair remote history before retrying; do not resend the full list while an earlier part remains stored. Coordinate other writers; Redis atomic replacement does not prevent stale compaction across processes. Redis Cluster reads and pops remain available, but transactional append, clear, and replacement require a supported backend. Terminal output failures do not become replayable.
Retain the intended sandbox, tracing, and display boundaries.
- Risk: 🟢 LOW. macOS local commands can no longer launch host applications through Launch Services; disabled runs emit fewer spans inside caller-owned traces.
- Evidence: #5335 adds Launch Services denial to the shared normal/PTY macOS profile. Native coverage checks the operating-system decision. Sandbox input validation returns recoverable tool errors without swallowing provider failures. Protected mount failures produce fresh redacted errors. Source arguments and linked exceptions remain intact, but the caught source traceback is detached. Tracing opt-out covers resumed tools and streamed cleanup, while resumed approved tools use the agent span. The realtime example renders tool content as literal text.
- Files: src/agents/sandbox/sandboxes/unix_local.py, src/agents/sandbox/_mount_security.py, src/agents/run.py, src/agents/tracing/, examples/realtime/app/static/app.js.
- Action: retain the macOS behavior note and #5335 reporter credit in the release. Do not describe local sandboxing as complete host or network isolation; use the documented Docker or hosted alternatives where needed. No tracing or realtime configuration migration is required.
Keep additive integrations and dependency requirements explicit.
- Risk: 🟢 LOW. Consumers opting into metadata, examples, or extras must use their specific contracts.
- Evidence: converted MCP tools expose copied mcp_annotations metadata; it does not grant approval or become a model tool schema. Decisions examples use a separate OpenAI client with named typed answers and conservative refusal handling. Core Python support remains >=3.10 and the OpenAI dependency remains >=3.0.0,<4. The examples require OpenAI >=3.26.0,<4; the Temporal extra pins 1.34.0 and the Vercel extra accepts >=0.7.0,<0.9.
- Files: src/agents/mcp/util.py, src/agents/tool.py, examples/decisions/, pyproject.toml, uv.lock.
- Action: treat MCP annotations as untrusted discovery hints. Non-MCP and unannotated tools return None; reads return copies. Omitted hints stay omitted, so apply the installed MCP defaults yourself. The metadata is not serialized into tool origin. Install the example-specific SDK version and retain separate client/tracing ownership. Refresh application lockfiles when adopting the changed extras.

Documentation coverage (non-blocking)

Coverage source: current candidate documentation and a fresh search of all open PRs. The only open documentation PR is #5370 at 7754b11c7a8b4a2a0e9492f43de5f4762c456367; its complete diff removes Runloop guidance for unmerged #5369. It does not cover this release's new obligations. Runloop removal is outside this candidate.
Status: partially covered.
Covered obligations: existing SDK/agent version routing for saved tasks; tracing opt-out and local sandbox limits; MCP callable approval policies; computer safety checks; Decisions example setup, separate client ownership, refusal handling, and routing limitations.
Gaps and exact post-release suggestions:

File and section	Wording or example to add
`docs/human_in_the_loop.md`, "Versioning pending tasks" and "Serialization options"	Explain schema 1.21, the legacy hook-identity restriction, and finishing affected tasks on their original SDK/agent code. Recommend unique names for new durable runs; same-name agents indistinguishable without hook attributes cannot serialize. Explain that unserializable dataclass context is omitted with a warning; show a serializer/deserializer or `context_override`, and `strict_context=True` to reject omission.
`docs/running_agents.md`, `tool_error_formatter`; `docs/tools.md`, "Handling errors in function tools"	Add `tool_exception`, `error`, callback migration, `None` fallback, explicit per-tool precedence, exclusions, and safe model-visible messages.
`docs/results.md`, failure recovery and pending input	Explain retained completed outputs, absent custom output metadata after failed extraction, original session ownership, and the terminal-output replay limit. State that completed stop tools can reject added pending input; finish that run before starting a new user turn.
`docs/sessions/index.md`, Conversations, Redis, and compaction sections	Document 20-item request batches and partial-append reconciliation. Multi-request writes disable client retries and drain the current request on cancellation; single-request writes retain client behavior. Explain deferred compaction during approvals; standalone Redis atomic replacement, Cluster write restrictions, and application coordination across writers.
`docs/mcp.md`, tool discovery and agent-level configuration	Document `FunctionTool.mcp_annotations` as copied optional metadata; absent annotations return `None` and omitted hints remain omitted. Consumers apply the installed MCP defaults. State that metadata neither authorizes execution nor enters model schemas or serialized tool origin. Distinguish MCP failure handlers from the run-wide formatter.
`docs/sandbox/clients.md`, local and hosted clients	Optionally note macOS Launch Services denial and document the Vercel >=0.7.0,<0.9 bound. Preserve the existing local-isolation limitations.

Publication timing: publish documentation for new behavior after 0.24.0 is available. These documentation gaps do not block the release.

Key Changes draft

Key Changes

0.24.0 adds run-wide function error formatting and MCP discovery annotations, and improves recovery, sandbox safety, and tracing. This minor release includes compatibility changes for custom error callbacks and some saved agent graphs. Review the first two highlights before upgrading.

Highlights:

Update custom error formatters. RunConfig.tool_error_formatter can receive kind="tool_exception" and an optional error. Handle the new kind or return None to retain the default message. Explicit per-tool handlers keep precedence; unconfigured defaults stay unchanged.
Plan upgrades around saved runs. New RunState snapshots use schema 1.21. Finish affected older same-name agent graphs on their original SDK. Keep the agent code and original hook ordering unchanged. Use unique agent names for new durable runs; renaming a saved graph is not a migration.
Recover completed work more reliably. Deferred approval history, completed tool outputs, aliases, and compaction state survive supported recovery paths. Automatic compaction waits for approvals. Redis replaces history atomically on supported standalone clients. Conversations appends respect the 20-item request limit. Reconcile partial writes before retrying.
Harden local execution and display. macOS sandbox commands deny Launch Services requests. Sandbox tools recover from invalid model arguments. Protected mount errors preserve caller exception data while detaching the caught traceback. The realtime demo displays tool content as text.
Honor tracing choices through resume and cleanup. Per-run tracing opt-out applies inside caller traces, and approved resumed tools attach to the resumed agent span.
Use richer integration examples and metadata. MCP tools expose optional mcp_annotations as discovery hints. New Decisions recipes demonstrate classification, routing, and tool review with OpenAI >=3.26.0,<4. They use a separate client, not an Agents model adapter.
Refresh optional dependency locks. The Temporal extra uses temporalio==1.34.0; the Vercel extra supports vercel-sandbox>=0.7.0,<0.9. Core Python and OpenAI SDK minimums are unchanged.

Thanks to @masasron for reporting the macOS local sandbox issue fixed in #5335.

Notes

This review covers the exact candidate above, including its release metadata. Changes to main, the candidate, or its API baseline require a fresh release check and approval.