release: 0.22.1

[seratch]

Release readiness review (v0.22.0 -> TARGET release/v0.22.1)

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

Diff

v0.22.0...90857dc

Release intent

• Review mode: final candidate
• Intended release: patch (v0.22.1)
• Minimum required release type: patch
• Versioning verdict: compatible

Release call

🟢 GREEN LIGHT TO SHIP The patch candidate is version-consistent, contains no confirmed regression or incompatible public-contract change, and is exactly one release-manifest commit ahead of current origin/main.

Scope summary

• 195 files changed (+10,511/-2,906); key areas touched: core run behavior, output guardrails, model adapters, Voice, Realtime, MCP, Docker sandbox state, tracing, usage, visualization, release-contract coverage, tests, documentation, and release metadata.

Risk assessment (ordered by impact)

1. Customizable terminal output-guardrail placeholders

   • Risk: 🟢 LOW. Applications can customize the data-free placeholder persisted and replayed when an output guardrail rejects terminal function-tool output; a caller-provided formatter could deliberately derive sensitive text from its run context.
   • Evidence: Relative to v0.22.0, RunConfig.output_guardrail_blocked_message is appended as an optional field with the existing placeholder as its default. Invalid, asynchronous, empty, or failing formatter results fall back to the default, and rejected output and guardrail output_info are not supplied to the formatter. Streaming and non-streaming sanitization use the resolved placeholder consistently.
   • Files: src/agents/run_config.py, src/agents/run.py, src/agents/run_internal/blocked_output.py, src/agents/run_internal/run_loop.py, tests/test_run_config.py, tests/test_agent_runner_streamed.py
   • Action: Ship with the default, fallback, and redaction semantics unchanged; merge the corresponding guidance in docs: document v0.22.1 behavior updates #4577 only after v0.22.1 is available.

2. Voice public contract and OpenAI client ownership

   • Risk: 🟢 LOW. Voice users gain formally frozen imports and additional configuration behavior, while explicit provider options now take precedence over the SDK-wide default client.
   • Evidence: The released contract adds 27 Voice callables and canonical imports, 14 public Voice modules, five public properties, two Voice type aliases, and TTSCustomVoice, with no removals. OpenAI and Voice providers reuse the shared default client only when all provider options are None. Streamed STT derives its endpoint, authentication, headers, and query parameters from the selected client, forwards language and prompt settings, and uses monotonic event deadlines.
   • Files: src/agents/models/openai_provider.py, src/agents/models/_openai_websocket.py, src/agents/voice/, tests/voice/, tests/fixtures/released_api_contract.json
   • Action: No release code change is required; preserve the documented client-precedence and Voice import contracts.

3. Docker labels and the durable RunState boundary

   • Risk: 🟢 LOW. Docker sandbox labels become durable session state and mismatched labels now reject reuse of an existing container instead of silently resuming with different identity metadata.
   • Evidence: DockerSandboxClientOptions and DockerSandboxSessionState append labels with an empty default. RunState schema 1.17 records the new field, older payloads without labels restore as {}, all previously supported schema versions remain readable, replacement containers receive persisted labels, and existing containers are checked only for the labels the state requires.
   • Files: src/agents/run_state.py, src/agents/sandbox/sandboxes/docker.py, tests/sandbox/test_compatibility_guards.py, tests/sandbox/test_docker.py, tests/fixtures/run_state/
   • Action: No release code change is required; retain the empty-label backward-read behavior and schema 1.17 compatibility fixtures.

4. Model terminal behavior and replay sanitization

   • Risk: 🟢 LOW. Previously ambiguous or provider-only data is handled more explicitly: empty truncated Chat Completions now fail, and replay input no longer forwards output-only created_by metadata.
   • Evidence: Streaming and non-streaming OpenAI Chat Completions responses ending with finish_reason="length" before any text, refusal, or tool call raise ModelBehaviorError while retaining request and usage evidence. Run-item replay strips top-level and nested created_by fields through the shared sanitizer without mutating the original item. Any-LLM Chat Completions keeps ModelSettings.extra_body nested rather than merging it into top-level call arguments.
   • Files: src/agents/models/chatcmpl_stream_handler.py, src/agents/models/openai_chatcompletions.py, src/agents/extensions/models/any_llm_model.py, src/agents/items.py, tests/models/, tests/test_items_helpers.py
   • Action: No release code change is required; preserve the distinction between truncation errors, refusals, and valid partial output.

