openai-agents-python

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

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