release: 0.21.0

[seratch]

Release readiness review (v0.20.0 -> TARGET HEAD)

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

Diff

v0.20.0...97fe036

Release intent

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

Release call

🟢 GREEN LIGHT TO SHIP The candidate is correctly versioned, preserves the released API and durable-state contracts, and contains a consistent three-file release manifest over current origin/main.

Scope summary

• 228 files changed (+20,299/-8,243); key areas include OpenAI Python 3 and HTTPX2 compatibility, provider-neutral testing utilities, MCP lifecycle and retry behavior, Sandbox support, Voice input validation, streaming cleanup, RunState safety, documentation, and the frozen public API contract.

Risk assessment (ordered by impact)

1. OpenAI Python 3 and HTTPX2 migration

   • Risk: 🟢 LOW. Custom HTTP clients, transports, mocks, authentication, hooks, and TLS environments may require migration, but the minor version correctly signals the compatibility boundary and usable migration paths exist.
   • Evidence: The dependency moves to openai>=3.0.0,<4; OpenAI provider, Voice, tracing, retry, and WebSocket paths use HTTPX2; default-client behavior is retained; explicitly installed legacy HTTPX remains a temporary OpenAI Python migration bridge.
   • Files: pyproject.toml, uv.lock, src/agents/_httpx_compat.py, src/agents/models/, src/agents/voice/models/openai_model_provider.py, src/agents/tracing/processors.py
   • Action: Release as minor and retain exact HTTPX2 migration, legacy-client, and TLS trust-store guidance.

2. New provider-neutral testing APIs are frozen

   • Risk: 🟢 LOW. The release creates substantial new public surface for deterministic Agent, Sandbox, Realtime, and Voice testing.
   • Evidence: agents.testing, agents.testing.model, agents.testing.sandbox, agents.realtime.testing, and agents.voice.testing are explicitly covered by the release-contract policy and generated v0.21.0 contract, including canonical imports, signatures, module exports, and optional Voice bindings.
   • Files: src/agents/testing/, src/agents/realtime/testing.py, src/agents/voice/testing.py, tests/fixtures/released_api_contract_policy.json, tests/fixtures/released_api_contract.json
   • Action: Treat the generated v0.21.0 contract as the compatibility baseline and publish the testing guide after the package release.

3. MCP compatibility and lifecycle changes remain bounded

   • Risk: 🟢 LOW. Applications can use MCP Python SDK v1 or v2, while lifecycle operations are serialized and retry delays can be capped.
   • Evidence: The supported mcp>=1.19.0,<3 range remains intact, compatibility code selects the installed HTTP family, and the new optional retry ceiling is appended to public constructors without changing previous positional meanings.
   • Files: src/agents/mcp/_compat.py, src/agents/mcp/manager.py, src/agents/mcp/server.py, docs/mcp.md
   • Action: Preserve the documented MCP v1/v2 transport distinctions and uncapped default retry behavior.

4. Runtime and durable-state fixes preserve released paths

   • Risk: 🟢 LOW. Streaming cleanup, RunState interruption snapshots, apply-diff targeting, session limits, and Voice WAV validation become stricter or safer without changing the supported durable-state schema.
   • Evidence: Historical RunState fixtures remain readable in packaged environments, RunState.interruptions now returns a detached list, and the release adds focused regression coverage for the affected paths.
   • Files: src/agents/run_state.py, src/agents/run_internal/, src/agents/apply_diff.py, src/agents/memory/openai_conversations_session.py, src/agents/voice/input.py
   • Action: Keep the fixes and their focused regression coverage together in the release.

Documentation coverage (non-blocking)

• Coverage source: docs: updates for v0.21.0 release #4381 at ba6bf6b7591734cf7a412ac15d7a0499aea5d745, plus documentation already present in the release target.
• Status: partially covered
• Covered obligations: OpenAI Python 3 and HTTPX2 custom-client migration, provider-neutral testing APIs and recipes, MCP v1/v2 behavior, Sandbox and Runloop additions, session and streaming lifecycle behavior, and Voice pipeline error handling.
• Gaps or post-release suggestions: Add the HTTPX2 TLS trust-store change to docs/config.md and the 0.21.0 entry in docs/release.md: HTTPX2 uses the operating-system trust store instead of the previous certifi default, so minimal containers and TLS-inspecting environments may need system CA certificates, SSL_CERT_FILE, SSL_CERT_DIR, or an explicit ssl.SSLContext.
• Publication timing: Merge docs: updates for v0.21.0 release #4381 after version 0.21.0 is published because it documents unreleased behavior.

Key Changes draft

Key Changes

Version 0.21.0 is a minor release because it introduces substantial provider-neutral testing APIs and migrates the SDK to OpenAI Python 3 and HTTPX2. The HTTP migration can require changes for applications that customize the OpenAI transport or depend on the previous TLS trust-store behavior; default API workflows otherwise retain their existing Agents SDK configuration.

Highlights:

• Require openai>=3.0.0,<4 and use HTTPX2 across the default OpenAI provider, Voice provider, tracing exporter, Responses WebSocket support, and provider retry normalization. Custom HTTP integrations should migrate to HTTPX2; an explicitly installed legacy httpx client remains a temporary OpenAI Python migration bridge.
• Add deterministic testing utilities for Agent workflows and Sandbox sessions under agents.testing, Realtime sessions under agents.realtime.testing, and Voice pipelines under agents.voice.testing.
• Support MCP Python SDK v1 and v2 while serializing manager lifecycle operations and adding the optional retry_backoff_seconds_max ceiling.
• Allow Runloop Sandbox configurations to reference existing managed secrets through RunloopExistingSecret.
• Improve runtime safety for streamed terminal failures, interruption snapshots, stacked apply-diff anchors, conversation-history limits, and Voice WAV validation.

Notes

• The release branch is exactly one commit ahead of current origin/main.
• The release commit changes only pyproject.toml, uv.lock, and tests/fixtures/released_api_contract.json.
• Open documentation PR docs: updates for v0.21.0 release #4381 is not part of the release target.