Skip to content

Release history

openai-agents-python releases

A lightweight, powerful framework for multi-agent workflows

Back to tool Latest release

All releases

56 shown

No immediate action
v0.17.4 Mixed

Custom voice + tool recovery + docs

Open
Review required
v0.17.3 Bug fix
Auth RCE / SSRF

Bug fixes, docs updates, CI changes

Open
No immediate action
v0.17.2 Bug fix

AsyncSQLiteSession session settings

Open
v0.17.1 Bug fix

Fixed a variety of bugs across sandboxes, tracing, sessions, realtime agents, core modules, and extensions.

Full changelog

What's Changed

Sandboxes

  • fix: include sandbox provider error details by @seratch in https://github.com/openai/openai-agents-python/pull/3326
  • fix: #3274 limit sandbox archive extraction by @Aphroq in https://github.com/openai/openai-agents-python/pull/3278
  • fix: #3273 validate git repo subpaths by @Aphroq in https://github.com/openai/openai-agents-python/pull/3276
    • fix: allow empty GitRepo subpaths as repository root by @seratch in https://github.com/openai/openai-agents-python/pull/3299
    • fix: preserve GitRepo root subpath aliases by @seratch in https://github.com/openai/openai-agents-python/pull/3303

Tracing

  • fix: make tracing shutdown best-effort on process exit by @seratch in https://github.com/openai/openai-agents-python/pull/3343
  • fix: keep BatchTraceProcessor worker alive on exporter errors by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3216
  • fix: guard no-op tracing span IDs by @seratch in https://github.com/openai/openai-agents-python/pull/3296

Sessions

  • fix: #3267 preserve required hosted tool IDs in OpenAI conversation sessions by @seratch in https://github.com/openai/openai-agents-python/pull/3341
  • fix: #3304 skip corrupt items during pop (sessions) by @Aphroq in https://github.com/openai/openai-agents-python/pull/3305
  • fix: #3306 track MongoDB metadata timestamps by @Aphroq in https://github.com/openai/openai-agents-python/pull/3307
  • fix: preserve created_at across writes (redis-session) by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3202
  • fix: skip corrupt docs in MongoDBSession.pop_item by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3247

Realtime Agents

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

Other core modules

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

Extensions

  • fix: avoid duplicating content and signed thinking blocks across parallel tool-call splits (any-llm) by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3261
  • fix: avoid duplicating content and signed thinking blocks across parallel tool-call splits (litellm) by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3215
  • fix: #3330 handle string tool trimmer allowlists by @Aphroq in https://github.com/openai/openai-agents-python/pull/3331
  • fix: preserve HandoffInputData.input_items in remove_all_tools by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3253

Documentation & Other Changes

  • docs: updates for v0.17.0 by @seratch in https://github.com/openai/openai-agents-python/pull/3188
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3193
  • docs: add dapr to durable orchestration integrations by @yaron2 in https://github.com/openai/openai-agents-python/pull/3292
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3293
  • docs: update MCP examples by @seratch in https://github.com/openai/openai-agents-python/pull/3342
  • test: guard Responses transport extra kwargs with official client by @seratch in https://github.com/openai/openai-agents-python/pull/3295
  • chore: improve examples auto-run coverage and artifact handling by @seratch in https://github.com/openai/openai-agents-python/pull/3328
  • chore: improve automated example coverage and local service handling by @seratch in https://github.com/openai/openai-agents-python/pull/3297
  • Release 0.17.1 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3290

New Contributors

  • @yaron2 made their first contribution in https://github.com/openai/openai-agents-python/pull/3292
  • @0xSudoSSH made their first contribution in https://github.com/openai/openai-agents-python/pull/3339

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

View release on GitHub
v0.17.0 Breaking risk
⚠ Upgrade required
  • If your application copies trusted host files or directories from outside the SDK process current working directory into a sandbox, add those paths to `Manifest.extra_path_grants` using `SandboxPathGrant`, preferably as read-only.
  • Treat `extra_path_grants` as trusted configuration; do not populate grants from untrusted input.
