Changelog

OpenAI Agents SDK

OpenAI Agent SDK, showing Python releases

Recently checked

Last checked against an official source: Nov 7, 2026, 03:13 PM GMT+1

Collection from official sources is limited. Earlier releases may be missing. This page does not claim a complete version history.

Latest Version:v0.24.0

Loaded Releases:63

Source:GitHub Releases

RSS

Latest Releases (63)

v0.24.0

October 15, 2026

•expose MCP annotations on converted tools (#5356) (75813f8)
•support run-wide tool exception formatting (#5326) (8fd9a7c)
•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)

Show more (7)

•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)

v0.23.1

October 2, 2026

•restore release tests and refresh required readiness check (#5278) (730deb4)
•Review mode: final candidate
•Intended release: patch, 0.23.1
•Minimum required release type: patch
•Versioning verdict: compatible
•28 files changed (+622/-42): release automation, test fixtures, integration/example tooling, and release metadata.
•The clean candidate contains current main a575a6e637feb9aea1b591237b007dd4991ddfba plus only six release-owned metadata files. Package, lockfile, manifest, source version and API baseline agree on 0.23.1. Snapshot source b31b9f8d13d49142a64f8873f2cc2ee40441a795 is an ancestor of the candidate.
•Relative to v0.23.0, SDK runtime source changes only its version string. API snapshot content, dependencies, Python support and persisted schemas are unchanged.

Show more (7)

•First PyPI publication of the 0.23 series includes earlier migration requirements
•Risk: 🟢 LOW with the previously reviewed migration paths. Users upgrading from 0.22.3 receive the 0.23.0 behavior changes as well as this patch.
•Evidence: PyPI has neither 0.23.0 nor 0.23.1. The 0.23.0 release assessment in #5226 covers strict tools, approval restoration, encrypted history, resource limits, voice defaults and provider changes; this candidate does not alter those runtime paths.
•Files: CHANGELOG.md, src/agents/version.py; unchanged 0.23.0 runtime contracts assessed in #5226.
•Action: Carry forward the 0.23.0 migration guidance in the 0.23.1 announcement, particularly explicit strict-tool parameters, fresh legacy approvals, trusted encrypted-history import, resource-limit overrides and the explicit prior voice-model override.
•Release checks recover without changing package behavior
•Risk: 🟢 LOW. Test-loop initialization and required-check ownership are corrected while publication authorization remains intact.

v0.23.0

October 2, 2026

•mcp: add configurable MCP listing page limits (#5133) (9a21ab1)
•sandbox: add opt-in Docker removal protection (#5116) (ae5803f)
•sandbox: allow configuring memory consolidation turns (#5135) (daa1bcb)
•sessions: add an opt-in encrypted history scan budget (#5118) (a2fdb94)
•avoid awaiting cleanup during coroutine closure (#5163) (719c4e7)
•ci: update and group CodeQL actions together (#5262) (f76153c)
•ci: validate release source before building distributions (#5220) (2747c1c)
•core/extensions: respect sensitive trace capture for model metadata (#5129) (88b722d)

Show more (7)

•core: bound agent tool streaming callback backlogs (#5106) (f23da76)
•core: isolate nested agent tool state across fresh runs (#5123) (46cc8d8)
•core: preserve closed parent constraints in singleton allOf (#5131) (f010d18)
•core: preserve guarded final outputs in agent tools (#5115) (f3a15f6)
•core: preserve structured guardrail diagnostics and agent output during persistence (#5016) (51bcea7)
•core: preserve tool identity during asynchronous enablement (#5136) (f2ae64c)
•core: redact default tool failure details (#5112) (40956e0)

v0.22.3

September 18, 2026

What's Changed

fix(core): align conditional approvals with validated tool arguments (#5066)
fix(core): deliver tool-not-found output on server-managed resume (#4947)
fix(sandbox): keep command paths POSIX on a Windows host (#4958)
fix(sessions): handle concurrent async SQLite startup (#4987)

fix(sessions): do not forward session limit as Conversations page size (#4961)
fix(tracing): do not cache a missing OPENAI_API_KEY (#5017)
fix(extensions): include shell and apply_patch calls in AdvancedSQLiteSession's tool usage (#4982)
fix(extensions): reap subprocesses on early stream close (#4804)
fix(extensions): preserve exact IDs in AdvancedSQLiteSession.delete_branch (#4980)

Documentation & Other Changes

docs: align repository security and contributor guidance (#4962)
docs: clarify Unix-local execution boundaries (#5064)
docs: update translated pages (#5065)
docs(examples): drop the duplicated word in the Temporal trace name (#5079)
chore: add code ownership and required release review guidance (#4965)
fix(deps): update vulnerable dependencies without changing SDK APIs (#4963)
ci: add Python and Actions CodeQL security scanning (#4974)
Add SDKs team as repository code owner (#5058)
release: 0.22.3 (#5077)

New Contributors

@hyeonsang010716 made their first contribution (#4947)
@jbeckwith-oai made their first contribution (#4962)
@00200200 made their first contribution (#4987)
@JiangLLM made their first contribution (#4980)
@tiagovilasboas made their first contribution (#4961)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.22.2...v0.22.3

v0.22.2

OpenAI Agents SDK 0.22.2

September 9, 2026

What's Changed

feat: support current image generation tool options (#4932)
fix(sandbox): prevent UnixLocal file API symlink races (#4931)
fix(sessions): reset compaction response chain after pop (#4934)

Documentation & Other Changes

docs: document v0.22.1 behavior updates (#4577)
release: 0.22.2 (#4935)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.22.1...v0.22.2

v0.22.1

September 8, 2026

What's Changed

feat(core): support image results in web search tools (#4898)
feat(core): customize output guardrail blocked messages (#4594)
feat(mcp): add server-wide guardrails to MCP tools (#4632)
feat(sandbox): add configurable Unix-local environment isolation (#4640)

feat(sandbox): allow labels on Docker sandbox containers (#4564)
feat(voice): expose streamed transcription options (#4645)
fix(core): detach aggregated request usage entries (#4519)
fix(core): fail closed on empty tool arguments (#4545)
fix(core): strip created_by when replaying RunItems as input (#4568)
fix(core): strict_schema error message, REPL whitespace input, debug docstrings (#4600)
fix(core): max_turns no longer clobbers a tripped input guardrail exception in streaming (#4606)
fix(core): preserve serialized approval resume ownership (#4613)
fix(core): read tool args without Pydantic property shadowing (#4627)
fix(core): accept JSON Schema type arrays of object for tool outputs (#4647)
fix(core): honor End of File hunks when the file ends in a newline (#4661)
fix(core): preserve tuple annotations for variadic tool arguments (#4655)
fix(core): fix streamed response span losing response/input when consumer stops at completed event (#4692)
fix(core): apply **kwargs value annotation to each keyword value (#4714)
fix(core): reject **kwargs keys that collide with named tool parameters (#4674)
fix(core): reject fixed-length tuple annotations for variadic tool arguments (#4735)
fix(core): preserve Field constraints on variadic tool parameters (#4739)
fix(core): close model providers created by Runner (#4785)
fix(core/voice): honor OpenAI provider options over default clients (#4530)
fix(chat-completions): merge a streamed turn's message into its pending tool-call message (#4728)
fix(chat-completions): raise ModelBehaviorError on truncated empty completions (#4513)
fix(chat-completions) reject unpaired function outputs in Chat Completions (#4699)
fix(extensions): skip AdvancedSQLiteSession usage store when the branch has no turn (#4822)
fix(extensions): nest extra_body on the any-llm chat path (#4544)
fix(mcp): deep-copy cached tools before returning them (#4525)
fix(mcp): clear active MCP servers after cleanup (#4586)
fix(mcp): deduplicate managed servers (#4591)
fix(realtime): advance crossed guardrail thresholds (#4590)
fix(realtime): preserve item status on retrieved conversation items (#4598)
fix(sandbox): finish dependency cleanup on cancellation (#4607)
fix(sandbox): keep unbounded UnixLocal workspace I/O off the event loop (#4700)
fix(sandbox): preserve UTF-8 boundaries in Cloudflare SSE (#4707)
fix(sandbox): clean up PTY startup cancellation (#4750)
fix(sandbox): settle PTY output before cleanup (#4738)
fix(sandbox): preserve workdir for shell command lists (#4915)
fix(sessions): recover failed resumed Session writes before model calls (#4630)
fix(sessions): recover failed resumed Session writes on a renewed interruption (#4650)
fix(sessions): persist resumed tool guardrail results (#4654)
fix(sessions): recover resumed handoffs after session append failures (#4725)
fix(sessions): settle conversation deletion before propagating cancellation (#4790)
fix(sessions): preserve concurrent writes during compaction (#4736)
fix(sessions): reject resuming a run whose accepted terminal output was not persisted (#4698)
fix(sessions): preserve Session transformations during generation tracking (#4917)
fix(tracing): flush buffered data after tracing is disabled (#4528)
fix(tracing): preserve response IDs in redacted traces (#4641)
fix(tracing): record the tool output on approval-gated function spans (#4866)
fix(voice): support custom OpenAI TTS voice IDs (#4541)
fix(voice): forward streamed STT language and prompt (#4574)
fix(voice): honor client config for streamed STT (#4575)
fix(voice) reject ignored explicit-client options (#4527)
fix(voice): include current OpenAI TTS voices (#4535)
fix(voice): use monotonic STT event deadlines (#4593)
fix(voice): support context in single-agent workflow (#4636)
fix(voice): enforce public Voice class state coverage (#4644)
fix(voice): redact STT prompts from traces (#4663)
fix(voice): redact TTS instructions from speech spans (#4676)
fix(voice): accept every NumPy spelling of a supported TTS dtype (#4778)
fix(voice): wake stream when producer is cancelled (#4825)
fix(visualization): preserve nodes with duplicate names (#4512)
refactor: extract RunState agent graph identity (#4876)
refactor: share provider generation-span population (#4877)

Documentation & Other Changes

docs: document v0.22.0 behavior changes (#4522)
docs: fix wording in handoff example prompts (#4520)
docs: preserve English heading anchors in translated pages (#4580)
docs: refresh tracing integration links (#4634)
docs: clarify capability visibility and authorization (#4642)
docs: clarify database driver installation for SQLAlchemy sessions (#4743)
docs: skip reference pages on Windows (#4761)
docs: clarify requested state consistency guarantees (#4903)
docs: make the encrypted session quick start self-contained (#4909)
fix: freeze the public voice API contract (#4578)
fix: enforce public type alias contract coverage (#4595)
fix: route verification changes and require confirmed docs-only pushes (#4880)
fix: propagate the serial test runner's exit code on Windows (#4771)
fix: harden PyPI publishing and require manual release tags (#4726)
fix: require complete policy for new public TypedDicts (#4900)
fix: simplify verification and stabilize sandbox tests (#4916)
fix: consolidate Docker-backed integration tests (#4667)
chore: run repository skill tests in dedicated CI (#4881)
refactor: separate release contract verification responsibilities (#4878)
perf: reduce async stability command startup overhead (#4874)
test: make async progress and trace-worker tests deterministic (#4875)
test: organize Realtime session tests by responsibility (#4879)
test(sandbox): skip unavailable Windows symlinks (#4853)
release: 0.22.1 (#4576)

New Contributors

@Chair403 made their first contribution (#4520)
@green3sf made their first contribution (#4519)
@tandede made their first contribution (#4512)
@seanxuu made their first contribution (#4564)
@simpleqt made their first contribution (#4600)
@shoemoney made their first contribution (#4606)
@shoutoutuoadi325 made their first contribution (#4598)
@ayaangazali made their first contribution (#4650)
@lllakshit made their first contribution (#4661)
@Excelius-Wang made their first contribution (#4655)
@XuQuanxin04 made their first contribution (#4692)
@Hughhhhcoder made their first contribution (#4707)
@rajarshidattapy made their first contribution (#4674)
@mmjerge made their first contribution (#4728)
@subhashpolisetti made their first contribution (#4735)
@rioyu123 made their first contribution (#4822)
@Nikhils-G made their first contribution (#4778)
@MohammedAlkindi made their first contribution (#4771)
@Ayushraj06-bit made their first contribution (#4698)
@rksharma-owg made their first contribution (#4903)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.22.0...v0.22.1

v0.22.0

August 19, 2026

Key Changes

Version 0.22.0 is a minor release because it adds substantial runtime hardening and tightens an existing provider configuration contract. Applications that combine an explicit openai_client with organization or project must move those values to the AsyncOpenAI client.

Highlights:

Redacts terminal function-tool output rejected by agent output guardrails from replayable and persisted SDK state.
Raises ModelBehaviorError for non-streaming Responses with terminal status failed or incomplete.

Rejects conflicting provider options when OpenAIProvider receives an explicit client.
Isolates usage accounting between independent RunState checkpoints while preserving nested-agent aggregation.
Expands agents registered through handoff(agent) in generated graphs.
Clarifies the existing shallow-copy behavior of Agent.clone() and RealtimeAgent.clone().

What's Changed

fix(core): redact blocked tool outputs from replay state (#4507)
fix(core): reject ignored explicit-client options for OpenAIProvider (#4497)
fix(core): preserve Griffe logger inheritance (#4494)
fix(core): reject terminal failed/incomplete responses in non-streaming get_response by @weike-zhang in github.* * fix(core): isolate usage between RunState checkpoints by @chiruu12 in github.com/openai/openai-agents-python/pull/4479 fix(sandbox): require apply_patch update hunks (#4470)
fix(sandbox): enforce Windows mypy compatibility (#4499)
fix(tracing): respect model-data logging redaction for record_model_error_on_span (#4496)
fix(tracing): clean up processors after tracing is disabled (#4502)
fix(visualization): expand handoff() targets in agent graphs (#4517)

Documentation & Other Changes

docs: document v0.21.1 runtime behavior (#4460)
docs: correct Agent.clone list attribute semantics (#4474)
docs: add testing resources to llms indexes (#4509)
ci: align Python version coverage (#4475)
test: use sys.executable instead of tee for the stdio placeholder command (#4478)
fix: keep Codex verification for development sandboxed by @seratch in github.com/openai/openai-agents-python/pull/4508 com/openai/openai-agents-python/pull/4516
release: 0.22.0 (#4523)

New Contributors

@li2631026381-alt made their first contribution (#4470)
@thegoodengineer made their first contribution (#4474)
@teachershuang made their first contribution (#4509)
@weike-zhang made their first contribution (#4516)
@chiruu12 made their first contribution (#4479)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.21.1...v0.22.0

v0.21.1

August 17, 2026

What's Changed

feat(core): add model call timeouts (#4428)
feat(sandbox): add run-scoped sandbox working directories (#4427)
feat(sandbox): allow Docker sandboxes to disable networking (#4452)
feat(sandbox): add Modal sandbox resource options (#4455)
fix(core): honor exact call approval decisions (#4447)

fix(core): count Responses requests without usage (#4453)
fix(core): close all MultiProvider children after failures (#4438)
fix(core): reject partially matched stacked anchors (#4431)
fix(chat-completions): Chat Completions reasoning replay (#4432)
fix(realtime): truncate audio at zero elapsed time (#4457)
fix(realtime): end iteration after clean server close (#4461)
fix(sessions): prevent advanced SQLite structure table conflicts (#4454)
fix(sessions): include compaction usage in run totals (#4446)
fix(sandbox): validate view_image raster content (#4462)
fix(sandbox): keep model paths POSIX-normalized (#4416)
fix(sandbox): normalize apply_patch paths as POSIX (#4437)

Documentation & Other Changes

docs: updates for v0.21.0 release (#4381)
docs: list Tuning Engines tracing integration (#4440)
fix: update cffi lock for Python 3.14 (#4448)
release: 0.21.1 (#4467)

New Contributors

@Coiggahou2002 made their first contribution (#4431)
@fszcd made their first contribution (#4438)
@cerebrixos made their first contribution (#4440)
@Filimoa made their first contribution (#4455)
@koadegno made their first contribution (#4452)
@Chirag6722 made their first contribution (#4457)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.21.0...v0.21.1

v0.21.0

August 15, 2026

Key Changes

This minor release does not introduce a known breaking SDK behavior change. The minor version bump is for the new provider-neutral testing APIs and the OpenAI Python v3 compatibility update.

Highlights:

Added agents.testing, agents.realtime.testing, and agents.voice.testing utilities for deterministic Agent, Sandbox, Realtime, and Voice workflow tests without provider requests.
Updated OpenAI provider compatibility to openai>=3.0.0,<4, including HTTPX2-aware request, response, transport, and exception handling.

Hardened RunState interruption snapshots, recursive agent-tool approvals, max-turn finalization, streaming cleanup, and sensitive-error redaction.
Improved MCP lifecycle snapshot isolation and added configurable retry backoff ceilings.
Added Sandbox Runloop existing-secret support and tightened view-image path grants.
Added stricter Voice validation for invalid channels, frame rates, incomplete multichannel frames, and non-finite audio rates.

What's Changed

feat: support OpenAI Python 3 and HTTPX2 (#4380)
feat: add scripted model test utilities (#4362)
fix: freeze public testing module contracts (#4386)
fix: freeze public testing API state contracts (#4404)
fix(core): preserve scripted annotation streaming across Python SDK releases (#4422)
fix(core): isolate interruption results (#4384)
fix(core): close the model stream when a streamed turn ends in a terminal failure (#4366)
fix(core): redact tool output value from output-type validation errors (#4396)
fix(core): align Responses parallel tool calls with converted tools (#4405)
fix(core): max-turn handler session semantics (#4412)
fix(core): detach RunState interruption snapshots (#4409)
fix(core): isolate RunState checkpoint tool decisions (#4413)
fix(core): resume recursive agent tool approvals (#4414)
fix(mcp): stop handing the tools cache to callers (#4424)
fix(mcp): protect manager lifecycle state snapshots (#4407)
fix(mcp): isolate manager lifecycle results (#4368)
fix(mcp): add configurable retry backoff ceiling (#4379)
fix(realtime): handle non-finite audio rates (#4419)
fix(sandbox): expose the scripted sandbox session type (#4406)
fix(sandbox): apply stacked anchors sequentially (#4369)
fix(sandbox): snapshot HTTP proxy headers (#4397)
fix(sandbox): snapshot per-op audit policies (#4398)
fix(sandbox): honor view_image extra path grants (#4417)
fix(sessions): handle zero conversation history limits (#4365)
fix(voice): honor WAV sample width (#4361)
fix(voice): reject incomplete multichannel audio frames (#4370)
fix(voice): reject non-positive audio channels (#4372)
fix(voice): reject non-positive audio frame rates (#4382)
fix(voice): stop buffering audio when audio tracing is disabled (#4411)
fix(extensions): gate AnyLLM parallel tool calls on converted tools (#4363)
fix(extensions): preserve resume argument ordering (#4400)
fix(extensions): let managed_secrets reference existing Runloop secrets (#4378)

Documentation & Other Changes

docs: synchronize v0.20.0 features (#4280)
docs: clarify PGP key location (#4371)
test: order test spans by start sequence, not by started_at alone (#4392)
release: 0.21.0 (#4387)

New Contributors

@FU-max-boop made their first contribution (#4361)
@weivwang made their first contribution (#4363)
@jaideeppyne made their first contribution (#4371)
@hansu650 made their first contribution (#4372)
@xumaple made their first contribution (#4378)
@viyatb-oai made their first contribution (#4400)
@ErenAta16 made their first contribution (#4392)
@apcha-oai made their first contribution (#4422)
@sylvesterkaczmarek made their first contribution (#4417)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.20.0...v0.21.0

v0.20.0

August 11, 2026

Key Changes

Version 0.20.0 is a minor release because it changes the implicit default model and includes a potentially breaking MCP dependency migration for applications with customized local HTTP transports. MCP v1 remains supported, and affected applications can migrate to httpx2 or pin mcp<2.

Highlights:

The default model is now gpt-5.6-luna; explicit models, run-level overrides, and OPENAI_DEFAULT_MODEL continue to take precedence.
Local MCP connections support MCP Python SDK v1 and v2 across stdio, SSE, and Streamable HTTP transports.

Applications using custom MCP HTTP authentication or client factories must use the HTTP types owned by the installed MCP major version, or pin mcp<2.
RunState.add_input() can stage durable user input before a resumed model call, with guardrail, persistence, and serialization support.
Sandbox mount validation adds explicit credential-exposure acknowledgements and preserves redacted error contracts without serializing credential authority.
Realtime input transcription supports the GA transcription settings for gpt-live-transcribe, gpt-transcribe, and gpt-realtime-whisper.

What's Changed

feat: use GPT-5.6 Luna as the default model (#4282)
feat: add durable pending input to RunState (#4325)
feat(mcp): support MCP Python SDK v1 and v2 (#4106)
feat(sessions): pass run context to custom sessions (#4209)
feat(realtime): support GA transcription options (#4351)
feat: preserve raw usage payloads (#4279)
feat: allow applications to approve unsafe replays (#4319)
fix: falsy optional reference handling (#4305)
fix: prevent queue consumer deadlocks (#4201)
fix: publish completed streamed guardrail results on failure paths (#4223)
fix: annotate the bare tool guardrail decorator overloads (#4238)
fix: tool approval is not honored on resume when Runner.run is given a context (#4245)
fix: redact JSON validation errors (#4211)
fix: copy raw_responses when building a RunState (#4237)
fix: keep empty turns in the nested conversation history (#4230)
fix: keep tool guardrail results when a resumed run interrupts again (#4239)
fix: work on copies of the lists a resumed run adopts from RunState (#4251)
fix: strip placeholder item IDs without provider_data on the Responses path (#4266)
fix: bind tool approvals to concrete invocations (#4257)
fix: normalize optional fields in tool invocation identity (#4289)
fix: count requests when providers omit usage (#4290)
fix: suppress pydantic serializer warnings (#4291)
fix: keep FunctionTool subclasses copyable (#4311)
fix: preserve streamed guardrail session state (#4312)
fix: keep acknowledged safety checks serializable after restore (#4316)
fix: preserve default-valued fields in serialized tool output (#4307)
fix: strip output-only created_by when replaying model output as input (#4308)
fix: preserve local shell outputs across RunState resume (#4320)
fix: serialize containers of models and dataclasses as structured data (#4339)
fix: reject schemas that exceed safe recursion depth (#4358)
fix: reject unsafe strict-schema ref siblings (#4356)
fix(sandbox): reject unsafe mount credential configurations (#4255)
fix(extensions): settle snapshot directory mount transitions for Modal (#4315)
fix(sandbox): preserve sandbox error contracts during mount redaction (#4344)
feat(sandbox): add explicit mount credential exposure acknowledgements (#4321)
fix(sandbox): cancel sibling env resolvers when one fails (#4195)
fix(sandbox): encode Blaxel terminal WebSocket URL query values (#4217)
fix(sandbox): stop splitting Cloudflare SSE events at chunk boundaries (#4215)
fix(sandbox): keep move_to when coercing apply_patch operation mappings (#4242)
fix(sandbox): retain program items in memory rollouts (#4276)
fix(sandbox): restore archived file modes when extracting a workspace tar (#4287)
fix(sandbox): keep source entry metadata when lazily loading a skill (#4294)
fix(mcp): hosted MCP approval identity (#4256)
fix(mcp): keep MCP error content when structured output is enabled (#4224)
fix(mcp): build the active server list without re-consuming the iterable (#4235)
fix(mcp): preserve free-form MCP object schemas (#4310)
fix(mcp): serialize non-text content blocks as JSON instead of Python repr (#4338)
fix(mcp): serialize manager lifecycle operations (#4340)
fix(mcp): bound lifecycle and CI waits (#4342)
fix(chat-completions): keep url citations when converting chat completions output (#4222)
fix(chat-completions): assemble chat completions content parts in content index order (#4236)
fix(chat-completions): propagate the OpenAI request ID on the Chat Completions path (#4243)
fix(chat-completions): keep url citations on the streamed chat completions path (#4252)
fix(chat-completions): announce the chat completions assistant message once (#4275)
fix(chat-completions): convert input_file items that reference a file_id on the Chat Completions path (#4295)
fix(chat-completions): raise on audio output in the streamed chat completions path (#4309)
fix(chat-completions): omit parallel_tool_calls without tools on the Chat Completions path (#4359)
fix(sessions): release SQLite engine config entries when engines are collected (#4210)
fix(sessions): enforce closed state on SQLite session empty add_items (#4231)
fix(sessions): make session mutations atomic (#4212)
fix(sessions): preserve required program item ids for OpenAI conversations (#4253)
fix(sessions): apply the reasoning item id policy to stored session history (#4278)
fix(sessions): preserve DaprSession created_at across writes (#4213)
fix(sessions): strip placeholder item IDs before Conversations persistence (#4288)
fix(sessions): preserve falsey compaction decision hooks (#4299)
fix(sessions): restore session history when compaction replacement is cancelled (#4298)
fix(sessions): prune orphaned tool outputs from limited sessions (#4324)
fix(realtime): apply tool call item updates to session history (#4284)
fix(realtime): preserve falsey custom models (#4286)
fix(realtime): compute G.711 audio length for typed and mapping format spellings (#4292)
fix(voice): forward TTSModelSettings.speed to the OpenAI speech API (#4220)
fix(voice): keep the word separator when flushing streamed sentences (#4227)
fix(voice): start the dispatcher when a session ends with no turns (#4259)
fix(voice): report transcription session close failures to the consumer (#4343)
fix(tracing): release the trace scope when a generator is closed (#4221)
fix(tracing): release the span scope when a generator is closed (#4233)
fix(tracing): catch only the context reset on generator close (#4232)
fix(extensions): harden tool output trimming contracts (#4204)
fix(extensions): forward prompt_cache_retention on the any-llm Responses path (#4248)
fix(extensions): resolve the any-llm default model at call time (#4219)
fix(extensions): surface content filter refusals on the any_llm chat path (#4234)
fix(extensions): omit litellm's parallel_tool_calls without tools (#4330)

Documentation & Other Changes

docs: correct nonexistent guardrail type names (#4218)
docs(tracing): fix custom span output example (#4196)
docs: voice quickstart also needs sounddevice (#4250)
docs: improve translation source clarity (#4306)
perf: run serial tests alongside xdist (#4197)
perf: add source-only typecheck target (#4200)
perf: accelerate developer checks (#4258)
test: harden release compatibility contracts (#4297)
ci: check prospective release contracts before merge (#4347)
fix: make release API contract promotion policy-driven (#4349)
fix: freeze Runloop platform properties (#4355)
test: isolate released API source validation (#4350)
release: 0.20.0 (#4348)

New Contributors

@XSAM made their first contribution (#4196)
@abhay-codes07 made their first contribution (#4217)
@ColebyPearson made their first contribution (#4250)
@Luccacvb made their first contribution (#4252)
@ojassharma7 made their first contribution (#4245)
@nothariharan made their first contribution (#4298)
@ribhavjain made their first contribution (#4316)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.19.4...v0.20.0

v0.19.4

August 5, 2026

What's Changed

fix: preserve completed tool guardrail results (#4180)
fix: redact invalid tool argument errors (#4182)
fix: defer non-stream session saves until output guardrails (#4184)
fix: honor resolved status before policy checks (#4183)
fix: cancel sibling work after concurrent failures (#4185)

fix: surface non-streaming content-filter refusals (#4188)
fix(mcp): derive streamable HTTP retry backoff from backoffs taken (#4174)
fix(realtime): clean up failed connection attempts (#4189)
fix(tracing): mark non-streaming agent span failures (#4191)
fix(sandbox): enforce token output budgets (#3934)
fix(sandbox): single-flight cached dependency factories (#4178)
fix(sessions): enforce closed state in MongoDBSession (#4176)
fix(sessions): preserve repeated history provenance (#4181)
fix(sessions): skip conversation creation on empty add_items (#4190)
fix(sessions): reject reused branch IDs when creating a branch (#4186)
fix(extensions): preserve streamed provider thinking blocks (#4177)

Documentation & Other Changes

perf: speed up the test suite (#4171)
test: make parallel guardrail overlap deterministic (#4187)
test: make async tool and guardrail tests deterministic (#4192)
test: make parent cancellation tests deterministic (#4193)

New Contributors

@rxits made their first contribution (#4174)
@cosin2077 made their first contribution (#3934)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.19.3...v0.19.4

v0.19.3

August 4, 2026

What's Changed

fix: resolve agent tool name collisions consistently (#4137)
fix: reconcile resumed tool name collisions (#4145)
fix: persist the max-turns handler output to the session (#4160)
fix: report output guardrail results when a tripwire aborts the run (#4090)

fix: replace closed default loop in run_sync (#4102)
fix: honor falsey custom output extractors for agents as tools (#4088)
fix: report tool guardrail results for streamed runs (#4097)
fix: preserve approved tool output on streamed resume (#4126)
fix: normalize typeless strict object schemas (#4139)
fix: synchronize after-turn cancellation with event consumption (#4130)
fix: keep input item order when collapsing duplicates (#4140)
fix: stop emitting handoff calls as streamed tool_called events (#4146)
fix: preserve tool call and output order when deduplicating inputs (#4147)
fix: honor falsey handoff input filters (#4153)
fix: define explicit zero-value contracts (#4101)
fix: keep committed tool session records when a streamed output guardrail trips (#4148)
fix(mcp): auto-paginate tool and prompt listings (#4094)
fix(chatcmpl): clear pending thinking blocks when flushing an assistant message (#4089)
fix(sandbox): remove apply_patch move source as the bound user (#4100)
fix(sandbox): harden default snapshot path resolution (#4141)
fix(sessions): enforce closed state in AsyncSQLiteSession (#4109)
fix(sessions): avoid creating remote conversation on uninitialized clear_session (#4111)
fix(sessions): roll back a failed SQLiteSession insert (#4163)
fix(realtime): apply output guardrails to text deltas (#4124)
fix(realtime): clamp interrupt truncation to received audio (#4122)
fix(realtime): scope delayed audio guardrail interruption (#4135)
fix(voice): clean up tasks when streams close early (#4131)
fix(voice): finish STT event handling after listener errors (#4170)
fix(tracing): name streamed task spans after the run's own workflow (#4167)
fix(extensions): keep trimmer's definition names and instance data in trimmed schemas (#4110)
fix(extensions): release AnyLLM provider streams and preserve completed runs (#4133)
fix(extensions): send AnyLLM Responses reasoning as a mapping (#4138)
fix(extensions): record model-call failures on the provider's own span (#4143)
fix(extensions): let an in-flight provider stream close finish after cancellation (#4156)
fix(extensions): preserve thinking blocks for replay (#4157)

Documentation & Other Changes

docs: fix spelling in GPT-5 example (#4168)
chore(ci): preserve cache pruning with setup-uv v9 (#4103)
test: stabilize tracing atexit timeout coverage (#4104)

New Contributors

@n33levo made their first contribution (#4088)
@omidsaffari made their first contribution (#4153)
@PranavMishra28 made their first contribution (#4143)
@wesleyzhangwq made their first contribution (#4168)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.19.2...v0.19.3

v0.19.2

August 1, 2026

What's Changed

feat: expose original callable through wrapped (#4038)
fix: report input guardrail results when a tripwire aborts the run (#4071)
fix: consolidate same-exception re-raises into bare raise across all modules (#4023)
fix(sandbox): preserve tagged EnvValue subclasses (#4039)

fix(modal): reject ephemeral paths during tar hydration (#4045)
fix(mcp): redact MCP prompt and resource transport errors (#4067)
fix(mcp): redact URL credentials from SDK errors (#4015)
fix(mcp): redact URL credentials from tracing and tool metadata (#4020)
fix(mcp): redact direct MCP cleanup transport errors (#4078)
fix(mcp): clean failed servers before reconnecting (#3939)
fix(mcp): nested MCP cleanup error redaction (#4049)
fix(realtime): preserve raw server event payloads (#4062)
fix(memory): count valid SQLAlchemy and MongoDB session items for positive limits (#4032)
fix(memory): count valid AdvancedSQLiteSession items for positive limits (#4031)
fix(memory): count valid Redis and Dapr session items for positive limits (#4033)
fix(memory): enforce closed state in Redis and Dapr sessions (#4035)
fix(extensions): keep tool parameters named like schema keywords (#4036)
fix(extensions): close the LiteLLM provider stream on exit (#4066)
fix(extensions): preserve completed LiteLLM streams on cleanup failure (#4077)
fix(voice): propagate iterator cancellation (#4040)
fix(voice): break out of audio dispatch loop when a stream task signals session_ended (#4044)
fix(voice): block audio dispatcher while idle (#4061)
fix(tracing): use monotonic export deadlines (#4063)

Documentation & Other Changes

docs: correct the documented Chat Completions store default (#4074)

New Contributors

@chinmayv095 made their first contribution (#4032)
@jstar0 made their first contribution (#3939)
@Kaif10 made their first contribution (#4036)
@SawhneySatvik made their first contribution (#4035)
@GautamSharma99 made their first contribution (#4061)
@LHMQ878 made their first contribution (#4045)
@dfedoryshchev made their first contribution (#4074)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.19.1...v0.19.2

v0.19.1

July 29, 2026

What's Changed

feat(sandbox): support native host paths in path grants (#4009)
fix: redact Realtime audio format diagnostics (#3992)
fix: redact Blaxel unmount paths in logging (#3993)
fix: retry pre-response WebSocket server errors (#3991)

fix(run): cancel the parallel input-guardrail task when the model turn fails (#3982)
fix(run): allow empty streamed model input (#3995)
fix(models): route falsey mapped providers (#3996)
fix(memory): count valid SQLite session items for positive limits (#4001)
fix(run): count streamed retries when terminal usage is missing (#4002)
fix(run): cancel streamed models when input guardrails fail (#4004)
fix: preserve zero Blobfuse attribute cache timeout (#4006)
fix(tracing): enforce max_batch_size during force_flush and shutdown in BatchTraceProcessor (#3985)
fix(agent-tools): honor falsey input builders (#4007)
fix: cancel sibling enablement checks on failure (#4005)

Documentation & Other Changes

docs: updates for 0.19.0 (#3872)
docs: fix a URL in sandbox example code (#3987)
docs: repair tracing integration links (#3986)
docs: use decorators module throughout examples (#3946)

New Contributors

@dk3yyyy made their first contribution (#3991)
@ShawnSiao made their first contribution (#3987)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.19.0...v0.19.1

v0.19.0Breaking Change

v0.19.0

July 27, 2026

Key Changes

This minor release does not introduce a breaking change. The minor version bump reflects a significant new OpenAI Responses feature area: Programmatic Tool Calling.

Highlights:

Added agents.tool.ProgrammaticToolCallingTool, which lets supported OpenAI Responses models generate JavaScript to coordinate eligible tools. It supports per-tool allowed_callers, structured function-tool outputs, and integration with Runner streaming, guardrails, approvals, sessions, and RunState. See Programmatic Tool Calling for setup and constraints.

Added the public agents.decorators module and the shorter @tool alias alongside the existing function and guardrail decorators. Function tools now also support async callable objects.
SDK configuration now consistently accepts either typed settings objects or dictionaries across agents, runs, models, sessions, sandboxes, and voice pipelines, with validation for unknown settings.
Hardened error and diagnostic logging across models, tools, MCP, Realtime, sessions, sandboxes, and tracing to avoid exposing raw sensitive payloads while preserving useful debugging context.
Improved AnyLLM, LiteLLM, and Chat Completions compatibility, preserved session history across model retries, and added retries for WebSocket overloads that occur before a response starts.
Added VercelCloudBucketMountStrategy. Mounted sessions exclude bucket contents from workspace persistence and intentionally do not support dynamic mount changes or session resume.

What's Changed

feat: add Programmatic Tool Calling support (#3833)
fix: remove programmatic transcripts from handoff tool filtering (#3879)
fix: encode structured programmatic tool errors as JSON (#3932)
feat: consistently accept typed objects and dictionaries for SDK configuration (#3917)
feat: add tool decorator alias (#3920)
feat(sandbox): add Vercel cloud mount strategy (#3899)
fix: retry pre-response WebSocket overload errors (#3978)
fix: harden sensitive runtime logging (#3938)
fix: redact Realtime and RunState diagnostics (#3948)
fix: stop leaking raw exceptions in model + tool error logs (#3910)
fix: preserve callable function tool compatibility (#3959)
fix: support async callable objects as function tools (#3949)
fix: partition nested handoffs history ownership (#3823)
fix: summarize programmatic transcripts during nested handoffs (#3878)
fix: improve AnyLLM and LiteLLM provider compatibility (#3930)
fix: improve provider compatibility and preserve session history on retries (#3931)
fix: fail closed on invalid callable approval arguments (#3867)
fix: classify lazy skill read probes correctly (#3893)
fix: reuse the verbose stdout logging handler (#3957)
fix: recognize typed easy input messages in Chat Completions (#3877)
fix: include device nodes when parsing ls output (#3951)
fix: preserve *args/**kwargs docstring descriptions in tool schemas (#3956)
fix: compare inspect sentinels by identity in function_schema (#3961)
fix: parse ls output with SELinux security-context marker (#3904)
fix: preserve dot-prefixed skip paths in Modal tar workspace excludes (#3905)
fix: cleanup cancelled servers during MCP connect failure (#3919)
fix: await async callable-object dynamic instructions (#3942)
fix: await async callable-object callbacks (#3944)
fix: Blaxel's shell-quote interpolated FUSE mount options (#3873)
fix: escape multiline DOT names in visualization (#3898)
fix: redact raw message payload from realtime agents' conversion-failure log (#3907)
fix: encode streamed float32 audio as PCM16 in voice handling (#3916)
fix: redact MCP tool-call and formatter errors from logs (#3918)
fix: parse Google docstrings whose Args: follows a section body (#3862)
fix: pin and verify rclone sandbox installs (#3911)
fix: reject empty additionalProperties mappings in strict_schema (#3927)
fix: send logprobs=True when top_logprobs is set when using LiteLLM (#3929)
fix: surface content-filter refusals when buffering streamed tool calls in chat completions (#3897)
fix: reject unsupported streamed STT audio dtypes (#3950)
fix: use last_agent property in pretty_print_run_result_streaming to avoid None crash (#3965)
fix: use last_agent property in RunResultStreaming._create_error_details (#3967)

Documentation & Other Changes

docs: document compact tracing hierarchy (#3839)
docs: clarify sandbox support on Windows (#3866)
docs: remove unnecessary RunContextWrapper wrapping in tool enabling example (#3869)
docs: remove unused Runner import in tracing docs (#3881)
docs: fix runnable Python examples (#3885)
docs: fix missing imports in dynamic instructions example (#3895)
docs: fix conversation example imports (#3903)
docs: fix API cross-reference targets (#3913)
docs: improve sandbox example runtime validation (#3880)
docs: fix streamed audio API rendering (#3940)
chore: add packaged live integration and provider regression coverage (#3936)
chore: update e2b versions (#3871)
chore: update FastAPI test dependency (#3974)
chore: isolate unit tests from ambient proxy settings (#3945)

New Contributors

@oldrobotdev made their first contribution (#3862)
@AAliKKhan made their first contribution (#3869)
@matthewlouisbrockman made their first contribution (#3871)
@Syed-Umer-Ali made their first contribution (#3895)
@hsusul made their first contribution (#3898)
@SHAI-Cheravgoyal made their first contribution (#3904)
@dimaosipa made their first contribution (#3910)
@FayezBast made their first contribution (#3916)
@gunjanjaswal made their first contribution (#3897)
@TheSaiEaranti made their first contribution (#3951)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.18.3...v0.19.0

v0.18.3

July 17, 2026

What's Changed

feat: make task and turn tracing spans configurable (#3834)
feat(realtime): track response usage in session context (#3812)
fix(memory): serialize OpenAI conversation session initialization (#3821)
fix(models): raise UserError for conflicting provider args instead of assert (#3809)

fix(handoffs): preserve user messages containing history wrappers (#3815)
fix(computer): isolate provider instances across concurrent runs (#3843)
fix(sandbox): avoid redundant E2B workspace root creation (#3845)
fix: preserve streamed session input across model retries (#3857)
fix: prevent stale prepared-item identity reuse (#3858)
fix: AdvancedSQLiteSession clear_session and pop_item metadata leaks (#3755)
fix: parse Google docstrings missing the blank line before a section (#3832)
fix: bound $ref expansion in strict JSON schema conversion (#3838)
fix: redact non-tool trace error details (#3848)

Documentation & Other Changes

docs: updates for hosted multi-agent support (#3789)
docs: make UserContext example runnable in Agents documentation (#3851)
chore: enable flake8-async for runtime source (#3813)

New Contributors

@Dhruva-Das made their first contribution (#3809)
@russeell made their first contribution (#3815)
@okaditya84 made their first contribution (#3755)
@sohumt123 made their first contribution (#3832)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.18.2...v0.18.3

v0.18.2

July 11, 2026

What's Changed

feat: support GPT-5.6 request controls (#3794)
feat: add hosted multi-agent beta support (#3788)
fix(sandbox): own Daytona PTY worker tasks (#3778)
fix(realtime): enqueue callback errors synchronously (#3777)
fix(realtime): use monotonic playback timing (#3776)

fix(sandbox): own Docker deferred cleanup tasks (#3779)
fix(sandbox): own Unix PTY fd close tasks (#3780)
fix(litellm): surface content-filter refusals instead of an empty turn (#3769)
refactor(sandbox): share core PTY output collection (#3796)
refactor(sandbox): share extension PTY output collection (#3797)
refactor(sandbox): share E2B rclone setup (#3798)
refactor(sandbox): share Runloop rclone setup (#3799)
refactor: share retry error metadata extraction (#3800)
refactor: share retry-after parsing (#3801)

Documentation & Other Changes

fix: serialize model-backed rollout interruptions as dicts (#3790)
chore: enable G004 logging lint rule (#3802)
chore: enable RUF012 for runtime source (#3803)
chore: remove unused noqa directives (#3804)
chore: exempt OpenAI package from dependency cooldown (#3792)

New Contributors

@Otis0408 made their first contribution (#3790)
@seanturner83 made their first contribution (#3769)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.18.1...v0.18.2

v0.18.1

July 10, 2026

What's Changed

feat: add GPT-5.6 model defaults and migrate examples (#3774)
fix: support cache-write usage across OpenAI Python versions (#3773)
fix(realtime): make session cleanup deterministic (#3767)
fix: preserve nested tool state during restoration (#3753)

fix: close Chat Completions streams on early exit (#3689)
fix(sessions): handle list content in AdvancedSQLiteSession browsing helpers (#3761)
fix(models): accumulate streamed logprobs in place to avoid O(n^2) copies (#3762)
fix: send logprobs=True when top_logprobs is set on Chat Completions (#3763)

Documentation & Other Changes

docs: updates for v0.18.0 (#3741)
docs(realtime): fix RealtimeRunner context docstring (#3748)
docs: clarify agent tool state options (#3754)
test(items): document refusal None invariant (#3751)

New Contributors

@william-xue made their first contribution (#3754)
@winklemad made their first contribution (#3763)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.18.0...v0.18.1

v0.18.0

July 7, 2026

RealtimeAgent's default is now gpt-realtime-2.1

Since this version, the default model for RealtimeAgents is gpt-realtime-2.1: developers.openai.com/api/docs/models/gpt-realtime-2.1

What's Changed

feat: update default realtime model to gpt-realtime-2.1 (#3740)
feat: add Unicode storage option to SQLAlchemySession (#3746)
fix(visualization): keep fillcolor on handoff nodes by merging style attributes (#3744)

Documentation & Other Changes

docs: updates for v0.17.8 release (#3737)

New Contributors

@comp made their first contribution (#3744)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.8...v0.18.0

v0.17.8

July 7, 2026

What's Changed

feat: add invalid final output recovery handler (#3736)
fix: propagate realtime session iterator cancellation (#3686)
fix: redact realtime validation failure logs (#3687)
fix: preserve non-dict Mapping values in _to_dump_compatible (#3700)

fix: escape quotes and backslashes in DOT names for visualization (#3712)
fix: enforce strict Pydantic validation when strict_json_schema=True + handoffs (#3724)
fix: fix an issue with length-frame exec-stdin writes within a sandbox (#3719)

Documentation & Other Changes

docs: add DProvenanceKit to external tracing processors list (#3726)
docs: add sandbox examples to examples index (#3731)
test: improve coverage for stream and sandbox edge cases (#3730)

New Contributors

@fallintoplace made their first contribution (#3686)
@anxkhn made their first contribution (#3700)
@Om-Borse26 made their first contribution (#3724)
@imran31415 made their first contribution (#3719)
@Therealdk8890 made their first contribution (#3726)
@saime428 made their first contribution (#3731)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.7...v0.17.8

v0.17.7

June 24, 2026

What's Changed

feat: expose configurable websocket max_size limit (#3645)
feat: add buffered Chat Completions tool-call streaming (#3506)
fix: reduce sandbox sink buffering and spool timeouts (#3642)
fix: #3346 clean up branch-only messages when deleting branches (#3347)

fix: #3348 make AdvancedSQLiteSession add_items atomic (#3349)
fix: cancel sibling guardrail tasks when one raises (#3239)
fix: skip needs_approval_checker when status resolved in _collect_runs_by_approval (#3259)
fix: validate ls special permission bits by position (#3420)
fix: gate remote-mount edit guidance by mode (#3423)
fix: remove dependency on types-requests (#3509)
fix: empty list/tuple tool output dropped via all([]) == True (#3554)
fix: wake PTY output collection on process exit (E2B) (#3610)
fix: avoid stale object-id dedupe in server conversation tracker (#3621)
fix: report effective Blaxel timeouts (#3643)
fix: prevent ambiguous Realtime multi-agent tool dispatch (#3441)
fix: add hint to duplicated MCP server tool name error message (#3678)
fix: recursively extract HTTP errors from nested ExceptionGroups (#3556)

Documentation & Other Changes

docs: #3461 changes for tool_not_found_behavior option (#3462)
docs: changes for #3487 feature addition (#3488)
docs: fix OpenAI capitalization in auto-generated ref titles (#3646)
docs: add SDK maintainer references and review guidance (#3676)

New Contributors

@rouge8 made their first contribution (#3509)
@vidigoat made their first contribution (#3554)
@rohitrastogi made their first contribution (#3610)
@chutch made their first contribution (#3621)
@he-yufeng made their first contribution (#3643)
@anneheartrecord made their first contribution (#3645)
@2830500285 made their first contribution (#3642)
@atimothee made their first contribution (#3646)
@incoffeemonster made their first contribution (#3506)
@wustwyh made their first contribution (#3678)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.6...v0.17.7

v0.17.6

June 19, 2026

What's Changed

feat: add pre-approval tool input guardrails (#3487)
feat: add SDK-only custom data for tool outputs (#3486)
fix: enforce the documented strict JSON-compatible contract for #3486 (#3657)
fix: suppress handoff whitespace tool-name warnings (#3652)

Documentation & Other Changes

docs: fix typo in sandbox guide (#3628)

New Contributors

@siddiksawani made their first contribution (#3657)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.5...v0.17.6

v0.17.5

June 11, 2026

What's Changed

fix: expose sandbox error retryability (#3581)
fix: #3512 type tool-end hook results as object (#3518)
fix: use tuple form for SpeechGroupSpanData __slots__ (#3534)
chore: bump Modal sandbox extra to 1.4.3 (#3538)

Documentation & Other Changes

docs: add MongoDB session example under examples/memory (#3036)

docs: add missing space in MCP params docstrings (#3535)
docs: fix docstring typo in stdio params env description (#3557)
docs: fix two docstring grammar errors in tool.py (#3543)
docs: add Latitude to external tracing processors list (#3577)
docs: tweak in usage doc (#3597)
docs: fix string concatenation typo in agent instructions (#3599)
docs: capitalization fix in tracing docs (#3602)
docs: fix subject-verb agreement in agent loop description (#3605)
test: add unit tests for run_demo_loop streaming, EOF, and empty-input paths (#3542)
test: add unit tests for _openai_retry helpers (77% -> 95% coverage) (#3544)

New Contributors

@jluocsa made their first contribution (#3534)
@jdoughty04 made their first contribution (#3538)
@guillemwilly made their first contribution (#3577)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.4...v0.17.5

v0.17.4

May 26, 2026

What's Changed

feat: support Realtime custom voice objects (#3473)
fix: #3459 add opt-in recovery for missing function tools (#3461)
fix: apply hardened http client default to MCP SSE transport (#3466)
fix: use non-None value for output in FunctionSpanData (#3475)

fix: add missing entries to span __slots__ (#3483)
fix: redact invalid JSON payload in ModelBehaviorError data (#3485)
fix: export more tracing related functions & types from agents (#3489)
fix: export MCPListToolsItem, ToolSearchCallItem, and ToolSearchOutputItem from agents (#3490)

New Contributors

@rmotgi1227 made their first contribution (#3475)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.3...v0.17.4

v0.17.3

May 19, 2026

What's Changed

fix: keep mountpoint credentials out of sandbox commands (#3429)
fix: unify memory optional dependency import errors (#3389)
fix: guard None text in text_message_output and add output guardrail count to RunErrorDetails (#3375)
fix: avoid mutating FunctionTool params_json_schema (#3382)

fix: avoid mutating codex output schema input (#3385)
fix: #3357 output schema names for Literal types (#3358)
fix: skip wait_for_status when Vercel sandbox is in a terminal state (#3410)
fix: filter hosted_tool_call types in remove_all_tools handoff filter (#3386)
fix: guard None text in ItemHelpers.extract_last_content (#3394)
fix: log exception when output guardrail raises instead of silently ignoring (#3411)
fix: reject relative sandbox workspace roots (#3422)
fix: normalize leading question marks in exposed port queries (#3424)
fix: #3363 honor short custom voice splitter chunks (#3364)
fix: runtime handling updates by @adrianbravo-oai @ioleksiuk (#3451)

Documentation & Other Changes

docs: add SDK review guidance (#3376)
docs: mark Agent.instructions as optional (#3384)
docs: translate all pages using new settings (#3392)
docs: document auto_previous_response_id (#3383)
docs: fix LiteLLM API reference redirect (#3444)
docs: fix duplicated word in usaspending glossary example (#3445)
chore: clean up CI jobs and update uv pin (#3400)
ci: harden release tag workflow (#3399)

New Contributors

@zhoufengen made their first contribution (#3375)
@hintz-openai made their first contribution (#3399)
@cty-ut made their first contribution (#3410)
@ynachiket made their first contribution (#3444)
@LeSingh1 made their first contribution (#3445)
@adrianbravo-oai made their first contribution (#3451)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.2...v0.17.3

v0.17.2

May 12, 2026

What's Changed

fix: #3268 fix OpenAI Conversations reasoning persistence (#3352)
fix: avoid auto response for unknown realtime tools (ref: #3287) (#3366)
fix: #3354 interrupt tracing retry backoff on shutdown (#3355)
fix: #3359 preserve local approval rejection reasons (#3360)

fix: #3361 honor session settings in AsyncSQLiteSession (#3362)
fix: #3310 avoid empty chat tool outputs (#3312)

Documentation & Other Changes

docs: clarify max_delay for retries works (#3350)
docs: normalize memory docstring cross-references (#3370)
docs: document sandbox archive limits after #3278 release (#3311)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.1...v0.17.2

v0.17.1

May 11, 2026

Sandboxes

fix: include sandbox provider error details (#3326)
fix: #3274 limit sandbox archive extraction (#3278)
fix: #3273 validate git repo subpaths (#3276)
fix: allow empty GitRepo subpaths as repository root (#3299)
fix: preserve GitRepo root subpath aliases (#3303)

Tracing

fix: make tracing shutdown best-effort on process exit (#3343)

fix: keep BatchTraceProcessor worker alive on exporter errors (#3216)
fix: guard no-op tracing span IDs (#3296)

Sessions

fix: #3267 preserve required hosted tool IDs in OpenAI conversation sessions (#3341)
fix: #3304 skip corrupt items during pop (sessions) (#3305)
fix: #3306 track MongoDB metadata timestamps (#3307)
fix: preserve created_at across writes (redis-session) (#3202)
fix: skip corrupt docs in MongoDBSession.pop_item (#3247)

Realtime Agents

fix: #3333 scope Realtime tool approvals by qualified key (#3340)
fix: #3286 send realtime output for unknown tool calls (#3287)
fix: #3284 wake realtime event iterators on close (#3285)
fix: preserve existing transcript over stale delta accumulator (#3214)
fix: expose max_output_tokens on RealtimeSessionModelSettings (#3223)
fix: validate RealtimeAgent fields in __post_init__ (#3234)
fix: skip invalid input_text parts in user input conversion (realtime) (#3243)
fix: raise UserError for input_type without on_handoff (realtime) (#3248)
fix: preserve output_audio content parts in output_item events (realtime) (#3230)
fix: treat None audio.input/audio.output as unset (realtime) (#3254)
fix: stop AudioInput.to_base64() from mutating caller's buffer (voice agents) (#3201)

Other core modules

fix: make chat completions response-feature validation opt-in (#3298)
fix: #3275 reject chat completions server state (#3279)
fix: #3282 reject unsupported Chat Completions reusable prompts (#3283)
fix: #3313 align multi-choice chat streams with strict validation (#3314)
fix: #3308 reject chat custom tool calls explicitly (#3309)
fix: #3270 validate model retry backoff settings (#3272)
fix: #3319 preserve nested handoff history content (#3320)
fix: #3280 streaming guardrail exception cleanup (#3281)
fix: #3288 normalize RunState guardrail payloads (#3289)
fix: #3315 align generic dict output schemas (#3316)
fix: #3317 return fresh empty strict schemas (#3318)
fix: #781 replace assertion in handoff() with UserError (#3339)
fix: preserve failed status across apply_patch operations (#3217)
fix: preserve existing request_usage_entries on Usage.add (#3213)
fix: await cancelled output guardrail tasks on tripwire (#3187)
fix: persist output_tokens_details when input details are None (#3227)
fix: drop reasoning items orphaned by dropped tool calls (#3207)
fix: skip CompactionItem silently in stream queue helper (#3224)
fix: await on_handoff callables with async __call__ (#3211)
fix: preserve tool guardrail results across handoffs in SingleStepResult (#3237)
fix: preserve last known response_id on conversation resume (#3245)
fix: isolate MCP strict schema conversion from non-strict fallback (#3199)
fix: exclude Computer instances from provider duck-typing (#3249)
fix: skip needs_approval_checker when status already resolved (#3229)
fix: export MCPToolCancellationError from top-level package (#3210)
fix: preserve chained $ref during sibling-key expansion (#3205)

Extensions

fix: avoid duplicating content and signed thinking blocks across parallel tool-call splits (any-llm) (#3261)
fix: avoid duplicating content and signed thinking blocks across parallel tool-call splits (litellm) (#3215)
fix: #3330 handle string tool trimmer allowlists (#3331)
fix: preserve HandoffInputData.input_items in remove_all_tools (#3253)

Documentation & Other Changes

docs: updates for v0.17.0 (#3188)
docs: add dapr to durable orchestration integrations (#3292)
docs: update MCP examples (#3342)
test: guard Responses transport extra kwargs with official client (#3295)
chore: improve examples auto-run coverage and artifact handling (#3328)
chore: improve automated example coverage and local service handling (#3297)

New Contributors

@yaron2 made their first contribution (#3292)
@0xSudoSSH made their first contribution (#3339)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.17.0...v0.17.1

v0.17.0

May 8, 2026

RealtimeAgent's default is now gpt-realtime-2

Since this version, the default model for RealtimeAgents is gpt-realtime-2: developers.openai.com/api/docs/models/gpt-realtime-2

Sandbox local source materialization change

In this version, sandbox local source materialization keeps LocalFile.src and LocalDir.src within the materialization base_dir unless the source path is covered by Manifest.extra_path_grants.

The base_dir is the SDK process current working directory when the manifest is applied; relative local sources are resolved from that directory, while absolute local sources must already be inside it or under an explicit grant. This closes a local artifact boundary issue, but it can affect applications that intentionally copy trusted host files or directories from outside that base directory into a sandbox workspace.Expand commentComment on line R24Resolved

To migrate, grant trusted host roots at the manifest level with SandboxPathGrant, preferably as read-only when the sandbox only needs to read those files:

from pathlib import Path

from agents.sandbox import Manifest, SandboxPathGrant
from agents.sandbox.entries import Dir, LocalDir

# This is an absolute host path outside the SDK process base_dir.
TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs")

manifest = Manifest(
    extra_path_grants=(
        # This host root is outside the SDK process base_dir, so the manifest must grant it.
        SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True),
    ),
    entries={
        # No grant is needed for local sources that stay under the SDK process base_dir.
        "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."),
        # This entry reads from the granted host root and copies it into the sandbox workspace.
        "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."),
        # Dir creates a sandbox workspace directory; it does not read from the host filesystem.
        "output": Dir(description="Generated artifacts."),
    },
)

Treat extra_path_grants as trusted application configuration. Do not populate grants from model output or other untrusted manifest input unless your application has already approved those host paths.

What's Changed

feat: default realtime sessions to gpt-realtime-2 (#3190)
fix: #3169 constrain local sandbox artifact sources to base dir (#3177)
fix: Responses context-management extra_args collision (#3185)

Documentation & Other Changes

Full Changelog: github.com/openai/openai-agents-python/compare/v0.16.1...v0.17.0

v0.16.1

May 7, 2026

What's Changed

fix: #3109 stabilize chat completions stream output indexes (#3176)
fix: #3168 validate MCP require_approval policies (#3179)
fix: #3116 restore session history after compaction replacement failures (#3117)
fix: #3171 reject corrupt Dapr session state updates (#3173)

fix: #3170 clean up git repo temp clones on failure (#3172)
fix: #3174 count valid encrypted session items for limits (#3175)
fix: reject non-object function tool input JSON (#3166)

Documentation & Other Changes

docs: updates for #3147 (#3148)
docs: add 0.16.0 changelog (#3153)
docs: document tool execution concurrency (#3164)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.16.0...v0.16.1

v0.16.0

May 7, 2026

Default model change

In this version, the SDK default model is now gpt-5.4-mini instead of gpt-4.1. This could affect agents and runs that do not explicitly set a model. Because the new default is a GPT-5 model, implicit default model settings now include GPT-5 defaults such as reasoning.effort="none" and verbosity="low".

The new default model should work better for most use cases (see the report at github.com/openai/openai-agents-python/pull/3147), but if you need to keep the previous default model behavior for some reasons, set a model explicitly on the agent or run config like Agent(name="Assistant", model="gpt-4.1"), or set the OPENAI_DEFAULT_MODEL environment variable.

Disable max_turns detection

This version adds a new option max_turns=None to disable the Agents SDK run turn limit while preserving the existing default of DEFAULT_MAX_TURNS (10) when max_turns is omitted.

Tool execution concurrency

This version adds a new SDK-side runtime configuration for local function tool execution concurrency: ToolExecutionConfig(max_function_tool_concurrency=...) on RunConfig, preserves default behavior when unset. The change keeps provider-side ModelSettings.parallel_tool_calls separate from SDK-side local execution scheduling.

Server-prefixed MCP tool naming

This version adds a new option include_server_in_tool_names to MCPConfig. When it is set to True, the SDK includes the MCP server name in the tool name to prevent tool name conflicts with other MCP servers.

agent = Agent(
    name="Assistant",
    mcp_servers=[my_mcp_server],
    mcp_config={"include_server_in_tool_names": True},
)

What's Changed

feat: switch the default model to a newer mini model (affecting only when a model is unset) (#3147)
feat: allow disabling max_turns with None (#3132)
feat: #1167 add opt-in server-prefixed MCP tool names (#3019)
feat: #1859 add runtime function tool concurrency config (#3152)
fix: #3104 stabilize chat completions tool call output indexes (#3161)
fix: reject external symlink targets during hydrate (#3094)
fix: make Permissions hashable to match User and Group (#3154)

Documentation & Other Changes

docs: realtime guardrail fallback behavior (#3157)

New Contributors

@mavrickdeveloper made their first contribution (#3019)
@mindbomber made their first contribution (#3157)

Full Changelog: github.com/openai/openai-agents-python/compare/v0.15.3...v0.16.0

Showing 30 of 63