docs: improve doc coverage for Dapr sessions and advanced model settings (#2587)

Author: seratch

docs/examples.md

@@ -58,8 +58,10 @@ Check out a variety of sample implementations of the SDK in the examples section
     -   Advanced SQLite session storage
     -   Redis session storage
     -   SQLAlchemy session storage
+    -   Dapr state store session storage
     -   Encrypted session storage
-    -   OpenAI session storage
+    -   OpenAI Conversations session storage
+    -   Responses compaction session storage
 
 -   **[model_providers](https://github.com/openai/openai-agents-python/tree/main/examples/model_providers):**
     Explore how to use non-OpenAI models with the SDK, including custom providers and LiteLLM integration.

docs/models/index.md

@@ -204,6 +204,36 @@ english_agent = Agent(
 )
 ```
 
+#### Common advanced `ModelSettings` options
+
+When you are using the OpenAI Responses API, several request fields already have direct `ModelSettings` fields, so you do not need `extra_args` for them.
+
+| Field | Use it for |
+| --- | --- |
+| `parallel_tool_calls` | Allow or forbid multiple tool calls in the same turn. |
+| `truncation` | Set `"auto"` to let the Responses API drop the oldest conversation items instead of failing when context would overflow. |
+| `prompt_cache_retention` | Keep cached prompt prefixes around longer, for example with `"24h"`. |
+| `response_include` | Request richer response payloads such as `web_search_call.action.sources`, `file_search_call.results`, or `reasoning.encrypted_content`. |
+| `top_logprobs` | Request top-token logprobs for output text. The SDK also adds `message.output_text.logprobs` automatically. |
+
+```python
+from agents import Agent, ModelSettings
+
+research_agent = Agent(
+    name="Research agent",
+    model="gpt-5.2",
+    model_settings=ModelSettings(
+        parallel_tool_calls=False,
+        truncation="auto",
+        prompt_cache_retention="24h",
+        response_include=["web_search_call.action.sources"],
+        top_logprobs=5,
+    ),
+)
+```
+
+Use `extra_args` when you need provider-specific or newer request fields that the SDK does not expose directly at the top level yet.
+
 Also, when you use OpenAI's Responses API, [there are a few other optional parameters](https://platform.openai.com/docs/api-reference/responses/create) (e.g., `user`, `service_tier`, and so on). If they are not available at the top level, you can use `extra_args` to pass them as well.
 
 ```python

docs/ref/extensions/memory/dapr_session.md

@@ -1,2 +1,3 @@
-# ::: agents.extensions.memory.dapr_session.DaprSession
+# `DaprSession`
 
+::: agents.extensions.memory.dapr_session.DaprSession

docs/sessions/index.md

@@ -204,6 +204,7 @@ Use this table to pick a starting point before reading the detailed examples bel
 | `AsyncSQLiteSession` | Async SQLite with `aiosqlite` | Extension backend with async driver support |
 | `RedisSession` | Shared memory across workers/services | Good for low-latency distributed deployments |
 | `SQLAlchemySession` | Production apps with existing databases | Works with SQLAlchemy-supported databases |
+| `DaprSession` | Cloud-native deployments with Dapr sidecars | Supports multiple state stores plus TTL and consistency controls |
 | `OpenAIConversationsSession` | Server-managed storage in OpenAI | OpenAI Conversations API-backed history |
 | `OpenAIResponsesCompactionSession` | Long conversations with automatic compaction | Wrapper around another session backend |
 | `AdvancedSQLiteSession` | SQLite plus branching/analytics | Heavier feature set; see dedicated page |
@@ -377,6 +378,36 @@ session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 
 See [SQLAlchemy Sessions](sqlalchemy_session.md) for detailed documentation.
 
+### Dapr sessions
+
+Use `DaprSession` when you already run Dapr sidecars or want session storage that can move across different state-store backends without changing your agent code.
+
+```bash
+pip install openai-agents[dapr]
+```
+
+```python
+from agents import Agent, Runner
+from agents.extensions.memory import DaprSession
+
+agent = Agent(name="Assistant")
+
+async with DaprSession.from_address(
+    "user_123",
+    state_store_name="statestore",
+    dapr_address="localhost:50001",
+) as session:
+    result = await Runner.run(agent, "Hello", session=session)
+    print(result.final_output)
+```
+
+Notes:
+
+-   `from_address(...)` creates and owns the Dapr client for you. If your app already manages one, construct `DaprSession(...)` directly with `dapr_client=...`.
+-   Pass `ttl=...` to let the backing state store expire old session data automatically when the store supports TTL.
+-   Pass `consistency=DAPR_CONSISTENCY_STRONG` when you need stronger read-after-write guarantees.
+-   The Dapr Python SDK also checks the HTTP sidecar endpoint. In local development, start Dapr with `--dapr-http-port 3500` as well as the gRPC port used in `dapr_address`.
+-   See [`examples/memory/dapr_session_example.py`](https://github.com/openai/openai-agents-python/tree/main/examples/memory/dapr_session_example.py) for a full setup walkthrough, including local components and troubleshooting.
 
 
 ### Advanced SQLite sessions

mkdocs.yml

@@ -124,6 +124,7 @@ plugins:
                     - ref/models/multi_provider.md
                     - ref/mcp/server.md
                     - ref/mcp/util.md
+                    - ref/mcp/manager.md
                 - Tracing:
                     - ref/tracing/index.md
                     - ref/tracing/create.md
@@ -166,6 +167,15 @@ plugins:
                     - ref/extensions/memory/dapr_session.md
                     - ref/extensions/memory/encrypt_session.md
                     - ref/extensions/memory/advanced_sqlite_session.md
+                    - Experimental Codex:
+                        - ref/extensions/experimental/codex/codex_tool.md
+                        - ref/extensions/experimental/codex/codex.md
+                        - ref/extensions/experimental/codex/codex_options.md
+                        - ref/extensions/experimental/codex/thread.md
+                        - ref/extensions/experimental/codex/thread_options.md
+                        - ref/extensions/experimental/codex/turn_options.md
+                        - ref/extensions/experimental/codex/events.md
+                        - ref/extensions/experimental/codex/items.md
         - locale: ja
           name: 日本語
           build: true