Breaking changes
  • Default model for RealtimeAgent changed from previous default to gpt-realtime-2.
  • Sandbox local source materialization now confines `LocalFile.src` and `LocalDir.src` within the manifest's `base_dir` unless granted via `Manifest.extra_path_grants`.
Notable features
  • RealtimeAgent defaults to model gpt-realtime-2
Full changelog

Key Changes

RealtimeAgent's default is now gpt-realtime-2

Since this version, the default model for RealtimeAgents is gpt-realtime-2: https://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 by @seratch in https://github.com/openai/openai-agents-python/pull/3190
  • fix: #3169 constrain local sandbox artifact sources to base dir by @seratch in https://github.com/openai/openai-agents-python/pull/3177
  • fix: Responses context-management extra_args collision by @alfozan in https://github.com/openai/openai-agents-python/pull/3185

Documentation & Other Changes

  • Release 0.17.0 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3191

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

View release on GitHub
v0.16.1 Bug fix

Fixed session history restoration after compaction replacement failures.

Full changelog

What's Changed

  • fix: #3109 stabilize chat completions stream output indexes by @seratch in https://github.com/openai/openai-agents-python/pull/3176
  • fix: #3168 validate MCP require_approval policies by @seratch in https://github.com/openai/openai-agents-python/pull/3179
  • fix: #3116 restore session history after compaction replacement failures by @Aphroq in https://github.com/openai/openai-agents-python/pull/3117
  • fix: #3171 reject corrupt Dapr session state updates by @Aphroq in https://github.com/openai/openai-agents-python/pull/3173
  • fix: #3170 clean up git repo temp clones on failure by @Aphroq in https://github.com/openai/openai-agents-python/pull/3172
  • fix: #3174 count valid encrypted session items for limits by @Aphroq in https://github.com/openai/openai-agents-python/pull/3175
  • fix: reject non-object function tool input JSON by @ioleksiuk in https://github.com/openai/openai-agents-python/pull/3166

Documentation & Other Changes

  • docs: updates for #3147 by @seratch in https://github.com/openai/openai-agents-python/pull/3148
  • docs: add 0.16.0 changelog by @seratch in https://github.com/openai/openai-agents-python/pull/3153
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3163
  • docs: document tool execution concurrency by @seratch in https://github.com/openai/openai-agents-python/pull/3164
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3165
  • Release 0.16.1 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3167

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

View release on GitHub
v0.16.0 Breaking risk patches CVE-2026-42208
⚠ Upgrade required
  • If you require the previous default model behavior, explicitly set it via Agent(model="gpt-4.1") or the OPENAI_DEFAULT_MODEL environment variable.
  • The max_turns detection can be disabled by setting max_turns=None in run configuration.
Breaking changes
  • Default SDK model changed from gpt-4.1 to gpt-5.4-mini, altering implicit behavior such as reasoning.effort="none" and verbosity="low".
Notable features
  • Option max_turns=None disables the Agents SDK run turn limit while preserving the default of 10 when omitted.
  • ToolExecutionConfig(max_function_tool_concurrency=...) allows configuring local function tool execution concurrency.
  • include_server_in_tool_names=True in MCPConfig adds the MCP server name to tool names to avoid conflicts.
Full changelog

Key Changes

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 https://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) by @seratch in https://github.com/openai/openai-agents-python/pull/3147
  • feat: allow disabling max_turns with None by @seratch in https://github.com/openai/openai-agents-python/pull/3132
  • feat: #1167 add opt-in server-prefixed MCP tool names by @mavrickdeveloper in https://github.com/openai/openai-agents-python/pull/3019
  • feat: #1859 add runtime function tool concurrency config by @seratch in https://github.com/openai/openai-agents-python/pull/3152
  • fix: #3104 stabilize chat completions tool call output indexes by @seratch in https://github.com/openai/openai-agents-python/pull/3161
  • fix: reject external symlink targets during hydrate by @Aphroq in https://github.com/openai/openai-agents-python/pull/3094
  • fix: make Permissions hashable to match User and Group by @ioleksiuk in https://github.com/openai/openai-agents-python/pull/3154

