docs: updates for v0.21.0 release

[seratch]

This pull request updates the v0.21.0 documentation with a provider-neutral testing guide for Agent, Sandbox, Realtime, and Voice workflows.

The guide:

• shows fixed, tool-driven, request-aware, streaming, retry, and workflow-drift recipes for ScriptedModel;
• demonstrates a black-box SandboxAgent workflow with scripted_sandbox_session(), including FIFO matching, detached histories, structured errors, and caller-owned session cleanup;
• documents Python-native ScriptedRealtimeModel message and tool workflows instead of the TypeScript scenario API;
• adds full Voice pipeline coverage with scripted STT, TTS, transcription sessions, workflows, and PCM helpers;
• explains when tests should use the provider-neutral utilities and when they should keep the real provider adapter, transport, sandbox provider, or audio integration; and
• adds navigation and API reference coverage for agents.testing, agents.realtime.testing, agents.voice.testing, and the generated agents.testing submodules.

The organization follows the TypeScript testing guide's shared recipe and boundary concepts while preserving the Python SDK's distinct Realtime and Voice APIs.

Test plan

• make build-docs
• Execute representative Agent, Sandbox, Realtime, Realtime tool, retry-advice, and Voice examples without provider requests.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7c1d011f3f

ℹ️ 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".

[FU-max-boop]

Would you be open to a small community-tools note in this testing guide?

I maintain AgentRunProof, a CLI that complements the provider-neutral scripted fixtures here by running the real Runner through deterministic cross-version RunState and approval-resume conformance scenarios. It emits content-addressed verification records and its built-in scenarios make no provider request and require no API key.

A deliberately small addition could be:

## Ecosystem tools

The following community tools complement the SDK's provider-neutral testing APIs.

- [AgentRunProof](https://github.com/FU-max-boop/agentrunproof) runs deterministic cross-version conformance scenarios for serialized `RunState` and approval-resume workflows, and emits reproducible certificates without provider requests.

This is the harness I used to diagnose the checkpoint-isolation gap that led to #4413 and to validate the recursive/serialized fix in #4414. It would add no SDK dependency or runtime behavior, and I would be happy to submit the one-file docs change after this release-docs PR lands if you prefer to keep release preparation separate.

The current PyPI release targets 0.20.x; I am preparing the explicit 0.21 compatibility release in parallel and will not claim 0.21 support until #4387 is published.

[seratch]

@FU-max-boop Thanks for sharing this, and for using your tool to help diagnose #4413 and validate #4414. We really appreciate contributions that use tools like this to find gaps and provide reproducible verification.

For now, we would like to keep this testing guide focused on SDK-maintained testing APIs, so we are not planning to add community tool listings here. That said, contributions and feedback backed by your tool's findings are very welcome.

[FU-max-boop]

Understood — thank you for the clear boundary and the kind words. I’ll keep AgentRunProof external to the SDK and use it to provide narrow, conventional regressions and reproducible before/after validation when it finds a concrete gap. I won’t pursue a community-tools listing in this guide.