openai · seratch · Aug 15, 2026 · Aug 13, 2026
diff --git a/docs/config.md b/docs/config.md
@@ -51,6 +51,30 @@ custom_client = AsyncOpenAI(base_url="...", api_key="...")
 set_default_openai_client(custom_client)
 ```
 
+### Custom HTTP clients with `openai` v3
+
+Version 0.21.0 requires `openai>=3.0.0,<4`. The default OpenAI provider uses HTTPX2, so most applications do not need to configure an HTTP client directly. If your application passes `http_client=` to `AsyncOpenAI`, use HTTPX2 types for the custom client and its transport-facing options:
+
+```python
+import httpx2
+from openai import AsyncOpenAI, DefaultAsyncHttpx2Client
+
+from agents import set_default_openai_client
+
+http_client = DefaultAsyncHttpx2Client(
+    timeout=httpx2.Timeout(30.0, connect=5.0),
+)
+custom_client = AsyncOpenAI(
+    api_key="...",
+    http_client=http_client,
+)
+set_default_openai_client(custom_client)
+```
+
+The same migration applies to custom transports, authentication, event hooks, mock transports, URLs, requests, responses, and transport exception handling. Use their `httpx2` equivalents. The Agents SDK does not convert arbitrary legacy `httpx` objects to HTTPX2. The OpenAI Python SDK provides a temporary compatibility path for legacy clients when the application installs `httpx` explicitly, but new and migrated code should use HTTPX2.
+
+This OpenAI client boundary is separate from local MCP transport customization. MCP Python SDK v1 uses its own legacy `httpx` dependency, while MCP Python SDK v2 uses `httpx2`; see [MCP Python SDK v1 and v2](mcp.md#mcp-python-sdk-v1-and-v2).
+
 If you prefer environment-based endpoint configuration, the default OpenAI provider also reads `OPENAI_BASE_URL`. When you enable Responses websocket transport, it also reads `OPENAI_WEBSOCKET_BASE_URL` for the websocket `/responses` endpoint.
 
 ```bash

diff --git a/docs/ref/realtime/testing.md b/docs/ref/realtime/testing.md
@@ -0,0 +1,3 @@
+# `Testing`
+
+::: agents.realtime.testing
diff --git a/docs/ref/testing.md b/docs/ref/testing.md
@@ -0,0 +1,3 @@
+# `Testing`
+
+::: agents.testing
diff --git a/docs/ref/testing/model.md b/docs/ref/testing/model.md
@@ -0,0 +1,3 @@
+# `Model`
+
+::: agents.testing.model
diff --git a/docs/ref/testing/sandbox.md b/docs/ref/testing/sandbox.md
@@ -0,0 +1,3 @@
+# `Sandbox`
+
+::: agents.testing.sandbox
diff --git a/docs/ref/voice/testing.md b/docs/ref/voice/testing.md
@@ -0,0 +1,3 @@
+# `Testing`
+
+::: agents.voice.testing
diff --git a/docs/release.md b/docs/release.md
@@ -19,6 +19,19 @@ We will increment `Z` for non-breaking changes:
 
 ## Breaking change changelog
 
+### 0.21.0
+
+Version 0.21.0 requires `openai` v3 and moves the Agents SDK's OpenAI HTTP integrations to HTTPX2. Applications that use the default OpenAI client do not need to change their client setup, but applications that customize the OpenAI HTTP layer may need to migrate transport-facing code.
+
+Highlights:
+
+-   The required OpenAI dependency is now `openai>=3.0.0,<4`. A clean core installation uses HTTPX2 and no longer installs legacy `httpx` as a direct dependency.
+-   The default OpenAI provider, Voice provider, Responses WebSocket support, tracing exporter, and provider retry normalization now use HTTPX2. Their existing Agents SDK public configuration and runtime behavior remain unchanged.
+-   Applications that pass `http_client=` to `AsyncOpenAI` should migrate custom clients, transports, authentication, event hooks, mock transports, timeout values, URLs, requests, responses, and transport exception handling from `httpx` to `httpx2`. Prefer the OpenAI Python SDK's `DefaultAsyncHttpx2Client` when the application needs the OpenAI client's defaults plus custom HTTP options. See [Custom HTTP clients with `openai` v3](config.md#custom-http-clients-with-openai-v3).
+-   The Agents SDK does not convert arbitrary legacy HTTPX objects to HTTPX2. The OpenAI Python SDK's temporary legacy-client compatibility path requires an explicit `httpx` installation and should be treated as a migration bridge.
+-   Local MCP HTTP customization continues to follow the installed MCP package: MCP Python SDK v1 supplies and uses legacy `httpx`, while MCP Python SDK v2 uses `httpx2`. Ordinary MCP connections do not need application changes. See [MCP Python SDK v1 and v2](mcp.md#mcp-python-sdk-v1-and-v2).
+-   Public provider-neutral testing utilities now cover Agent model, Sandbox session, Realtime session, and Voice pipeline workflows without provider or process dependencies. See [Testing](testing.md) for recipes and guidance on when to keep the real provider adapter or integration boundary.
+
 ### 0.20.0
 
 Version 0.20.0 includes a potentially breaking MCP dependency migration for applications that customize local MCP HTTP transports. It also updates the SDK default model used when an agent or run does not explicitly select one.

diff --git a/docs/testing.md b/docs/testing.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -54,6 +54,7 @@ plugins:
             - Configuration: config.md
             - Documentation:
                 - Agents: agents.md
+                - Testing: testing.md
                 - Sandbox agents:
                     - Quickstart: sandbox_agents.md
                     - Concepts: sandbox/guide.md
@@ -97,6 +98,7 @@ plugins:
                     - Runner: ref/run.md
                     - Run config: ref/run_config.md
                     - Run state: ref/run_state.md
+                    - Testing: ref/testing.md
                     - Sandbox:
                         - Overview: ref/sandbox.md
                         - SandboxAgent: ref/sandbox/sandbox_agent.md
@@ -166,6 +168,7 @@ plugins:
                     - Events: ref/realtime/events.md
                     - Configuration: ref/realtime/config.md
                     - Model: ref/realtime/model.md
+                    - Testing: ref/realtime/testing.md
                 - Voice:
                     - Pipeline: ref/voice/pipeline.md
                     - Workflow: ref/voice/workflow.md
@@ -179,6 +182,7 @@ plugins:
                     - OpenAI voice model provider: ref/voice/models/openai_provider.md
                     - OpenAI STT: ref/voice/models/openai_stt.md
                     - OpenAI TTS: ref/voice/models/openai_tts.md
+                    - Testing: ref/voice/testing.md
                 - Extensions:
                     - Handoff filters: ref/extensions/handoff_filters.md
                     - Handoff prompt: ref/extensions/handoff_prompt.md