Documentation & Other Changes

  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3151
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3160
  • docs: realtime guardrail fallback behavior by @mindbomber in https://github.com/openai/openai-agents-python/pull/3157
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3162
  • Release 0.16.0 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3150

New Contributors

  • @mavrickdeveloper made their first contribution in https://github.com/openai/openai-agents-python/pull/3019
  • @mindbomber made their first contribution in https://github.com/openai/openai-agents-python/pull/3157

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

View release on GitHub
v0.15.3 Bug fix

Fixed duplicate tool errors to be deterministic and rejected non-object JSON inputs.

Full changelog

What's Changed

  • fix(mcp): avoid mutating tool input schemas by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3134
  • fix(mcp): reject non-object tool input JSON by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3135
  • fix(mcp): make duplicate tool errors deterministic by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3136
  • fix: tolerate audio deltas before audio format negotiation in ModelAu… by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3141

Documentation & Other Changes

  • docs: updates for #3128 by @seratch in https://github.com/openai/openai-agents-python/pull/3129
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3131
  • test: cover overlapping tool response creates by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/3140
  • Release 0.15.3 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3149

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

View release on GitHub
v0.15.2 Bug fix
Notable features
  • Added context management model setting
Full changelog

What's Changed

  • feat: add context management model setting by @seratch in https://github.com/openai/openai-agents-python/pull/3128
  • fix: #3123 avoid replaying assistant conversation item IDs for OpenAIConversationsSession by @seratch in https://github.com/openai/openai-agents-python/pull/3127
  • fix: redact function tool trace span errors by @Aphroq in https://github.com/openai/openai-agents-python/pull/3111
  • fix: redact MCP invalid JSON errors when tool logging is disabled by @Aphroq in https://github.com/openai/openai-agents-python/pull/3088
  • fix: reject failed responses stream terminals by @Aphroq in https://github.com/openai/openai-agents-python/pull/3107
  • fix: only rewind matching session suffixes by @Aphroq in https://github.com/openai/openai-agents-python/pull/3090
  • fix: reject string-like shell commands by @Aphroq in https://github.com/openai/openai-agents-python/pull/3092
  • fix: filter custom_tool_call types in remove_all_tools handoff filter by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3095
  • fix: make ToolContext hashable to match RunContextWrapper by @ioleksiuk in https://github.com/openai/openai-agents-python/pull/3097
  • fix: block disabled function tools before execution by @Aphroq in https://github.com/openai/openai-agents-python/pull/3118
  • fix: isolate merged MCP tool metadata by @felmonon in https://github.com/openai/openai-agents-python/pull/3114

Documentation & Other Changes

  • docs: updates for #3080 by @seratch in https://github.com/openai/openai-agents-python/pull/3081
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3084
  • test: improve coverage and organize test layout by @seratch in https://github.com/openai/openai-agents-python/pull/3085
  • test: cover realtime tool timeout behaviors in realtime session by @Aphroq in https://github.com/openai/openai-agents-python/pull/3076
  • test: add realtime tool output serialization edge cases by @Aphroq in https://github.com/openai/openai-agents-python/pull/3077
  • test: cover on_handoff, on_tool_start, on_tool_end on RunHooks by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3098
  • test: cover real Handoff object branch in visualization by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3100
  • test: add direct unit tests for _tool_identity helpers by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3101
  • test: add direct unit tests for _mcp_tool_metadata helpers by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3102
  • Release 0.15.2 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3099

New Contributors

  • @ioleksiuk made their first contribution in https://github.com/openai/openai-agents-python/pull/3097

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.1...v0.15.2

View release on GitHub
v0.15.1 Bug fix
Notable features
  • Expose Responses WebSocket keepalive options
Full changelog

