openai‑agents‑python 0.24.0 and 0.23.1: Checkpoint, Tool Error and Session Changes

Version 0.24.0: RunState, tool errors and session recovery #

The v0.24.0 release notes are dated 2026-10-15 and include a readiness review that classifies the release as a minor release. The review reports 111 files changed (+15,444/-1,412) and gives a versioning verdict of compatible with the required minor release. Its release call is quoted below, and the sections that follow group the changes by theme.

"The prepared 0.24.0 candidate has no unresolved release blocker." v0.24.0 release notes

Saved RunState checkpoints need the original SDK #

The RunState writer advances from schema 1.18 to 1.21, and the reader rejects certain older graphs that contain same-name non-root agents. The review states that the saved identity ordering could have depended on hook attributes, even when those attributes stayed unchanged. For affected runs, finish the legacy tasks with the original SDK rather than loading them under the new reader. The rejection is a safe failure, so the checkpoint is not resumed with a possibly incorrect agent ownership.

The notes give specific conditions for finishing these tasks: use the original SDK, unchanged agent definitions and the hook ordering used when the snapshot was written. Do not rename a stored graph or change its schema label to force migration. New identity generation excludes all hook instance attributes and keeps the hook type, so graphs that differ only by those attributes cannot be serialized. Use unique agent names before starting new durable runs, and note that older SDKs cannot read new 1.21 snapshots.

Tool error formatters gain a tool_exception category #

The ToolErrorFormatterArgs.kind field adds "tool_exception", and the optional error field is appended to the formatter arguments. The run-wide callback now handles eligible decorated function failures. Explicit per-tool handlers keep precedence, including an explicit None or the default handler. Factory-created MCP and Agent.as_tool failures, timeouts, cancellation and schema-backed program calls keep their separate behavior. Because the notes warn that a formatter treating every non-rejection as a missing tool can return misleading text for a crashed function, handle "tool_exception" explicitly or return None to keep the default message.

With no custom formatter, the default behavior stays unchanged. The notes also say to keep exception details out of model-visible output unless they are deliberately sanitized. Formatters that are exhaustive over the category values need the new branch, because a new value reaches them after the upgrade.

Completed tool outputs and session writes during failures #

For client-managed runs, accepted call and output pairs survive sibling or callback failures once input and tool-output guardrails permit publication. The notes say this preserves completed work without promising automatic replay, so applications must still reconcile external side effects and partially committed history. Automatic compaction waits for pending approvals, and deferred approval history waits for the output guardrail boundary. Resume supported nonterminal failures with the original session backend and ID, using returned state and history rather than replaying completed tools.

Conversations writes use batches of at most 20 items and can commit partially across requests. After a partial append, inspect and repair remote history before retrying, and do not resend the full list while an earlier part remains stored. Redis replacement now uses a transaction, but the notes state that it does not prevent stale compaction across processes, so writers need coordination. Redis Cluster reads and pops remain available, while transactional append, clear and replacement require a supported backend. The notes record the related rejection changes in #5323 and #5361, which are referenced as plain issue numbers.

Sandbox, tracing and realtime example changes #

The notes say that #5335 adds Launch Services denial to the shared normal and PTY macOS profile, so macOS local commands can no longer launch host applications through Launch Services. Native coverage checks the operating-system decision. The same notes instruct that local sandboxing must not be described as complete host or network isolation, and that the documented Docker or hosted alternatives should be used where needed. The reporter credit for #5335 is listed for retention in the release.

Sandbox input validation now returns recoverable tool errors without swallowing provider failures. Protected mount failures produce fresh redacted errors, with source arguments and linked exceptions intact, though the caught source traceback is detached. The tracing opt-out covers resumed tools and streamed cleanup, and resumed approved tools use the agent span. Disabled runs emit fewer spans inside caller-owned traces. The realtime example renders tool content as literal text. The review states that no tracing or realtime configuration migration is required.

