docs: clarify realtime transport boundaries and SIP attach flows (#2591)

Author: seratch

docs/examples.md

@@ -69,10 +69,10 @@ Check out a variety of sample implementations of the SDK in the examples section
 -   **[realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime):**
     Examples showing how to build real-time experiences using the SDK, including:
 
-    -   Web applications
-    -   Command-line interfaces
-    -   Twilio integration
-    -   Twilio SIP integration
+    -   Web application patterns with structured text and image messages
+    -   Command-line audio loops and playback handling
+    -   Twilio Media Streams integration over WebSocket
+    -   Twilio SIP integration using Realtime Calls API attach flows
 
 -   **[reasoning_content](https://github.com/openai/openai-agents-python/tree/main/examples/reasoning_content):**
     Examples demonstrating how to work with reasoning content and structured outputs.

docs/human_in_the_loop.md

@@ -119,7 +119,7 @@ To stream output while waiting for approvals, call `Runner.run_streamed`, consum
 - **Local MCP servers**: Use `require_approval` on `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` to gate MCP tool calls (see `examples/mcp/get_all_mcp_tools_example/main.py` and `examples/mcp/tool_filter_example/main.py`).
 - **Hosted MCP servers**: Set `require_approval` to `"always"` on `HostedMCPTool` to force HITL, optionally providing `on_approval_request` to auto-approve or reject (see `examples/hosted_mcp/human_in_the_loop.py` and `examples/hosted_mcp/on_approval.py`). Use `"never"` for trusted servers (`examples/hosted_mcp/simple.py`).
 - **Sessions and memory**: Pass a session to `Runner.run` so approvals and conversation history survive multiple turns. SQLite and OpenAI Conversations session variants are in `examples/memory/memory_session_hitl_example.py` and `examples/memory/openai_session_hitl_example.py`.
-- **Realtime agents**: The realtime demo exposes WebSocket messages that approve or reject tool calls via `approve_tool_call` / `reject_tool_call` on the `RealtimeSession` (see `examples/realtime/app/server.py` for the server-side handlers).
+- **Realtime agents**: The realtime demo exposes WebSocket messages that approve or reject tool calls via `approve_tool_call` / `reject_tool_call` on the `RealtimeSession` (see `examples/realtime/app/server.py` for the server-side handlers and [Realtime guide](realtime/guide.md#tool-approvals) for the API surface).
 
 ## Long-running approvals
 

docs/index.md

@@ -73,5 +73,5 @@ Use this table when you know the job you want to do, but not which page explains
 | Keep memory across turns | [Running agents](running_agents.md#choose-a-memory-strategy) and [Sessions](sessions/index.md) |
 | Use OpenAI models, websocket transport, or non-OpenAI providers | [Models](models/index.md) |
 | Review outputs, run items, interruptions, and resume state | [Results](results.md) |
-| Build a low-latency voice agent | [Realtime agents quickstart](realtime/quickstart.md) |
+| Build a low-latency voice agent | [Realtime agents quickstart](realtime/quickstart.md) and [Realtime transport](realtime/transport.md) |
 | Build a speech-to-text / agent / text-to-speech pipeline | [Voice pipeline quickstart](voice/quickstart.md) |

docs/llms-full.txt

@@ -34,7 +34,8 @@ The Agents SDK delivers a focused set of Python primitives—agents, tools, guar
 - [Voice pipeline](https://openai.github.io/openai-agents-python/voice/pipeline/): Customize audio capture, buffering, model invocation, and playback in voice-first experiences.
 - [Voice tracing](https://openai.github.io/openai-agents-python/voice/tracing/): Inspect voice session traces, latency breakdowns, and audio event timelines.
 - [Realtime quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/): Launch realtime agents over websockets (WebRTC is not available in the Python SDK), subscribe to events, and manage low-latency execution.
-- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into realtime session lifecycle, event schemas, concurrency, and backpressure handling.
+- [Realtime transport](https://openai.github.io/openai-agents-python/realtime/transport/): Choose between the default server-side WebSocket path and SIP attach flows, with the browser WebRTC boundary called out explicitly.
+- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into realtime session lifecycle, structured input, approvals, interruptions, and low-level transport control.
 
 ## Models and Provider Integrations
 - [Model catalog](https://openai.github.io/openai-agents-python/models/): Lists supported OpenAI and partner models with guidance on selecting capabilities for different workloads.

docs/llms.txt

@@ -37,7 +37,8 @@ The SDK focuses on a concise set of primitives so you can orchestrate multi-agen
 - [Voice quickstart](https://openai.github.io/openai-agents-python/voice/quickstart/): Build speech-enabled agents with streaming transcription and TTS.
 - [Voice pipeline](https://openai.github.io/openai-agents-python/voice/pipeline/): Customize audio ingestion, tool execution, and response rendering.
 - [Realtime quickstart](https://openai.github.io/openai-agents-python/realtime/quickstart/): Stand up low-latency realtime agents with websocket transport (WebRTC is not available in the Python SDK).
-- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into session lifecycle, event formats, and concurrency patterns.
+- [Realtime transport](https://openai.github.io/openai-agents-python/realtime/transport/): Decide between the default server-side WebSocket path and SIP attach flows, with the browser WebRTC boundary called out explicitly.
+- [Realtime guide](https://openai.github.io/openai-agents-python/realtime/guide/): Deep dive into session lifecycle, structured input, approvals, interruptions, and low-level transport control.
 
 ## API Reference Highlights
 - [Agents API index](https://openai.github.io/openai-agents-python/ref/index/): Entry point for class and function documentation throughout the SDK.