What's Changed

  • feat: expose Responses WebSocket keepalive options by @seratch in https://github.com/openai/openai-agents-python/pull/3080
  • fix: restore UnixLocal PTY terminal signal defaults by @seratch in https://github.com/openai/openai-agents-python/pull/3082
  • fix: #3074 restore SIGINT defaults for UnixLocal PTY children by @Aphroq in https://github.com/openai/openai-agents-python/pull/3075

Documentation & Other Changes

  • docs: add 0.15 changelog by @seratch in https://github.com/openai/openai-agents-python/pull/3058
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3064
  • docs: improve quickstart documentation for Windows OS users by @seratch in https://github.com/openai/openai-agents-python/pull/3071
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3072
  • test: cover guardrail name fallback to function name by @Quratulain-bilal in https://github.com/openai/openai-agents-python/pull/3073
  • chore: harden Dapr Redis integration fixture loading by @Aphroq in https://github.com/openai/openai-agents-python/pull/3078
  • Release 0.15.1 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3083

New Contributors

  • @Aphroq made their first contribution in https://github.com/openai/openai-agents-python/pull/3078

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.15.0...v0.15.1

View release on GitHub
v0.15.0 Breaking risk
⚠ Upgrade required
  • Update code to provide a `model_refusal` error handler when calling `Runner.run_sync` to avoid unhandled exceptions, e.g., `error_handlers={"model_refusal": lambda data: data.error.refusal}`.
Breaking changes
  • Model refusals are now surfaced as `ModelRefusalError` rather than empty text output or triggering retry loops.
Full changelog

Key Changes

Better model refusal handling

In this version, model refusals are now surfaced explicitly as ModelRefusalError instead of being treated as empty text output or, for structured outputs, causing the run loop to retry until MaxTurnsExceeded.

This affects code that previously expected a refusal-only model response to complete with final_output == "". To handle refusals without raising, provide a model_refusal run error handler:

result = Runner.run_sync(
    agent,
    input,
    error_handlers={"model_refusal": lambda data: data.error.refusal},
)

For structured-output agents, the handler can return a value matching the agent's output schema, and the SDK will validate it like other run error handler final outputs.

What's Changed

  • fix: #3055 surface model refusals during run resolution by @seratch in https://github.com/openai/openai-agents-python/pull/3057

Documentation & Other Changes

  • docs: add missing space after period in MCPServerStdio docstring by @GopalGB in https://github.com/openai/openai-agents-python/pull/3053
  • chore(deps): bump actions/github-script from 8.0.0 to 9.0.0 by @dependabot[bot] in https://github.com/openai/openai-agents-python/pull/3059
  • chore(deps): bump peter-evans/create-pull-request from 8.1.0 to 8.1.1 by @dependabot[bot] in https://github.com/openai/openai-agents-python/pull/3062
  • chore(deps): bump pypa/gh-action-pypi-publish from 1.13.0 to 1.14.0 by @dependabot[bot] in https://github.com/openai/openai-agents-python/pull/3061
  • chore(deps): bump openai/codex-action from 1.6 to 1.8 by @dependabot[bot] in https://github.com/openai/openai-agents-python/pull/3060
  • Release 0.15.0 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3063

New Contributors

  • @GopalGB made their first contribution in https://github.com/openai/openai-agents-python/pull/3053

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.8...v0.15.0

View release on GitHub
v0.14.8 Bug fix

Minor fixes and improvements.

Full changelog

What's Changed

  • fix: #3046 preserve MCP re-export import errors by @seratch in https://github.com/openai/openai-agents-python/pull/3048
  • fix: #3043 delimit sandbox prompt instruction sections by @seratch in https://github.com/openai/openai-agents-python/pull/3047

Documentation & Other Changes

  • docs: fix typo in comment for WS event handler by @ateamofantsintheirprime in https://github.com/openai/openai-agents-python/pull/3050
  • Release 0.14.8 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3049

New Contributors

  • @ateamofantsintheirprime made their first contribution in https://github.com/openai/openai-agents-python/pull/3050

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.7...v0.14.8

