docs: reorganize navigation and clarify runtime guides (#2568)

Author: seratch

docs/config.md

@@ -1,5 +1,13 @@
 # Configuring the SDK
 
+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.
+
+If you need to configure a specific agent or run instead, start with:
+
+-   [Running agents](running_agents.md) for `RunConfig`, sessions, and conversation-state options.
+-   [Models](models/index.md) for model selection and provider configuration.
+-   [Tracing](tracing.md) for per-run tracing metadata and custom trace processors.
+
 ## API keys and clients
 
 By default, the SDK uses the `OPENAI_API_KEY` environment variable for LLM requests and tracing. The key is resolved when the SDK first creates an OpenAI client (lazy initialization), so set the environment variable before your first model call. If you are unable to set that environment variable before your app starts, you can use the [set_default_openai_key()][agents.set_default_openai_key] function to set the key.
@@ -30,7 +38,7 @@ set_default_openai_api("chat_completions")
 
 ## Tracing
 
-Tracing is enabled by default. It uses the OpenAI API keys from the section above by default (i.e. the environment variable or the default key you set). You can specifically set the API key used for tracing by using the [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] function.
+Tracing is enabled by default. By default it uses the same OpenAI API key as your model requests from the section above (that is, the environment variable or the default key you set). You can specifically set the API key used for tracing by using the [`set_tracing_export_api_key`][agents.set_tracing_export_api_key] function.
 
 ```python
 from agents import set_tracing_export_api_key

docs/guardrails.md

@@ -47,7 +47,7 @@ Tool guardrails wrap **function tools** and let you validate or block tool calls
 
 - Input tool guardrails run before the tool executes and can skip the call, replace the output with a message, or raise a tripwire.
 - Output tool guardrails run after the tool executes and can replace the output or raise a tripwire.
-- Tool guardrails apply only to function tools created with [`function_tool`][agents.function_tool]; hosted tools (`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`) and local runtime tools (`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`) do not use this guardrail pipeline.
+- Tool guardrails apply only to function tools created with [`function_tool`][agents.function_tool]; hosted tools (`WebSearchTool`, `FileSearchTool`, `HostedMCPTool`, `CodeInterpreterTool`, `ImageGenerationTool`) and built-in execution tools (`ComputerTool`, `ShellTool`, `ApplyPatchTool`, `LocalShellTool`) do not use this guardrail pipeline.
 
 See the code snippet below for details.
 

docs/index.md

@@ -54,3 +54,9 @@ print(result.final_output)
 ```bash
 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).

docs/ja/multi_agent.md

@@ -2,7 +2,7 @@
 search:
   exclude: true
 ---
-# 複数エージェントのオーケストレーション
+# エージェントオーケストレーション
 
 オーケストレーションとは、アプリ内でのエージェントの流れのことです。どのエージェントをどの順番で実行し、その後何をするかをどう決めるのか。エージェントをオーケストレーションする主な方法は 2 つあります。
 
@@ -38,4 +38,4 @@ LLM によるオーケストレーションは強力ですが、コードによ
 - 評価とフィードバックを行うエージェントと、タスクを実行するエージェントを `while` ループで回し、評価者が基準を満たしたと判断するまで繰り返す。
 - 複数のエージェントを並列実行する（例: `asyncio.gather` のような Python の基本コンポーネントを使用）。相互依存しない複数タスクがある場合の高速化に有効。
 