5. Stateful runtime corrections and public-contract enforcement

   • Risk: 🟢 LOW. The release prevents cached-data mutation, duplicate MCP ownership, delayed Realtime guardrail checks, buffered trace loss, shared usage mutation, and visualization node collapse. Release discovery now also requires explicit policy for new public type aliases.
   • Evidence: MCP tool results are detached from cached schemas, repeated instances of the same managed server object are owned once, and cleanup clears active state. Realtime guardrails advance past every threshold crossed by one delta. Buffered tracing data remains flushable after tracing is disabled. Aggregated usage entries are copied, visualization identity uses underlying objects, and the prospective contract freezes OutputGuardrailBlockedMessageFormatter as the third public type alias.
   • Files: src/agents/mcp/manager.py, src/agents/mcp/server.py, src/agents/realtime/session.py, src/agents/tracing/provider.py, src/agents/usage.py, src/agents/extensions/visualization.py, integration_tests/_contract_support.py, tests/test_released_api_contract.py
   • Action: No release code change is required; retain these lifecycle, isolation, identity, and contract-policy boundaries.

Documentation coverage (non-blocking)

• Coverage source: docs: document v0.22.1 behavior updates #4577 at head 354ab7e8f58959687892f359debf41f96799ff29; its latest code and security reviews completed with no findings.
• Status: covered
• Covered obligations: OpenAI client precedence; Voice STT, TTS, custom-voice, and client configuration; customizable output-guardrail placeholders and redaction boundaries; missing and empty callable-approval arguments; MCP cache isolation and manager deduplication; empty Chat Completions truncation; Any-LLM extra_body; created_by replay sanitization; Realtime debounce thresholds; Docker labels; tracing flush behavior; usage isolation; visualization identity; and ComputerTool model-selection precedence.
• Gaps or post-release suggestions: none for the identified v0.22.1 documentation obligations.
• Publication timing: Merge docs: document v0.22.1 behavior updates #4577 only after v0.22.1 is publicly available because it documents behavior not present in v0.22.0.

Notes

• Remote tags and origin/main were refreshed immediately before this release call; the latest release tag remains v0.22.0.
• TARGET is the clean release/v0.22.1 checkout at 90857dc76b707549eb8d019895a14a59656adb8a.
• The candidate parent and current origin/main both resolve to 233467994fac7e7dbd868931573cc9a4302c0a16.
• The branch name, pyproject.toml, editable openai-agents lock entry, and released contract agree on v0.22.1.
• The released contract records 233467994fac7e7dbd868931573cc9a4302c0a16 as baseline_commit and freezes 396 callables, 230 canonical imports, 79 public modules, 20 properties, three type aliases, and four TypedDicts.
• The BASE-versus-TARGET contract comparison contains no removals. Its only changed existing callable is RunConfig, where output_guardrail_blocked_message is appended with a None default.
• The prospective packaged-contract gate covered source, wheel, sdist, historical RunState fixtures, public API contracts, and optional dependency profiles.
• The release commit changes only pyproject.toml, uv.lock, and tests/fixtures/released_api_contract.json.
• docs: document v0.22.1 behavior updates #4577 is a separate open documentation change and is not part of the reviewed release target.
• Any change to the base, target commit, release-owned files, version metadata, lockfile, or contract invalidates this gate and requires a complete new review.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-23T04:02:29.972166Z	90857dc	New commits
🔒 Security Review	✅ Completed 2026-08-23T04:02:36.310436Z	90857dc	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b14fff3dd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cd7cce0e6b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".