# What changed in openai-agents

> 87 changes in openai-agents 0.23 to 0.24 from its official release notes, upgrade guides and advisories: 7 breaking, 9 security, 8 new APIs and options. Each one cited. Sources checked 2026-10-19. HTML: https://unstale.sh/pypi/openai-agents/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## openai-agents 0.24

### Breaking changes

- macOS sandbox commands deny Launch Services requests, preventing local commands from launching host applications through Launch Services. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Transactional append, clear, and replacement require a supported backend; Redis Cluster reads and pops remain available. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- New snapshots use schema 1.21, and some legacy graphs with same-name non-root agents are rejected rather than risk incorrect agent ownership; finish affected tasks with their original SDK and agent code. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)

### Security

- Protected mount failures produce fresh redacted errors while retaining source arguments and linked exceptions and detaching the caught source traceback. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)

### New APIs and options

- The formatter arguments include an optional error field for tool exceptions. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- The run-wide tool error formatter can receive the new tool_exception category for eligible decorated function failures; explicit per-tool handlers retain precedence. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)

### Behavior and default changes

- Automatic compaction waits while approvals are pending, avoiding compaction before approval history is ready. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Unserializable dataclass run contexts are omitted with a warning; use a serializer/deserializer or context_override, or strict_context=True to reject omission. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Deferred approval history is persisted across resumes and waits for the output guardrail boundary. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Converted MCP tools expose copied optional mcp_annotations metadata as discovery hints; it does not authorize execution or enter model schemas. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Writes are batched in requests of at most 20 items to respect the API limit; multi-request writes can commit partially, so reconcile remote history before retrying. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)

### Fixes and other changes

- Approved tools resumed after approval are traced inside the resumed agent span. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Accepted call/output pairs survive sibling or callback failures after input and tool-output guardrails permit publication, allowing supported recovery without replaying completed tools. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Unhandled computer safety checks now produce a warning. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Function-call aliases are preserved when restoring RunState. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Completed stop tools can reject added pending input when ending a resumed run; finish that run before starting a new user turn. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Standalone Redis replacement is atomic; coordinate other writers because atomic replacement does not prevent stale compaction across processes. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- The tracing opt-out is honored inside caller-owned traces, including resumed tools and streamed cleanup. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)
- Invalid sandbox tool arguments return recoverable tool errors without swallowing provider failures. (0.24.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.24.0)

## openai-agents 0.23

### Breaking changes

- Host sources in dictionary sandbox manifests are rejected. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Session history now requires encrypted envelopes. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Tool arguments that would be silently discarded as kwargs are now rejected. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Blank branch names are rejected for SQLite sessions. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)

### Security

- Streaming callback backlogs are bounded, and callbacks are validated before execution. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Host PATH read grants are limited to the child environment. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Exception details are redacted from Realtime tool error events. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Realtime tool output guardrails are now enforced. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Incoming WebSocket message size is bounded by default. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Grants are enforced during recursive removal. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Model metadata now respects the sensitive trace capture setting. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Special files are rejected in shared UnixLocal file I/O. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)

### New APIs and options

- An optional item budget is available for compaction rollback. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Docker removal protection can now be opted into. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- An encrypted history scan budget is available as an opt-in. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- MCP listing page limits are now configurable. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The number of turns used for memory consolidation can now be configured. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Bounded workspace outbox reads are available as an opt-in. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)

### Behavior and default changes

- Verbose connector output is summarized, reducing the amount of output passed through. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The STT session logging header is no longer forced. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Reasoning is omitted from default trace exports. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- gpt-transcribe is now the default voice STT model. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)

### Fixes and other changes

- Literal Unicode content now matches correctly. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The agent_end event names the agent whose turn ended. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Tools are resolved after agent start hooks run. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Filtered history is preserved during automatic compaction. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Built-in shell and apply_patch tools are selected by their own type. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Premature end-of-file in Chat Completions streams is rejected. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Clearing a session now resets the compaction response chain. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Closed parent constraints are preserved in singleton allOf schemas. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Codex command spans now honor the run tracing policy. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Namespaced compaction model names are accepted. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Output-only metadata is stripped from compaction replay. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Default tool failure details are redacted. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Ambiguous canonical Docker removal paths are rejected. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Encrypted session visibility is refreshed before compaction. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Encrypted SQLite history is preserved when pops use the wrong key. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Exporter overrides are preserved during shutdown. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Annotated constraints on function tools are preserved. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Function tool approvals are scoped to their owning agent. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Agent tools now preserve guarded final outputs. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Host grants are validated against normalized workspace roots. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Resumed MCP calls are bound to their original recipients. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The traceable dictionary now serializes only traced fields. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- MongoDB session identifiers are now validated. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Nested agent tool state is isolated across fresh runs and restored against the tool's own agent. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Nullable token counts are normalized in Chat Completions and remaining provider paths. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The pipeline tracing opt-out is honored inside caller traces. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Session keys are validated before clearing. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Terminal controls are escaped in result diagnostics. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Sandbox apply_patch approval scope is checked. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Fresh streamed handoffs are recovered after session append failures, preventing a failed append from losing the handoff. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Handoffs are recovered after compaction is cancelled. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Previous stream event aliases are discarded when a model times out. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- The session remains usable after a 5xx response. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Streamed transcription is finished when input ends. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Exception tracebacks from streaming tasks are redacted. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Persistence now preserves structured guardrail diagnostics and agent output. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- On Python 3.10, _wait_for_event raises the builtin TimeoutError. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Tool identity is preserved during asynchronous enablement. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Callback results are now validated. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- An item with non-JSON-serializable values no longer causes the export batch to be discarded. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Rate-limited trace exports are retried. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Transcription iterators are finished when sessions close during setup. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- UnixLocal snapshots preserve hardlinks and normalize special files and symlinks. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Legacy positional configuration arguments continue to be accepted. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Pre-request WebSocket handshake failures are retried. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)
- Nested paths and symlink targets are preserved in workspace snapshots. (0.23.0) — [release notes](https://github.com/openai/openai-agents-python/releases/tag/v0.23.0)