docs: structure improvements (#2538)

Author: seratch

docs/human_in_the_loop.md

@@ -111,7 +111,7 @@ In this example, `prompt_approval` is synchronous because it uses `input()` and
 
 To stream output while waiting for approvals, call `Runner.run_streamed`, consume `result.stream_events()` until it completes, and then follow the same `result.to_state()` and resume steps shown above.
 
-## Other patterns in this repository
+## Repository patterns and examples
 
 - **Streaming approvals**: `examples/agent_patterns/human_in_the_loop_stream.py` shows how to drain `stream_events()` and then approve pending tool calls before resuming with `Runner.run_streamed(agent, state)`.
 - **Agent as tool approvals**: `Agent.as_tool(..., needs_approval=...)` applies the same interruption flow when delegated agent tasks need review.

docs/mcp.md

@@ -51,6 +51,17 @@ Notes:
 - When `failure_error_function` is unset, the SDK uses the default tool error formatter.
 - Server-level `failure_error_function` overrides `Agent.mcp_config["failure_error_function"]` for that server.
 
+## Shared patterns across transports
+
+After you choose a transport, most integrations need the same follow-up decisions:
+
+- How to expose only a subset of tools ([Tool filtering](#tool-filtering)).
+- Whether the server also provides reusable prompts ([Prompts](#prompts)).
+- Whether `list_tools()` should be cached ([Caching](#caching)).
+- How MCP activity appears in traces ([Tracing](#tracing)).
+
+For local MCP servers (`MCPServerStdio`, `MCPServerSse`, `MCPServerStreamableHttp`), approval policies and per-call `_meta` payloads are also shared concepts. The Streamable HTTP section shows the most complete examples, and the same patterns apply to the other local transports.
+
 ## 1. Hosted MCP server tools
 
 Hosted tools push the entire tool round-trip into OpenAI's infrastructure. Instead of your code listing and calling tools, the
@@ -356,6 +367,10 @@ Key behaviors:
 - Call `reconnect(failed_only=True)` to retry failed servers, or `reconnect(failed_only=False)` to restart all servers.
 - Use `connect_timeout_seconds`, `cleanup_timeout_seconds`, and `connect_in_parallel` to tune lifecycle behavior.
 
+## Common server capabilities
+
+The sections below apply across MCP server transports (with the exact API surface depending on the server class).
+
 ## Tool filtering
 
 Each MCP server supports tool filters so that you can expose only the functions that your agent needs. Filtering can happen at

docs/models/index.md

@@ -5,6 +5,18 @@ The Agents SDK comes with out-of-the-box support for OpenAI models in two flavor
 -   **Recommended**: the [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel], which calls OpenAI APIs using the new [Responses API](https://platform.openai.com/docs/api-reference/responses).
 -   The [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel], which calls OpenAI APIs using the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat).
 
+## Choosing a model setup
+
+Use this page in the following order depending on your setup:
+
+| Goal | Start here |
+| --- | --- |
+| Use OpenAI-hosted models with SDK defaults | [OpenAI models](#openai-models) |
+| Use OpenAI Responses API over websocket transport | [Responses WebSocket transport](#responses-websocket-transport) |
+| Use non-OpenAI providers | [Non-OpenAI models](#non-openai-models) |
+| Mix models/providers in one workflow | [Advanced model selection and mixing](#advanced-model-selection-and-mixing) and [Mixing models across providers](#mixing-models-across-providers) |
+| Debug provider compatibility issues | [Troubleshooting non-OpenAI providers](#troubleshooting-non-openai-providers) |
+
 ## OpenAI models
 
 When you don't specify a model when initializing an `Agent`, the default model will be used. The default is currently [`gpt-4.1`](https://platform.openai.com/docs/models/gpt-4.1) for compatibility and low latency. If you have access, we recommend setting your agents to [`gpt-5.2`](https://platform.openai.com/docs/models/gpt-5.2) for higher quality while keeping explicit `model_settings`.
@@ -129,7 +141,7 @@ In cases where you do not have an API key from `platform.openai.com`, we recomme
 
     In these examples, we use the Chat Completions API/model, because most LLM providers don't yet support the Responses API. If your LLM provider does support it, we recommend using Responses.
 
-## Mixing and matching models
+## Advanced model selection and mixing
 
 Within a single workflow, you may want to use different models for each agent. For example, you could use a smaller, faster model for triage, while using a larger, more capable model for complex tasks. When configuring an [`Agent`][agents.Agent], you can select a specific model by either:
 
@@ -204,7 +216,7 @@ english_agent = Agent(
 )
 ```
 
-## Common issues with using other LLM providers
+## Troubleshooting non-OpenAI providers
 
 ### Tracing client error 401
 

docs/realtime/guide.md

@@ -1,4 +1,4 @@
-# Guide
+# Realtime agents guide
 
 This guide provides an in-depth look at building voice-enabled AI agents using the OpenAI Agents SDK's realtime capabilities.
 
@@ -123,7 +123,9 @@ main_agent = RealtimeAgent(
 )
 ```
 
-## Event handling
+## Runtime behavior and session handling
+
+### Event handling
 
 The session streams events that you can listen to by iterating over the session object. Events include audio output chunks, transcription results, tool execution start and end, agent handoffs, and errors. Key events to handle include:
 
@@ -136,7 +138,7 @@ The session streams events that you can listen to by iterating over the session
 
 For complete event details, see [`RealtimeSessionEvent`][agents.realtime.events.RealtimeSessionEvent].
 
-## Guardrails
+### Guardrails
 
 Only output guardrails are supported for realtime agents. These guardrails are debounced and run periodically (not on every word) to avoid performance issues during real-time generation. The default debounce length is 100 characters, but this is configurable.
 
@@ -160,13 +162,15 @@ agent = RealtimeAgent(
 
 When a guardrail is triggered, it generates a `guardrail_tripped` event and can interrupt the agent's current response. The debounce behavior helps balance safety with real-time performance requirements. Unlike text agents, realtime agents do **not** raise an Exception when guardrails are tripped.
 
-## Audio processing
+### Audio processing
 
 Send audio to the session using [`session.send_audio(audio_bytes)`][agents.realtime.session.RealtimeSession.send_audio] or send text using [`session.send_message()`][agents.realtime.session.RealtimeSession.send_message].
 
 For audio output, listen for `audio` events and play the audio data through your preferred audio library. Make sure to listen for `audio_interrupted` events to stop playback immediately and clear any queued audio when the user interrupts the agent.
 
-## SIP integration
+## Advanced integrations and low-level access
+
+### SIP integration
 
 You can attach realtime agents to phone calls that arrive via the [Realtime Calls API](https://platform.openai.com/docs/guides/realtime-sip). The SDK provides [`OpenAIRealtimeSIPModel`][agents.realtime.openai_realtime.OpenAIRealtimeSIPModel], which reuses the same agent flow while negotiating media over SIP.
 
@@ -195,7 +199,7 @@ async with await runner.run(
 
 When the caller hangs up, the SIP session ends and the realtime connection closes automatically. For a complete telephony example, see [`examples/realtime/twilio_sip`](https://github.com/openai/openai-agents-python/tree/main/examples/realtime/twilio_sip).
 
-## Direct model access
+### Direct model access
 
 You can access the underlying model to add custom listeners or perform advanced operations:
 
@@ -206,11 +210,11 @@ session.model.add_listener(my_custom_listener)
 
 This gives you direct access to the [`RealtimeModel`][agents.realtime.model.RealtimeModel] interface for advanced use cases where you need lower-level control over the connection.
 
-## Examples
+### Examples and further reading
 
 For complete working examples, check out the [examples/realtime directory](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) which includes demos with and without UI components.
 
-## Azure OpenAI endpoint format
+### Azure OpenAI endpoint format
 
 When connecting to Azure OpenAI, use the GA Realtime endpoint format and pass credentials via
 headers in `model_config`:

docs/realtime/quickstart.md

@@ -105,9 +105,9 @@ def _truncate_str(s: str, max_length: int) -> str:
     return s
 ```
 
-## Complete example
+## Full example (same flow in one file)
 
-Here's a complete working example:
+This is the same quickstart flow rewritten as a single script.
 
 ```python
 import asyncio
@@ -184,7 +184,9 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## Configuration options
+## Configuration and deployment notes
+
+Use these options after you have a basic session running.
 
 ### Model settings
 
@@ -215,15 +217,7 @@ if __name__ == "__main__":
 
 For the full schema, see the API reference for [`RealtimeRunConfig`][agents.realtime.config.RealtimeRunConfig] and [`RealtimeSessionModelSettings`][agents.realtime.config.RealtimeSessionModelSettings].
 
-## Next steps
-
--   [Learn more about realtime agents](guide.md)
--   Check out working examples in the [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) folder
--   Add tools to your agent
--   Implement handoffs between agents
--   Set up guardrails for safety
-
-## Authentication
+### Authentication
 
 Make sure your OpenAI API key is set in your environment:
 
@@ -237,7 +231,7 @@ Or pass it directly when creating the session:
 session = await runner.run(model_config={"api_key": "your-api-key"})
 ```
 
-## Azure OpenAI endpoint format
+### Azure OpenAI endpoint format
 
 If you connect to Azure OpenAI instead of OpenAI's default endpoint, pass a GA Realtime URL in
 `model_config["url"]` and set auth headers explicitly.
@@ -264,3 +258,11 @@ session = await runner.run(
 
 Avoid using the legacy beta path (`/openai/realtime?api-version=...`) with realtime agents. The
 SDK expects the GA Realtime interface.
+
+## Next steps
+
+-   [Learn more about realtime agents](guide.md)
+-   Check out working examples in the [examples/realtime](https://github.com/openai/openai-agents-python/tree/main/examples/realtime) folder
+-   Add tools to your agent
+-   Implement handoffs between agents
+-   Set up guardrails for safety