docs: add prompt template setup steps and MCP server manager guide (#2362)

Author: seratch

docs/agents.md

@@ -9,6 +9,7 @@ The most common properties of an agent you'll configure are:
 -   `name`: A required string that identifies your agent.
 -   `instructions`: also known as a developer message or system prompt.
 -   `model`: which LLM to use, and optional `model_settings` to configure model tuning parameters like temperature, top_p, etc.
+-   `prompt`: Reference a prompt template by id (and variables) when using OpenAI's Responses API.
 -   `tools`: Tools that the agent can use to achieve its tasks.
 -   `mcp_servers`: MCP servers that provide tools to the agent. See the [MCP guide](mcp.md).
 -   `reset_tool_choice`: Whether to reset `tool_choice` after a tool call (default: `True`) to avoid tool-use loops. See [Forcing tool use](#forcing-tool-use).
@@ -29,6 +30,65 @@ agent = Agent(
 )
 ```
 
+## Prompt templates
+
+You can reference a prompt template created in the OpenAI platform by setting `prompt`. This works with OpenAI models using the Responses API.
+
+To use it, please:
+
+1. Go to https://platform.openai.com/playground/prompts
+2. Create a new prompt variable, `poem_style`.
+3. Create a system prompt with the content:
+
+    ```
+    Write a poem in {{poem_style}}
+    ```
+
+4. Run the example with the `--prompt-id` flag.
+
+```python
+from agents import Agent
+
+agent = Agent(
+    name="Prompted assistant",
+    prompt={
+        "id": "pmpt_123",
+        "version": "1",
+        "variables": {"poem_style": "haiku"},
+    },
+)
+```
+
+You can also generate the prompt dynamically at run time:
+
+```python
+from dataclasses import dataclass
+
+from agents import Agent, GenerateDynamicPromptData, Runner
+
+@dataclass
+class PromptContext:
+    prompt_id: str
+    poem_style: str
+
+
+async def build_prompt(data: GenerateDynamicPromptData):
+    ctx: PromptContext = data.context.context
+    return {
+        "id": ctx.prompt_id,
+        "version": "1",
+        "variables": {"poem_style": ctx.poem_style},
+    }
+
+
+agent = Agent(name="Prompted assistant", prompt=build_prompt)
+result = await Runner.run(
+    agent,
+    "Say hello",
+    context=PromptContext(prompt_id="pmpt_123", poem_style="limerick"),
+)
+```
+
 ## Context
 
 Agents are generic on their `context` type. Context is a dependency-injection tool: it's an object you create and pass to `Runner.run()`, that is passed to every agent, tool, handoff etc, and it serves as a grab bag of dependencies and state for the agent run. You can provide any Python object as the context.

docs/config.md

@@ -38,6 +38,13 @@ from agents import set_tracing_export_api_key
 set_tracing_export_api_key("sk-...")
 ```
 
+If you need to attribute traces to a specific organization or project when using the default exporter, set these environment variables before your app starts:
+
+```bash
+export OPENAI_ORG_ID="org_..."
+export OPENAI_PROJECT_ID="proj_..."
+```
+
 You can also set a tracing API key per run without changing the global exporter.
 
 ```python

docs/mcp.md

@@ -243,6 +243,37 @@ async with MCPServerStdio(
     print(result.final_output)
 ```
 
+## 5. MCP server manager
+
+When you have multiple MCP servers, use `MCPServerManager` to connect them up front and expose the connected subset to your agents.
+
+```python
+from agents import Agent, Runner
+from agents.mcp import MCPServerManager, MCPServerStreamableHttp
+
+servers = [
+    MCPServerStreamableHttp(name="calendar", params={"url": "http://localhost:8000/mcp"}),
+    MCPServerStreamableHttp(name="docs", params={"url": "http://localhost:8001/mcp"}),
+]
+
+async with MCPServerManager(servers) as manager:
+    agent = Agent(
+        name="Assistant",
+        instructions="Use MCP tools when they help.",
+        mcp_servers=manager.active_servers,
+    )
+    result = await Runner.run(agent, "Which MCP tools are available?")
+    print(result.final_output)
+```
+
+Key behaviors:
+
+- `active_servers` includes only successfully connected servers when `drop_failed_servers=True` (the default).
+- Failures are tracked in `failed_servers` and `errors`.
+- Set `strict=True` to raise on the first connection failure.
+- 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.
+
 ## 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/ref/extensions/experimental/codex/codex.md

@@ -0,0 +1,3 @@
+# `Codex`
+
+::: agents.extensions.experimental.codex.codex

docs/ref/extensions/experimental/codex/codex_options.md

@@ -0,0 +1,3 @@
+# `Codex Options`
+
+::: agents.extensions.experimental.codex.codex_options

docs/ref/extensions/experimental/codex/codex_tool.md

@@ -0,0 +1,3 @@
+# `Codex Tool`
+
+::: agents.extensions.experimental.codex.codex_tool

docs/ref/extensions/experimental/codex/events.md

@@ -0,0 +1,3 @@
+# `Events`
+
+::: agents.extensions.experimental.codex.events

docs/ref/extensions/experimental/codex/exec.md

@@ -0,0 +1,3 @@
+# `Exec`
+
+::: agents.extensions.experimental.codex.exec

docs/ref/extensions/experimental/codex/items.md

@@ -0,0 +1,3 @@
+# `Items`
+
+::: agents.extensions.experimental.codex.items

docs/ref/extensions/experimental/codex/output_schema_file.md

@@ -0,0 +1,3 @@
+# `Output Schema File`
+
+::: agents.extensions.experimental.codex.output_schema_file