View release on GitHub
v0.14.7 Security relevant
Security fixes
  • Tightened tar and zip member validation
  • Reject symlinked LocalFile sources
Notable features
  • Convenience properties (tool_name, call_id) added to tool items
  • GPT-5.5 aliases added to sandbox compaction
Full changelog

What's Changed

  • feat: #2886 add convenience properties (tool_name, call_id) to tool items by @jawwad-ali in https://github.com/openai/openai-agents-python/pull/3027
  • fix: raise Phase 2 memory consolidation turn limit by @andi-oai in https://github.com/openai/openai-agents-python/pull/3038
  • fix: add GPT-5.5 aliases to sandbox compaction by @alfozan in https://github.com/openai/openai-agents-python/pull/3039
  • fix: tighten tar and zip member validation by @matthewflint in https://github.com/openai/openai-agents-python/pull/3028
  • fix: reject symlinked LocalFile sources by @matthewflint in https://github.com/openai/openai-agents-python/pull/2972
  • fix: remove unset fields from calls to Responses API by @s0rc3r3r01 in https://github.com/openai/openai-agents-python/pull/3026

Documentation & Other Changes

  • Release 0.14.7 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3031

New Contributors

  • @jawwad-ali made their first contribution in https://github.com/openai/openai-agents-python/pull/3027
  • @s0rc3r3r01 made their first contribution in https://github.com/openai/openai-agents-python/pull/3026
  • @andi-oai made their first contribution in https://github.com/openai/openai-agents-python/pull/3038

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.6...v0.14.7

View release on GitHub
v0.14.6 Bug fix

Minor fixes and improvements.

Full changelog

What's Changed

  • fix: update examples and defaults to GPT-5.5 by @alfozan in https://github.com/openai/openai-agents-python/pull/3016
  • chore: relax websockets upper bound from <16 to <17 by @mathisobadia in https://github.com/openai/openai-agents-python/pull/3013

Documentation & Other Changes

  • chore: harden uv dependency resolution by @mcgrew-oai in https://github.com/openai/openai-agents-python/pull/3014
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3021
  • docs: add MongoDB session documentation by @alexbevi in https://github.com/openai/openai-agents-python/pull/3015
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3023
  • Release 0.14.6 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3022

New Contributors

  • @mcgrew-oai made their first contribution in https://github.com/openai/openai-agents-python/pull/3014
  • @mathisobadia made their first contribution in https://github.com/openai/openai-agents-python/pull/3013

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.5...v0.14.6

View release on GitHub
v0.14.5 New feature
Notable features
  • Modal sandbox idle timeout option
  • HITL resume tool outputs
Full changelog

What's Changed

  • feat: #3001 add Modal sandbox idle timeout option by @seratch in https://github.com/openai/openai-agents-python/pull/3005
  • fix: #3004 serve HITL resume tool outputs by @seratch in https://github.com/openai/openai-agents-python/pull/3006
  • fix: backfill streamed terminal output by @ankitphogat in https://github.com/openai/openai-agents-python/pull/3000

Documentation & Other Changes

  • docs: clarify lazy skill source host paths by @alfozan in https://github.com/openai/openai-agents-python/pull/2998
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2999
  • Release 0.14.5 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/3007

New Contributors

  • @ankitphogat made their first contribution in https://github.com/openai/openai-agents-python/pull/3000

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.4...v0.14.5

View release on GitHub
v0.14.4 Mixed
Notable features
  • Adds BoxMount support
  • Fixes snapshot base override handling to properly ignore relative overrides
Full changelog

What's Changed

  • docs: remove duplicate word in voice interruptions section by @abhicris in https://github.com/openai/openai-agents-python/pull/2981
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2982
  • test: add sandbox compatibility guards by @seratch in https://github.com/openai/openai-agents-python/pull/2984
  • fix: ignore relative snapshot base overrides by @matthewflint in https://github.com/openai/openai-agents-python/pull/2976
  • feat: add BoxMount support by @alfozan in https://github.com/openai/openai-agents-python/pull/2988
  • refactor: share sandbox ephemeral mount lifecycle by @seratch in https://github.com/openai/openai-agents-python/pull/2986
  • refactor: share sandbox tar exclude arg generation by @seratch in https://github.com/openai/openai-agents-python/pull/2987
  • refactor: extract sandbox session helper operations by @seratch in https://github.com/openai/openai-agents-python/pull/2985
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2996
  • Release 0.14.4 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2989