Smaller 0.24.0 features, fixes and dependency bumps #

• Features: MCP annotations are exposed on converted tools (#5356), and run-wide tool exception formatting is supported (#5326).
• Fixes: unserializable dataclass run contexts are omitted (#5303); function-call aliases are preserved across RunState restoration (#5358); parameter descriptions in Args-only docstrings are preserved (#5302); pending input is rejected when completed stop tools end a resume (#5366); unhandled computer safety checks now produce a warning (#5305).
• Dependencies: the notes list redis from 7.0.1 to 8.1.0 (#5379), temporalio from 1.33.0 to 1.34.0 (#5377), boto3 from 1.42.75 to 1.43.109 (#5378), and several example requirement updates, including openai in /examples/realtime/twilio_sip.

Version 0.23.1: patch release and inherited migration guidance #

The v0.23.1 release notes, dated 2026-10-02, list one fix: restore release tests and refresh the required readiness check (#5278). The readiness review classifies this as a patch, 0.23.1 and reports 28 files changed (+622/-42). Relative to v0.23.0, the SDK runtime source changes only its version string, and the review states that API snapshot content, dependencies, Python support and persisted schemas are unchanged.

Release readiness checks in the 0.23.1 candidate #

OS mocks are now installed after event-loop initialization and restored before teardown, and authorized review events rerun the current PR-triggered readiness check rather than replacing or cancelling it. Source validation, native human approval, isolated builds and OIDC publishing remain unchanged. The review states that readiness fails because human approval is missing at the handoff, and that any new candidate head invalidates the approval body. Maintainers should submit exact-head approval and allow readiness to refresh before merging.

Carry 0.23.0 migration guidance into 0.23.1 upgrades #

The review states that PyPI has neither 0.23.0 nor 0.23.1 at the time of assessment, and that users upgrading from 0.22.3 receive the 0.23.0 behavior changes as well as this patch. The notes direct that the following 0.23.0 migration guidance be carried into the 0.23.1 announcement:

• explicit strict-tool parameters
• fresh legacy approvals
• trusted encrypted-history import
• resource-limit overrides
• the explicit prior voice-model override

The notes also list documentation follow-ups for voice, human-in-the-loop, tools, realtime transport and encrypted sessions. The review states that the separate documentation handoff for inherited MCP, sandbox, tracing and SQLAlchemy guidance remains open.

External-provider integration tests need explicit opt-in #

Integration bootstrap now resets inherited enable flags, removes the listed external-provider credentials by default, and rejects external model overrides without opt-in. External cases are deselected by default, and automatic examples use the expanded skip list. Default coverage is therefore not external-provider validation. For direct-provider coverage, use make integration-tests-providers-external and add -- --all. Manual example selection remains available.

Upgrade checklist for openai-agents-python 0.24.0 and 0.23.1 #

1. Identify saved durable runs that contain same-name non-root agents, since the 0.24.0 reader rejects certain older graphs of that kind.
2. Finish those legacy tasks with the original SDK, unchanged agent definitions and the hook ordering used when each snapshot was written.
3. Use unique agent names before starting new durable runs. Do not rename a stored graph or change its schema label.
4. Before any rollback, note that older SDKs cannot read new 1.21 snapshots.
5. Update custom tool error formatters to handle "tool_exception" explicitly or return None, and keep exception details out of model-visible output unless they are sanitized.
6. Resume supported failures with the original session backend and ID. After a partial Conversations append, inspect and repair remote history before retrying.
7. Coordinate other writers to the same session, because Redis atomic replacement does not prevent stale compaction across processes.
8. For macOS local sandbox use, keep the behavior note in internal documentation and use Docker or hosted alternatives where isolation is required.
9. If upgrading from 0.22.3, apply the 0.23.0 migration guidance that 0.23.1 carries forward.
10. Run external-provider integration coverage with make integration-tests-providers-external, adding -- --all when direct-provider coverage is intended.