v0.17.8

What's Changed

• feat: add invalid final output recovery handler by @seratch in #3736
• fix: propagate realtime session iterator cancellation by @fallintoplace in #3686
• fix: redact realtime validation failure logs by @fallintoplace in #3687
• fix: preserve non-dict Mapping values in _to_dump_compatible by @anxkhn in #3700
• fix: escape quotes and backslashes in DOT names for visualization by @anxkhn in #3712
• fix: enforce strict Pydantic validation when strict_json_schema=True + handoffs by @Om-Borse26 in #3724
• fix: fix an issue with length-frame exec-stdin writes within a sandbox by @imran31415 in #3719

Documentation & Other Changes

• docs: add DProvenanceKit to external tracing processors list by @Therealdk8890 in #3726
• docs: add sandbox examples to examples index by @saime428 in #3731
• test: improve coverage for stream and sandbox edge cases by @seratch in #3730
• chore(deps): bump astral-sh/setup-uv from 8.1.0 to 8.2.0 by @dependabot[bot] in #3714
• chore(deps): bump actions/setup-python from 6.2.0 to 6.3.0 by @dependabot[bot] in #3715
• chore(deps): bump actions/stale from 10.2.0 to 10.3.0 by @dependabot[bot] in #3716
• chore(deps): bump actions/checkout from 6.0.2 to 7.0.0 by @dependabot[bot] in #3717
• Release 0.17.8 by @github-actions[bot] in #3739

New Contributors

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

Full Changelog: v0.17.7...v0.17.8

v0.17.7

What's Changed

• feat: expose configurable websocket max_size limit by @anneheartrecord in #3645
• feat: add buffered Chat Completions tool-call streaming by @incoffeemonster in #3506
• fix: reduce sandbox sink buffering and spool timeouts by @2830500285 in #3642
• fix: #3346 clean up branch-only messages when deleting branches by @Aphroq in #3347
• fix: #3348 make AdvancedSQLiteSession add_items atomic by @Aphroq in #3349
• fix: cancel sibling guardrail tasks when one raises by @adityasingh2400 in #3239
• fix: skip needs_approval_checker when status resolved in _collect_runs_by_approval by @adityasingh2400 in #3259
• fix: validate ls special permission bits by position by @a1vazovsky in #3420
• fix: gate remote-mount edit guidance by mode by @a1vazovsky in #3423
• fix: remove dependency on types-requests by @rouge8 in #3509
• fix: empty list/tuple tool output dropped via all([]) == True by @vidigoat in #3554
• fix: wake PTY output collection on process exit (E2B) by @rohitrastogi in #3610
• fix: avoid stale object-id dedupe in server conversation tracker by @chutch in #3621
• fix: report effective Blaxel timeouts by @he-yufeng in #3643
• fix: prevent ambiguous Realtime multi-agent tool dispatch by @mavrickdeveloper in #3441
• fix: add hint to duplicated MCP server tool name error message by @wustwyh in #3678
• fix: recursively extract HTTP errors from nested ExceptionGroups by @mshsheikh in #3556

Documentation & Other Changes

• docs: #3461 changes for tool_not_found_behavior option by @seratch in #3462
• docs: changes for #3487 feature addition by @seratch in #3488
• docs: fix OpenAI capitalization in auto-generated ref titles by @atimothee in #3646
• docs: add SDK maintainer references and review guidance by @seratch in #3676
• Release 0.17.7 by @github-actions[bot] in #3682

New Contributors

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

Full Changelog: v0.17.6...v0.17.7

v0.17.6

What's Changed

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

Documentation & Other Changes

• docs: fix typo in sandbox guide by @mshsheikh in #3628
• Release 0.17.6 by @github-actions[bot] in #3659

New Contributors

• @siddiksawani made their first contribution in #3657

Full Changelog: v0.17.5...v0.17.6

v0.17.5

What's Changed

• fix: expose sandbox error retryability by @qiyaoq-oai in #3581
• fix: #3512 type tool-end hook results as object by @seratch in #3518
• fix: use tuple form for SpeechGroupSpanData __slots__ by @jluocsa in #3534
• chore: bump Modal sandbox extra to 1.4.3 by @jdoughty04 in #3538

Documentation & Other Changes

• docs: add MongoDB session example under examples/memory by @alexbevi in #3036
• docs: add missing space in MCP params docstrings by @jluocsa in #3535
• docs: fix docstring typo in stdio params env description by @mshsheikh in #3557
• docs: fix two docstring grammar errors in tool.py by @jluocsa in #3543
• docs: add Latitude to external tracing processors list by @guillemwilly in #3577
• docs: tweak in usage doc by @mshsheikh in #3597
• docs: fix string concatenation typo in agent instructions by @mshsheikh in #3599
• docs: capitalization fix in tracing docs by @mshsheikh in #3602
• docs: fix subject-verb agreement in agent loop description by @mshsheikh in #3605
• test: add unit tests for run_demo_loop streaming, EOF, and empty-input paths by @jluocsa in #3542
• test: add unit tests for _openai_retry helpers (77% -> 95% coverage) by @jluocsa in #3544
• Release 0.17.5 by @github-actions[bot] in #3619

New Contributors

• @jluocsa made their first contribution in #3534
• @jdoughty04 made their first contribution in #3538
• @guillemwilly made their first contribution in #3577

Full Changelog: v0.17.4...v0.17.5

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