New Contributors

  • @abhicris made their first contribution in https://github.com/openai/openai-agents-python/pull/2981

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.3...v0.14.4

View release on GitHub
v0.14.3 Bug fix

Minor fixes and improvements.

Full changelog

What's Changed

  • fix: #2962 normalize sandbox paths and add Windows CI by @seratch in https://github.com/openai/openai-agents-python/pull/2963
  • fix: #2938 make sandboxes importable on Windows by @seratch in https://github.com/openai/openai-agents-python/pull/2948
  • fix: prepare Daytona workspace root before start by @seratch in https://github.com/openai/openai-agents-python/pull/2956
  • fix: windows errors with #2956 by @seratch in https://github.com/openai/openai-agents-python/pull/2979
  • fix: #2951 warn for tool name character replacement by @seratch in https://github.com/openai/openai-agents-python/pull/2953
  • fix: tighten LocalSnapshot restorable checks by @matthewflint in https://github.com/openai/openai-agents-python/pull/2975
  • fix: bound manifest description truncation by @matthewflint in https://github.com/openai/openai-agents-python/pull/2974
  • fix: move module docstring to top of handoff_filters.py so it is assigned to __doc__ by @kuishou68 in https://github.com/openai/openai-agents-python/pull/2950

Documentation & Other Changes

  • docs: add Datadog as an external tracer in the tracing docs by @jarbaugh5 in https://github.com/openai/openai-agents-python/pull/2965
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2978
  • Release 0.14.3 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2980

New Contributors

  • @kuishou68 made their first contribution in https://github.com/openai/openai-agents-python/pull/2950
  • @jarbaugh5 made their first contribution in https://github.com/openai/openai-agents-python/pull/2965
  • @matthewflint made their first contribution in https://github.com/openai/openai-agents-python/pull/2975

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.2...v0.14.3

View release on GitHub
v0.14.2 Mixed
Notable features
  • Sandbox extra path grants support
  • Tool origin metadata persistence in run items
  • MongoDB session backend for extensions
Full changelog

What's Changed

  • feat: support sandbox extra path grants by @qiyaoq-oai in https://github.com/openai/openai-agents-python/pull/2920
  • feat: #2228 persist tool origin metadata in run items by @seratch in https://github.com/openai/openai-agents-python/pull/2654
  • feat(extensions): add MongoDB session backend by @alexbevi in https://github.com/openai/openai-agents-python/pull/2902
  • fix: loosen sandbox compaction model parsing by @sdcoffey in https://github.com/openai/openai-agents-python/pull/2930
  • fix: remove_all_tools missing hosted tool types by @javierdejesusda in https://github.com/openai/openai-agents-python/pull/2885
  • fix: tolerate None text in ResponseOutputText content items by @beveradb in https://github.com/openai/openai-agents-python/pull/2883
  • fix: #1876 LiteLLM extra_body forwarding by @yu2001-s in https://github.com/openai/openai-agents-python/pull/2900
  • fix: trust filesystem permissions for Vercel roots by @scotttrinh in https://github.com/openai/openai-agents-python/pull/2910
  • fix: #604 handle None choices in ChatCompletion response by @Spectual in https://github.com/openai/openai-agents-python/pull/2850
  • fix: normalize compacted Responses user inputs before session reuse by @seratch in https://github.com/openai/openai-agents-python/pull/2925
  • fix: #2929 surface run-loop exceptions after stream_events() completes by @nileshpatil6 in https://github.com/openai/openai-agents-python/pull/2931

