v0.17.1

What's Changed

Sandboxes

• fix: include sandbox provider error details by @seratch in #3326
• fix: #3274 limit sandbox archive extraction by @Aphroq in #3278
• fix: #3273 validate git repo subpaths by @Aphroq in #3276
  • fix: allow empty GitRepo subpaths as repository root by @seratch in #3299
  • fix: preserve GitRepo root subpath aliases by @seratch in #3303

Tracing

• fix: make tracing shutdown best-effort on process exit by @seratch in #3343
• fix: keep BatchTraceProcessor worker alive on exporter errors by @adityasingh2400 in #3216
• fix: guard no-op tracing span IDs by @seratch in #3296

Sessions

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

Realtime Agents

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

Other core modules

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

Extensions

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

Documentation & Other Changes

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

New Contributors

• @yaron2 made their first contribution in #3292
• @0xSudoSSH made their first contribution in #3339

Full Changelog: v0.17.0...v0.17.1

v0.17.0

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 #3190
• fix: #3169 constrain local sandbox artifact sources to base dir by @seratch in #3177
• fix: Responses context-management extra_args collision by @alfozan in #3185

Documentation & Other Changes

• Release 0.17.0 by @github-actions[bot] in #3191

Full Changelog: v0.16.1...v0.17.0

v0.16.1

What's Changed

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

Documentation & Other Changes

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

Full Changelog: v0.16.0...v0.16.1

v0.16.0

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

Documentation & Other Changes

• docs: update translated document pages by @github-actions[bot] in #3151
• docs: update translated document pages by @github-actions[bot] in #3160
• docs: realtime guardrail fallback behavior by @mindbomber in #3157
• docs: update translated document pages by @github-actions[bot] in #3162
• Release 0.16.0 by @github-actions[bot] in #3150

New Contributors

• @mavrickdeveloper made their first contribution in #3019
• @mindbomber made their first contribution in #3157

Full Changelog: v0.15.3...v0.16.0

v0.15.3

What's Changed

• fix(mcp): avoid mutating tool input schemas by @adityasingh2400 in #3134
• fix(mcp): reject non-object tool input JSON by @adityasingh2400 in #3135
• fix(mcp): make duplicate tool errors deterministic by @adityasingh2400 in #3136
• fix: tolerate audio deltas before audio format negotiation in ModelAu… by @Quratulain-bilal in #3141

Documentation & Other Changes

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

Full Changelog: v0.15.2...v0.15.3

v0.15.2

What's Changed

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

Documentation & Other Changes

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

New Contributors

• @ioleksiuk made their first contribution in #3097

Full Changelog: v0.15.1...v0.15.2

v0.15.1

What's Changed

• feat: expose Responses WebSocket keepalive options by @seratch in #3080
• fix: restore UnixLocal PTY terminal signal defaults by @seratch in #3082
• fix: #3074 restore SIGINT defaults for UnixLocal PTY children by @Aphroq in #3075

Documentation & Other Changes

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

New Contributors

• @Aphroq made their first contribution in #3078

Full Changelog: v0.15.0...v0.15.1

v0.15.0

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 #3057

Documentation & Other Changes

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

New Contributors

• @GopalGB made their first contribution in #3053

Full Changelog: v0.14.8...v0.15.0

v0.14.8

What's Changed

• fix: #3046 preserve MCP re-export import errors by @seratch in #3048
• fix: #3043 delimit sandbox prompt instruction sections by @seratch in #3047

Documentation & Other Changes

• docs: fix typo in comment for WS event handler by @ateamofantsintheirprime in #3050
• Release 0.14.8 by @github-actions[bot] in #3049

New Contributors

• @ateamofantsintheirprime made their first contribution in #3050

Full Changelog: v0.14.7...v0.14.8

v0.14.7

What's Changed

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

Documentation & Other Changes

• Release 0.14.7 by @github-actions[bot] in #3031

New Contributors

• @jawwad-ali made their first contribution in #3027
• @s0rc3r3r01 made their first contribution in #3026
• @andi-oai made their first contribution in #3038

Full Changelog: v0.14.6...v0.14.7