release: 0.21.0 - #4387

Release readiness review (v0.20.0 -> TARGET 8094e56)

This is a release readiness report done by $final-release-review skill.

Diff

v0.20.0...8094e56

Release intent

• Review mode: final candidate
• Intended release: minor 0.21.0
• Minimum required release type: minor
• Versioning verdict: compatible

Release call

🟢 GREEN LIGHT TO SHIP The candidate metadata, lockfile, branch, and frozen API contract agree, and no concrete release-blocking regression was identified.

Scope summary

• 255 files changed (+27916/-8912); key areas touched: provider-neutral testing utilities, OpenAI Python v3 and HTTPX2 compatibility, RunState and runner lifecycle, MCP lifecycle and retries, sandbox boundaries, Voice validation, documentation, and release contracts.

Risk assessment (ordered by impact)

1. OpenAI Python v3 and HTTPX2 compatibility

   • Risk: 🟢 LOW. Applications using OpenAI provider integrations now require the compatible OpenAI Python v3 range, while HTTPX-specific adapters and tests may need HTTPX2 types.
   • Evidence: The dependency range moves to openai>=3.0.0,<4, with compatibility code and focused provider, retry, packaging, and integration coverage.
   • Files: pyproject.toml, src/agents/_httpx_compat.py, src/agents/models/, src/agents/voice/models/
   • Action: Preserve the explicit OpenAI v3 and HTTPX2 migration wording in release communications.

2. Provider-neutral scripted testing APIs

   • Risk: 🟢 LOW. This is the major feature addition that requires the minor release.
   • Evidence: New agents.testing, agents.realtime.testing, and agents.voice.testing modules are covered by dedicated tests and are frozen in the v0.21.0 released API contract.
   • Files: src/agents/testing/, src/agents/realtime/testing.py, src/agents/voice/testing.py, tests/fixtures/released_api_contract.json
   • Action: Keep the public names, signatures, properties, TypedDict fields, and canonical imports frozen as generated.

3. RunState, streaming, and approval-resume hardening

   • Risk: 🟢 LOW. The release changes sensitive lifecycle paths, but the changes are narrowly scoped to snapshot isolation, recursive approvals, max-turn finalization, stream cleanup, and redacted failures.
   • Evidence: The diff adds focused regression tests for RunState isolation, approval identity, max-turn semantics, streaming cleanup, and sensitive logging paths.
   • Files: src/agents/run_state.py, src/agents/run_internal/run_loop.py, src/agents/exceptions.py
   • Action: Retain the tested resumed, nested, streamed, cancellation, and redaction behavior.

4. MCP, Sandbox, and Voice lifecycle fixes

   • Risk: 🟢 LOW. The release strengthens caller-mutation isolation, retry bounds, sandbox grants, and malformed-audio validation.
   • Evidence: Focused MCP, sandbox, and Voice tests cover lifecycle snapshots, retry configuration, view-image grants, Runloop secrets, frame validation, and tracing-disabled audio buffering.
   • Files: src/agents/mcp/, src/agents/extensions/sandbox/, src/agents/voice/
   • Action: Preserve the exact compatibility qualifiers and validation behavior in release notes.

Documentation coverage (non-blocking)

• Coverage source: docs: updates for v0.21.0 release #4381 at head 7bbaab8da4f0507fa27f745cd37143c13ecafd40, plus documentation already included in the release target.
• Status: covered
• Covered obligations: provider-neutral testing utilities, OpenAI v3 and HTTPX2 guidance, runner and session behavior, MCP, Sandbox, Realtime, and Voice changes.
• Gaps or post-release suggestions: none
• Publication timing: merge docs: updates for v0.21.0 release #4381 after the SDK release because it documents unreleased testing APIs.

Key Changes draft

Key Changes

This minor release does not introduce a known breaking SDK behavior change. The minor version bump is for the new provider-neutral testing APIs and the OpenAI Python v3 compatibility update.

Highlights:

• Added agents.testing, agents.realtime.testing, and agents.voice.testing utilities for deterministic Agent, Sandbox, Realtime, and Voice workflow tests without provider requests.
• Updated OpenAI provider compatibility to openai>=3.0.0,<4, including HTTPX2-aware request, response, transport, and exception handling.
• Hardened RunState interruption snapshots, recursive agent-tool approvals, max-turn finalization, streaming cleanup, and sensitive-error redaction.
• Improved MCP lifecycle snapshot isolation and added configurable retry backoff ceilings.
• Added Sandbox Runloop existing-secret support and tightened view-image path grants.
• Added stricter Voice validation for invalid channels, frame rates, incomplete multichannel frames, and non-finite audio rates.

Notes

• The candidate is exactly one release commit ahead of current origin/main.
• The release commit changes only the three release-owned manifest files.