v0.17.4

What's Changed

• feat: support Realtime custom voice objects by @lionel-oai in #3473
• fix: #3459 add opt-in recovery for missing function tools by @seratch in #3461
• fix: apply hardened http client default to MCP SSE transport by @ioleksiuk in #3466
• fix: use non-None value for output in FunctionSpanData by @rmotgi1227 in #3475
• fix: add missing entries to span slots by @rmotgi1227 in #3483
• fix: redact invalid JSON payload in ModelBehaviorError data by @LeSingh1 in #3485
• fix: export more tracing related functions & types from agents by @rmotgi1227 in #3489
• fix: export MCPListToolsItem, ToolSearchCallItem, and ToolSearchOutputItem from agents by @rmotgi1227 in #3490

Documentation & Other Changes

• Release 0.17.4 by @github-actions[bot] in #3505

New Contributors

• @rmotgi1227 made their first contribution in #3475

Full Changelog: v0.17.3...v0.17.4

v0.17.3

What's Changed

• fix: keep mountpoint credentials out of sandbox commands by @seratch in #3429
• fix: unify memory optional dependency import errors by @seratch in #3389
• fix: guard None text in text_message_output and add output guardrail count to RunErrorDetails by @zhoufengen in #3375
• fix: avoid mutating FunctionTool params_json_schema by @ioleksiuk in #3382
• fix: avoid mutating codex output schema input by @ioleksiuk in #3385
• fix: #3357 output schema names for Literal types by @Aphroq in #3358
• fix: skip wait_for_status when Vercel sandbox is in a terminal state by @cty-ut in #3410
• fix: filter hosted_tool_call types in remove_all_tools handoff filter by @ioleksiuk in #3386
• fix: guard None text in ItemHelpers.extract_last_content by @ioleksiuk in #3394
• fix: log exception when output guardrail raises instead of silently ignoring by @cty-ut in #3411
• fix: reject relative sandbox workspace roots by @matthewflint in #3422
• fix: normalize leading question marks in exposed port queries by @matthewflint in #3424
• fix: #3363 honor short custom voice splitter chunks by @Aphroq in #3364
• fix: runtime handling updates by @adrianbravo-oai @ioleksiuk in #3451

Documentation & Other Changes

• docs: add SDK review guidance by @seratch in #3376
• docs: mark Agent.instructions as optional by @ioleksiuk in #3384
• docs: translate all pages using new settings by @seratch in #3392
• docs: document auto_previous_response_id by @ioleksiuk in #3383
• docs: fix LiteLLM API reference redirect by @ynachiket in #3444
• docs: fix duplicated word in usaspending glossary example by @LeSingh1 in #3445
• chore: clean up CI jobs and update uv pin by @seratch in #3400
• ci: harden release tag workflow by @hintz-openai in #3399
• Release 0.17.3 by @github-actions[bot] in #3417

New Contributors

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

Full Changelog: v0.17.2...v0.17.3

v0.17.2

What's Changed

• fix: #3268 fix OpenAI Conversations reasoning persistence by @seratch in #3352
• fix: avoid auto response for unknown realtime tools (ref: #3287) by @seratch in #3366
• fix: #3354 interrupt tracing retry backoff on shutdown by @Aphroq in #3355
• fix: #3359 preserve local approval rejection reasons by @Aphroq in #3360
• fix: #3361 honor session settings in AsyncSQLiteSession by @Aphroq in #3362
• fix: #3310 avoid empty chat tool outputs by @Aphroq in #3312

Documentation & Other Changes

• docs: clarify max_delay for retries works by @seratch in #3350
• docs: update translated document pages by @github-actions[bot] in #3351
• docs: normalize memory docstring cross-references by @seratch in #3370
• docs: document sandbox archive limits after #3278 release by @Aphroq in #3311
• docs: update translated document pages by @github-actions[bot] in #3371
• Release 0.17.2 by @github-actions[bot] in #3368

Full Changelog: v0.17.1...v0.17.2

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