Documentation & Other Changes

  • docs: clarify OpenAI provider configuration guidance by @seratch in https://github.com/openai/openai-agents-python/pull/2901
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2903
  • docs: sync sandbox translations and set doc translation default model to gpt-5.4 by @seratch in https://github.com/openai/openai-agents-python/pull/2904
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2935
  • chore: bump temporalio Dep in Temporal example by @JasonSteving99 in https://github.com/openai/openai-agents-python/pull/2918
  • Release 0.14.2 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2899

New Contributors

  • @javierdejesusda made their first contribution in https://github.com/openai/openai-agents-python/pull/2885
  • @beveradb made their first contribution in https://github.com/openai/openai-agents-python/pull/2883
  • @yu2001-s made their first contribution in https://github.com/openai/openai-agents-python/pull/2900
  • @JasonSteving99 made their first contribution in https://github.com/openai/openai-agents-python/pull/2918
  • @scotttrinh made their first contribution in https://github.com/openai/openai-agents-python/pull/2910
  • @Spectual made their first contribution in https://github.com/openai/openai-agents-python/pull/2850
  • @alexbevi made their first contribution in https://github.com/openai/openai-agents-python/pull/2902
  • @qiyaoq-oai made their first contribution in https://github.com/openai/openai-agents-python/pull/2920
  • @nileshpatil6 made their first contribution in https://github.com/openai/openai-agents-python/pull/2931

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.14.1...v0.14.2

View release on GitHub
v0.14.0 New feature
Notable features
  • SandboxAgent with workspace manifests and sandbox memory capability
  • Multiple execution backends: UnixLocal, Docker, Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel
  • Workspace mounts and snapshots with S3, GCS, Azure Blob Storage, R2 support
View release on GitHub
v0.13.5 New feature
Notable features
  • Callable approval policies for local MCP servers
  • Public flush_traces API
View release on GitHub
v0.13.2 Security relevant
Security fixes
  • Pin LiteLLM upper bound to 1.82.6 to mitigate supply chain attack
Notable features
  • External web access added to WebSearchTool
View release on GitHub
v0.13.1 New feature
Notable features
  • Any-LLM model support with responses-compatible routing
View release on GitHub
v0.13.0 Breaking risk
Notable features
  • Default Realtime model changed to gpt-realtime-1.5
  • MCPServer exposes list_resources(), list_resource_templates(), read_resource()
  • Reasoning-content replay support for chat completions
View release on GitHub
v0.12.4 Bug fix

Fixes MCP tool invocation normalization and transient failure retry logic.

View release on GitHub
v0.12.1 Bug fix

Preserves approval rejection messages across agent resume flows.

Full changelog

What's Changed

  • feat: #2658 preserve explicit approval rejection messages across resume flows by @seratch in https://github.com/openai/openai-agents-python/pull/2660

Documentation & Other Changes

  • docs: add retry settings by @seratch in https://github.com/openai/openai-agents-python/pull/2655
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2656
  • Release 0.12.1 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2662

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.12.0...v0.12.1

View release on GitHub
v0.12.0 New feature
Notable features
  • Opt-in model retry policies in ModelSettings
Full changelog

Key Changes

Opt-in retry settings

New opt-in settings for retries of model API calls is available in this version. The new configuration is available as part of ModelSettings and it can be passed either as run config or model settings per an agent.

Refer to the following code examples for details:

  • https://github.com/openai/openai-agents-python/blob/main/examples/basic/retry.py
  • https://github.com/openai/openai-agents-python/blob/main/examples/basic/retry_litellm.py

What's Changed

  • feat: add opt-in model retry policies by @seratch in https://github.com/openai/openai-agents-python/pull/2651

Documentation & Other Changes

  • Release 0.12.0 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2653

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.11.1...v0.12.0

View release on GitHub
v0.11.0 Breaking risk
Breaking changes
  • Default reasoning.effort changed from 'low' to 'none' for gpt-5.1/5.2
Notable features
  • Tool search support
  • Computer use tool GA with gpt-5.4 support
View release on GitHub
v0.10.5 Breaking risk
Notable features
  • Explicit MultiProvider prefix modes
  • McpError returned as structured result