-[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数のコード例があります。
+[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns) に複数のコード例があります。

docs/ko/multi_agent.md

@@ -2,7 +2,7 @@
 search:
   exclude: true
 ---
-# 멀티 에이전트 오케스트레이션
+# 에이전트 오케스트레이션
 
 오케스트레이션은 앱에서 에이전트의 흐름을 의미합니다. 어떤 에이전트를 어떤 순서로 실행하고, 다음에 무엇을 할지 어떻게 결정할까요? 에이전트를 오케스트레이션하는 주요 방법은 두 가지입니다:
 
@@ -38,4 +38,4 @@ LLM 기반 오케스트레이션이 강력하긴 하지만, 코드 기반 오케
 - 작업을 수행하는 에이전트와 평가 및 피드백을 제공하는 에이전트를 `while` 루프로 함께 실행하고, 평가자가 출력이 특정 기준을 통과했다고 말할 때까지 반복
 - 여러 에이전트를 병렬로 실행, 예: 파이썬 기본 구성요소 `asyncio.gather` 사용. 서로 의존하지 않는 여러 작업이 있을 때 속도 향상에 유용합니다.
 
-[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 개의 code examples가 있습니다.
+[`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns)에 여러 개의 code examples가 있습니다.

docs/ko/tools.md

@@ -456,7 +456,7 @@ def get_user_profile(user_id: str) -> str:
 
 ## Agents as tools
 
-일부 워크플로에서는 제어를 핸드오프하는 대신 중앙 에이전트가 전문화된 에이전트 네트워크를 멀티 에이전트 오케스트레이션하도록 만들고 싶을 수 있습니다. 이를 위해 에이전트를 도구로 모델링할 수 있습니다.
+일부 워크플로에서는 제어를 핸드오프하는 대신 중앙 에이전트가 전문화된 에이전트 네트워크를 오케스트레이션하도록 만들고 싶을 수 있습니다. 이를 위해 에이전트를 도구로 모델링할 수 있습니다.
 
 ```python
 from agents import Agent, Runner
@@ -737,4 +737,4 @@ agent = Agent(
 -   [Codex tool API reference](ref/extensions/experimental/codex/codex_tool.md)
 -   [ThreadOptions reference](ref/extensions/experimental/codex/thread_options.md)
 -   [TurnOptions reference](ref/extensions/experimental/codex/turn_options.md)
--   전체 실행 가능한 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참고하세요
+-   전체 실행 가능한 샘플은 `examples/tools/codex.py` 및 `examples/tools/codex_same_thread.py`를 참고하세요

docs/multi_agent.md

@@ -1,4 +1,4 @@
-# Orchestrating multiple agents
+# Agent orchestration
 
 Orchestration refers to the flow of agents in your app. Which agents run, in what order, and how do they decide what happens next? There are two main ways to orchestrate agents:
 
@@ -17,6 +17,19 @@ An agent is an LLM equipped with instructions, tools and handoffs. This means th
 -   Code execution to do data analysis
 -   Handoffs to specialized agents that are great at planning, report writing and more.
 
+### Core SDK patterns
+
+In the Python SDK, two orchestration patterns come up most often:
+
+| Pattern | How it works | Best when |
+| --- | --- | --- |
+| Agents as tools | A manager agent keeps control of the conversation and calls specialist agents through `Agent.as_tool()`. | You want one agent to own the final answer, combine outputs from multiple specialists, or enforce shared guardrails in one place. |
+| Handoffs | A triage agent routes the conversation to a specialist, and that specialist becomes the active agent for the rest of the turn. | You want the specialist to respond directly, keep prompts focused, or swap instructions without the manager narrating the result. |
+
+Use **agents as tools** when a specialist should help with a bounded subtask but should not take over the user-facing conversation. Use **handoffs** when routing itself is part of the workflow and you want the chosen specialist to own the next part of the interaction.
+
+You can also combine the two. A triage agent might hand off to a specialist, and that specialist can still call other agents as tools for narrow subtasks.
+
 This pattern is great when the task is open-ended and you want to rely on the intelligence of an LLM. The most important tactics here are:
 
 1. Invest in good prompts. Make it clear what tools are available, how to use them, and what parameters it must operate within.
@@ -25,6 +38,8 @@ This pattern is great when the task is open-ended and you want to rely on the in
 4. Have specialized agents that excel in one task, rather than having a general purpose agent that is expected to be good at anything.
 5. Invest in [evals](https://platform.openai.com/docs/guides/evals). This lets you train your agents to improve and get better at tasks.
 
+If you want the core SDK primitives behind this style of orchestration, start with [tools](tools.md), [handoffs](handoffs.md), and [running agents](running_agents.md).
+
 ## Orchestrating via code
 
 While orchestrating via LLM is powerful, orchestrating via code makes tasks more deterministic and predictable, in terms of speed, cost and performance. Common patterns here are:
@@ -35,3 +50,11 @@ While orchestrating via LLM is powerful, orchestrating via code makes tasks more
 -   Running multiple agents in parallel, e.g. via Python primitives like `asyncio.gather`. This is useful for speed when you have multiple tasks that don't depend on each other.
 
 We have a number of examples in [`examples/agent_patterns`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns).
+
+## Related guides
+
+-   [Agents](agents.md) for composition patterns and agent configuration.
+-   [Tools](tools.md#agents-as-tools) for `Agent.as_tool()` and manager-style orchestration.
+-   [Handoffs](handoffs.md) for delegation between specialist agents.
+-   [Running agents](running_agents.md) for per-run orchestration controls and conversation state.
+-   [Quickstart](quickstart.md) for a minimal end-to-end handoff example.

docs/quickstart.md

@@ -34,158 +34,136 @@ export OPENAI_API_KEY=sk-...
 
 ## Create your first agent
 
-Agents are defined with instructions, a name, and optional config (such as `model_config`)
+Agents are defined with instructions, a name, and optional configuration such as a specific model.
 
 ```python
 from agents import Agent
 
 agent = Agent(
-    name="Math Tutor",
-    instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
+    name="History Tutor",
+    instructions="You answer history questions clearly and concisely.",
 )
 ```
 
-## Add a few more agents
+## Run your first agent
 
-Additional agents can be defined in the same way. `handoff_descriptions` provide additional context for determining handoff routing
+Use [`Runner`][agents.run.Runner] to execute the agent and get a [`RunResult`][agents.result.RunResult] back.
 
 ```python
-from agents import Agent
+import asyncio
+from agents import Agent, Runner
 
-history_tutor_agent = Agent(
+agent = Agent(
     name="History Tutor",
-    handoff_description="Specialist agent for historical questions",
-    instructions="You provide assistance with historical queries. Explain important events and context clearly.",
+    instructions="You answer history questions clearly and concisely.",
 )
 
-math_tutor_agent = Agent(
-    name="Math Tutor",
-    handoff_description="Specialist agent for math questions",
-    instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
-)
-```
-
-## Define your handoffs
-
-On each agent, you can define an inventory of outgoing handoff options that the agent can choose from to decide how to make progress on their task.
+async def main():
+    result = await Runner.run(agent, "When did the Roman Empire fall?")
+    print(result.final_output)
 
-```python
-triage_agent = Agent(
-    name="Triage Agent",
-    instructions="You determine which agent to use based on the user's homework question",
-    handoffs=[history_tutor_agent, math_tutor_agent]
-)
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
-## Run the agent orchestration
+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.
+
+## Give your agent tools
 
-Let's check that the workflow runs and the triage agent correctly routes between the two specialist agents.
+You can give an agent tools to look up information or perform actions.
 
 ```python
-from agents import Runner
+import asyncio
+from agents import Agent, Runner, function_tool
 
-async def main():
-    result = await Runner.run(triage_agent, "who was the first president of the united states?")
-    print(result.final_output)
-```
 
-## Add a guardrail
+@function_tool
+def history_fun_fact() -> str:
+    """Return a short history fact."""
+    return "Sharks are older than trees."
 
-You can define custom guardrails to run on the input or output.
 
-```python
-from agents import GuardrailFunctionOutput, Agent, Runner
-from pydantic import BaseModel
+agent = Agent(
+    name="History Tutor",
+    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
+    tools=[history_fun_fact],
+)
 
 
-class HomeworkOutput(BaseModel):
-    is_homework: bool
-    reasoning: str
+async def main():
+    result = await Runner.run(
+        agent,
+        "Tell me something surprising about ancient life on Earth.",
+    )
+    print(result.final_output)
 
-guardrail_agent = Agent(
-    name="Guardrail check",
-    instructions="Check if the user is asking about homework.",
-    output_type=HomeworkOutput,
-)
 
-async def homework_guardrail(ctx, agent, input_data):
-    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
-    final_output = result.final_output_as(HomeworkOutput)
-    return GuardrailFunctionOutput(
-        output_info=final_output,
-        tripwire_triggered=not final_output.is_homework,
-    )
+if __name__ == "__main__":
+    asyncio.run(main())
 ```
 
-## Put it all together
+## Add a few more agents
 
-Let's put it all together and run the entire workflow, using handoffs and the input guardrail.
+Additional agents can be defined in the same way. `handoff_description` gives the routing agent extra context about when to delegate.
 
 ```python
-from agents import Agent, InputGuardrail, GuardrailFunctionOutput, Runner
-from agents.exceptions import InputGuardrailTripwireTriggered
-from pydantic import BaseModel
-import asyncio
-
-class HomeworkOutput(BaseModel):
-    is_homework: bool
-    reasoning: str
+from agents import Agent
 
-guardrail_agent = Agent(
-    name="Guardrail check",
-    instructions="Check if the user is asking about homework.",
-    output_type=HomeworkOutput,
+history_tutor_agent = Agent(
+    name="History Tutor",
+    handoff_description="Specialist agent for historical questions",
+    instructions="You answer history questions clearly and concisely.",
 )
 
 math_tutor_agent = Agent(
     name="Math Tutor",
     handoff_description="Specialist agent for math questions",
-    instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
-)
-
-history_tutor_agent = Agent(
-    name="History Tutor",
-    handoff_description="Specialist agent for historical questions",
-    instructions="You provide assistance with historical queries. Explain important events and context clearly.",
+    instructions="You explain math step by step and include worked examples.",
 )
+```
 
+## Define your handoffs
 
-async def homework_guardrail(ctx, agent, input_data):
-    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
-    final_output = result.final_output_as(HomeworkOutput)
-    return GuardrailFunctionOutput(
-        output_info=final_output,
-        tripwire_triggered=not final_output.is_homework,
-    )
+On an agent, you can define an inventory of outgoing handoff options that it can choose from while solving the task.
 
+```python
 triage_agent = Agent(
     name="Triage Agent",
-    instructions="You determine which agent to use based on the user's homework question",
+    instructions="Route each homework question to the right specialist.",
     handoffs=[history_tutor_agent, math_tutor_agent],
-    input_guardrails=[
-        InputGuardrail(guardrail_function=homework_guardrail),
-    ],
 )
+```
+
+## Run the agent orchestration
+
+The runner handles executing individual agents, any handoffs, and any tool calls.
+
+```python
+import asyncio
+from agents import Runner
+
 
 async def main():
-    # Example 1: History question
-    try:
-        result = await Runner.run(triage_agent, "who was the first president of the united states?")
-        print(result.final_output)
-    except InputGuardrailTripwireTriggered as e:
-        print("Guardrail blocked this input:", e)
-
-    # Example 2: General/philosophical question
-    try:
-        result = await Runner.run(triage_agent, "What is the meaning of life?")
-        print(result.final_output)
-    except InputGuardrailTripwireTriggered as e:
-        print("Guardrail blocked this input:", e)
+    result = await Runner.run(
+        triage_agent,
+        "Who was the first president of the United States?",
+    )
+    print(result.final_output)
+    print(f"Answered by: {result.last_agent.name}")
+
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## Reference examples
+
+The repository includes full scripts for the same core patterns:
+
+-   [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py) for the first run.
+-   [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py) for function tools.
+-   [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py) for multi-agent routing.
+
 ## View your traces
 
 To review what happened during your agent run, navigate to the [Trace viewer in the OpenAI Dashboard](https://platform.openai.com/traces) to view traces of your agent runs.
@@ -195,5 +173,5 @@ To review what happened during your agent run, navigate to the [Trace viewer in
 Learn how to build more complex agentic flows:
 
 -   Learn about how to configure [Agents](agents.md).
--   Learn about [running agents](running_agents.md).
+-   Learn about [running agents](running_agents.md) and [sessions](sessions/index.md).
 -   Learn about [tools](tools.md), [guardrails](guardrails.md) and [models](models/index.md).