release: 0.22.0 - #4523

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

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

Diff

v0.21.1...370bb71

Release intent

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

Release call

🟢 GREEN LIGHT TO SHIP The candidate is internally consistent, current with origin/main, and no concrete release blocker was found.

Scope summary

• 119 files changed (+9,677/-3,089); key areas include output-guardrail persistence, Responses terminal handling, RunState usage isolation, provider validation, visualization, sandbox and tracing fixes, repository workflows, tests, and release metadata.

Risk assessment (ordered by impact)

1. Terminal tool-output guardrail redaction

   • Risk: 🟢 LOW. Rejected terminal function-tool payloads are no longer retained across session history, RunState, streamed state, or sandbox memory input.
   • Evidence: The runner reconstructs replay-safe call/output pairs from allowlisted fields, uses the fixed withheld-output marker, and discards unsupported or reasoning-bearing response suffixes.
   • Files: src/agents/run_internal/blocked_output.py, src/agents/run.py, src/agents/run_internal/run_loop.py
   • Action: Preserve the exact placeholder and fail-closed fallback wording in the post-release documentation.

2. Responses terminal failures and explicit-client validation

   • Risk: 🟢 LOW. Non-streaming failed and incomplete Responses now match streaming failure behavior. OpenAIProvider now rejects organization or project when an explicit client is also supplied.
   • Evidence: OpenAIResponsesModel and the Responses path in AnyLLMModel raise ModelBehaviorError; duplicate explicit-client configuration raises UserError.
   • Files: src/agents/models/openai_responses.py, src/agents/extensions/models/any_llm_model.py, src/agents/models/openai_provider.py
   • Action: Applications using an explicit client must configure account and connection values on AsyncOpenAI.

3. RunState usage checkpoint isolation

   • Risk: 🟢 LOW. Resumed checkpoints no longer mutate usage held by their source result or sibling checkpoints.
   • Evidence: _copy_for_run_state() deep-copies usage while cached nested Agent.as_tool() resumes explicitly rebind usage to the active outer context.
   • Files: src/agents/run_context.py, src/agents/agent.py
   • Action: Retain the distinction between independent top-level checkpoints and nested usage aggregation.

4. Visualization and clone semantics

   • Risk: 🟢 LOW. Graph generation now expands live targets registered through handoff(agent), while clone documentation accurately describes existing shallow-list ownership.
   • Evidence: Visualization resolves weak agent references and recursively traverses available targets; clone behavior itself remains shallow.
   • Files: src/agents/extensions/visualization.py, src/agents/agent.py, src/agents/realtime/agent.py
   • Action: Publish the matching usage guidance after the package release.

Documentation coverage (non-blocking)

• Coverage source: docs: document v0.22.0 behavior changes #4522 at head edfd1114a7b965493b98547bc1603f16361e3e4c
• Status: covered
• Covered obligations: release summary, output-guardrail redaction, guardrail-result sanitization, failed/incomplete Responses behavior, explicit-client option exclusivity, RunState usage snapshots, clone list sharing, and visualization handoff expansion
• Gaps or post-release suggestions: none
• Publication timing: merge docs: document v0.22.0 behavior changes #4522 after version 0.22.0 is released

Key Changes draft

Key Changes

Version 0.22.0 is a minor release because it adds substantial runtime hardening and tightens an existing provider configuration contract. Applications that combine an explicit openai_client with organization or project must move those values to the AsyncOpenAI client.

Highlights:

• Redacts terminal function-tool output rejected by agent output guardrails from replayable and persisted SDK state.
• Raises ModelBehaviorError for non-streaming Responses with terminal status failed or incomplete.
• Rejects conflicting provider options when OpenAIProvider receives an explicit client.
• Isolates usage accounting between independent RunState checkpoints while preserving nested-agent aggregation.
• Expands agents registered through handoff(agent) in generated graphs.
• Clarifies the existing shallow-copy behavior of Agent.clone() and RealtimeAgent.clone().

Notes

• The candidate branch, package metadata, lockfile, contract baseline, and intended version all agree.
• The release commit changes only the three release-owned files.
• The prospective packaged-contract gate completed successfully, and the frozen API contract is current for 0.22.0.
• origin/main remained at the reviewed parent after the final freshness check.