docs: improve documentation entry points and navigation (#2578)

Author: seratch

docs/config.md

@@ -1,4 +1,4 @@
-# Configuring the SDK
+# Configuration
 
 This page covers SDK-wide defaults that you usually set once during application startup, such as the default OpenAI key or client, the default OpenAI API shape, tracing export defaults, and logging behavior.
 

docs/index.md

@@ -58,5 +58,20 @@ export OPENAI_API_KEY=sk-...
 ## Start here
 
 -   Build your first text-based agent with the [Quickstart](quickstart.md).
--   Build a low-latency voice agent with the [Realtime agents quickstart](realtime/quickstart.md).
--   If you want a speech-to-text / agent / text-to-speech pipeline instead, see the [Voice pipeline quickstart](voice/quickstart.md).
+-   Then decide how you want to carry state across turns in [Running agents](running_agents.md#choose-a-memory-strategy).
+-   If you are deciding between handoffs and manager-style orchestration, read [Agent orchestration](multi_agent.md).
+
+## Choose your path
+
+Use this table when you know the job you want to do, but not which page explains it.
+
+| Goal | Start here |
+| --- | --- |
+| Build the first text agent and see one complete run | [Quickstart](quickstart.md) |
+| Add function tools, hosted tools, or agents as tools | [Tools](tools.md) |
+| Decide between handoffs and manager-style orchestration | [Agent orchestration](multi_agent.md) |
+| 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 speech-to-text / agent / text-to-speech pipeline | [Voice pipeline quickstart](voice/quickstart.md) |

docs/quickstart.md

@@ -68,6 +68,16 @@ if __name__ == "__main__":
 
 For a second turn, you can either pass `result.to_input_list()` back into `Runner.run(...)`, attach a [session](sessions/index.md), or reuse OpenAI server-managed state with `conversation_id` / `previous_response_id`. The [running agents](running_agents.md) guide compares these approaches.
 
+Use this rule of thumb:
+
+| If you want... | Start with... |
+| --- | --- |
+| Full manual control and provider-agnostic history | `result.to_input_list()` |
+| The SDK to load and save history for you | [`session=...`](sessions/index.md) |
+| OpenAI-managed server-side continuation | `previous_response_id` or `conversation_id` |
+
+For the tradeoffs and exact behaviors, see [Running agents](running_agents.md#choose-a-memory-strategy).
+
 ## Give your agent tools
 
 You can give an agent tools to look up information or perform actions.
@@ -104,6 +114,13 @@ if __name__ == "__main__":
 
 ## Add a few more agents
 
+Before you choose a multi-agent pattern, decide who should own the final answer:
+
+-   **Handoffs**: a specialist takes over the conversation for that part of the turn.
+-   **Agents as tools**: an orchestrator stays in control and calls specialists as tools.
+
+This quickstart continues with **handoffs** because it is the shortest first example. For the manager-style pattern, see [Agent orchestration](multi_agent.md) and [Tools: agents as tools](tools.md#agents-as-tools).
+
 Additional agents can be defined in the same way. `handoff_description` gives the routing agent extra context about when to delegate.
 
 ```python

docs/results.md

@@ -18,6 +18,7 @@ Most applications only need a few result properties or helpers:
 | `new_items` | Rich run items with agent, tool, and handoff metadata for logs, UIs, or audits. |
 | `last_agent` | The agent that should usually handle the next turn. |
 | `last_response_id` | Continuation with `previous_response_id` on the next OpenAI Responses turn. |
+| `agent_tool_invocation` | Metadata about the outer tool call when this result came from `Agent.as_tool()`. |
 | `interruptions` | Pending tool approvals you must resolve before resuming. |
 | `to_state()` | A serializable snapshot for pause/resume or durable job workflows. |
 
@@ -63,6 +64,16 @@ The [`new_items`][agents.result.RunResultBase.new_items] property contains the n
 
 Call [`result.to_state()`][agents.result.RunResult.to_state] when you need a serializable snapshot of the run. This is the bridge between a finished or paused run and a later resume, especially for approval flows or durable worker systems.
 
+## Agent-as-tool metadata
+
+When a result comes from a nested [`Agent.as_tool()`][agents.agent.Agent.as_tool] run, [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] exposes immutable metadata about the outer tool call:
+
+-   `tool_name`
+-   `tool_call_id`
+-   `tool_arguments`
+
+For ordinary top-level runs, `agent_tool_invocation` is `None`.
+
 ## Other information
 
 ### Guardrail results
@@ -110,4 +121,5 @@ approval workflows, see the [human-in-the-loop guide](human_in_the_loop.md).
 
 - [`final_output_as(...)`][agents.result.RunResultBase.final_output_as] casts final output to a specific type (optionally with runtime type checking).
 - [`last_response_id`][agents.result.RunResultBase.last_response_id] returns the latest model response ID. Pass this back as `previous_response_id` when you want to continue an OpenAI Responses API chain on the next turn.
+- [`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation] returns metadata about the outer tool call when the result comes from `Agent.as_tool()`.
 - [`release_agents(...)`][agents.result.RunResultBase.release_agents] drops strong references to agents when you want to reduce memory pressure after inspecting results.

docs/tools.md

@@ -577,6 +577,11 @@ json_tool = data_agent.as_tool(
 )
 ```
 
+Inside a custom extractor, the nested [`RunResult`][agents.result.RunResult] also exposes
+[`agent_tool_invocation`][agents.result.RunResultBase.agent_tool_invocation], which is useful when
+you need the outer tool name, call ID, or raw arguments while post-processing the nested result.
+See the [Results guide](results.md#agent-as-tool-metadata).
+
 ### Streaming nested agent runs
 
 Pass an `on_stream` callback to `as_tool` to listen to streaming events emitted by the nested agent while still returning its final output once the stream completes.

docs/tracing.md

@@ -4,10 +4,11 @@ The Agents SDK includes built-in tracing, collecting a comprehensive record of e
 
 !!!note
 
-    Tracing is enabled by default. There are two ways to disable tracing:
+    Tracing is enabled by default. You can disable it in three common ways:
 
     1. You can globally disable tracing by setting the env var `OPENAI_AGENTS_DISABLE_TRACING=1`
-    2. You can disable tracing for a single run by setting [`agents.run.RunConfig.tracing_disabled`][] to `True`
+    2. You can globally disable tracing in code with [`set_tracing_disabled(True)`][agents.set_tracing_disabled]
+    3. You can disable tracing for a single run by setting [`agents.run.RunConfig.tracing_disabled`][] to `True`
 
 ***For organizations operating under a Zero Data Retention (ZDR) policy using OpenAI's APIs, tracing is unavailable.***
 

mkdocs.yml

@@ -53,9 +53,8 @@ plugins:
           nav:
             - Intro: index.md
             - Quickstart: quickstart.md
-            - config.md
+            - Configuration: config.md
             - Documentation:
-                - multi_agent.md
                 - agents.md
                 - Models:
                     - models/index.md
@@ -64,6 +63,7 @@ plugins:
                 - guardrails.md
                 - running_agents.md
                 - streaming.md
+                - multi_agent.md
                 - handoffs.md
                 - results.md
                 - human_in_the_loop.md
@@ -174,7 +174,6 @@ plugins:
             - クイックスタート: quickstart.md
             - config.md
             - ドキュメント:
-                - multi_agent.md
                 - agents.md
                 - モデル:
                     - models/index.md
@@ -183,6 +182,7 @@ plugins:
                 - guardrails.md
                 - running_agents.md
                 - streaming.md
+                - multi_agent.md
                 - handoffs.md
                 - results.md
                 - human_in_the_loop.md
@@ -214,7 +214,6 @@ plugins:
             - 빠른 시작: quickstart.md
             - config.md
             - 문서:
-                - multi_agent.md
                 - agents.md
                 - 모델:
                     - models/index.md
@@ -223,6 +222,7 @@ plugins:
                 - guardrails.md
                 - running_agents.md
                 - streaming.md
+                - multi_agent.md
                 - handoffs.md
                 - results.md
                 - human_in_the_loop.md
@@ -254,7 +254,6 @@ plugins:
             - 快速开始: quickstart.md
             - config.md
             - 文档:
-                - multi_agent.md
                 - agents.md
                 - 模型:
                     - models/index.md
@@ -263,6 +262,7 @@ plugins:
                 - guardrails.md
                 - running_agents.md
                 - streaming.md
+                - multi_agent.md
                 - handoffs.md
                 - results.md
                 - human_in_the_loop.md