Full changelog

What's Changed

  • feat: #2492 add explicit MultiProvider prefix modes by @seratch in https://github.com/openai/openai-agents-python/pull/2593
  • fix: #879 return McpError as a structured error result instead of crashing the agent run by @adityasingh2400 in https://github.com/openai/openai-agents-python/pull/2598

Documents & Other Changes

  • docs: improve doc coverage for Dapr sessions and advanced model settings by @seratch in https://github.com/openai/openai-agents-python/pull/2587
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2589
  • docs: clarify realtime transport boundaries and SIP attach flows by @seratch in https://github.com/openai/openai-agents-python/pull/2591
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2592
  • docs: clarify agent runtime, handoff, HITL, and results flows by @seratch in https://github.com/openai/openai-agents-python/pull/2596
  • docs: update translated document pages by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2597
  • chore: add implementation strategy guidance for compatibility decisions by @seratch in https://github.com/openai/openai-agents-python/pull/2600
  • docs: fix deprecated capwords import for Python 3.11+ compatibility by @Jah-yee in https://github.com/openai/openai-agents-python/pull/2605
  • Release 0.10.5 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2595

New Contributors

  • @adityasingh2400 made their first contribution in https://github.com/openai/openai-agents-python/pull/2598
  • @Jah-yee made their first contribution in https://github.com/openai/openai-agents-python/pull/2605

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.10.4...v0.10.5

View release on GitHub
v0.10.3 New feature
Notable features
  • Immutable agent tool invocation metadata
  • RunResult tool_context accessor
View release on GitHub
v0.9.0 Breaking risk
Breaking changes
  • Python 3.9 no longer supported, upgrade to Python 3.10 or newer
  • Agent.as_tool() return type narrowed to FunctionTool
Notable features
  • Configurable timeout handling for function tools
  • ToolOutputTrimmer for smart context management
View release on GitHub
v0.8.3 New feature
Notable features
  • Model version support for realtime turn detection
Full changelog

What's Changed

  • Support model_version param for turn detection in realtime agents sdk by @jhills20 in https://github.com/openai/openai-agents-python/pull/2450

Documents & Other Changes

  • docs: describe Pydantic Field annotations for tool args by @haasonsaas in https://github.com/openai/openai-agents-python/pull/2436
  • Release 0.8.3 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2451

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.8.2...v0.8.3

View release on GitHub
v0.8.2 New feature
Notable features
  • Support for Annotated[T, Field(...)] in function schema
  • Agent included in ToolContext for tool calls
View release on GitHub
v0.8.0 Breaking risk
Breaking changes
  • Synchronous Python callables in function tools now execute on worker threads via asyncio.to_thread()
  • MCP tool failure handling configurable with different default behavior
Notable features
  • Human-in-the-loop (HITL) support with tool call approval workflow
  • Structured agent tool input support
  • Session customization parameters
View release on GitHub
v0.7.0 Breaking risk
Breaking changes
  • Nested handoff behavior disabled by default; enable with nest_handoff_history=True
Notable features
  • MCPServerManager for managing multiple MCP server instances
View release on GitHub
v0.6.9 New feature
Notable features
  • Input-based response compaction with store-aware auto mode
  • Robust handling of invalid tool argument JSON
Full changelog

What's Changed

  • feat: #2333 support input-based responses compaction with store-aware auto mode by @seratch in https://github.com/openai/openai-agents-python/pull/2334
  • fix: #2061 handle invalid tool arguments JSON without crashing by @seratch in https://github.com/openai/openai-agents-python/pull/2337
  • Release 0.6.9 by @github-actions[bot] in https://github.com/openai/openai-agents-python/pull/2336

Full Changelog: https://github.com/openai/openai-agents-python/compare/v0.6.8...v0.6.9

View release on GitHub
v0.6.6 New feature
Notable features
  • Auto-compact long conversations with responses.compact
  • AsyncSQLiteSession support
View release on GitHub

Beta — feedback welcome: [email protected]