docs: v0.8.0 changes (#2405)

docs/examples.md

@@ -77,13 +77,14 @@ Check out a variety of sample implementations of the SDK in the examples section
     Simple deep research clone that demonstrates complex multi-agent research workflows.
 
 -   **[tools](https://github.com/openai/openai-agents-python/tree/main/examples/tools):**
-    Learn how to implement OAI hosted tools such as:
+    Learn how to implement OAI hosted tools and experimental Codex tooling such as:
 
     -   Web search and web search with filters
     -   File search
     -   Code interpreter
     -   Computer use
     -   Image generation
+    -   Experimental Codex tool workflows (`examples/tools/codex.py`)
 
 -   **[voice](https://github.com/openai/openai-agents-python/tree/main/examples/voice):**
     See examples of voice agents, using our TTS and STT models, including streamed voice examples.

docs/human_in_the_loop.md

@@ -0,0 +1,130 @@
+# Human-in-the-loop
+
+Use the human-in-the-loop (HITL) flow to pause agent execution until a person approves or rejects sensitive tool calls. Tools declare when they need approval, run results surface pending approvals as interruptions, and `RunState` lets you serialize and resume runs after decisions are made.
+
+## Marking tools that need approval
+
+Set `needs_approval` to `True` to always require approval or provide an async function that decides per call. The callable receives the run context, parsed tool parameters, and the tool call ID.
+
+```python
+from agents import Agent, Runner, function_tool
+
+
+@function_tool(needs_approval=True)
+async def cancel_order(order_id: int) -> str:
+    return f"Cancelled order {order_id}"
+
+
+async def requires_review(_ctx, params, _call_id) -> bool:
+    return "refund" in params.get("subject", "").lower()
+
+
+@function_tool(needs_approval=requires_review)
+async def send_email(subject: str, body: str) -> str:
+    return f"Sent '{subject}'"
+
+
+agent = Agent(
+    name="Support agent",
+    instructions="Handle tickets and ask for approval when needed.",
+    tools=[cancel_order, send_email],
+)
+```
+
+`needs_approval` is available on [`function_tool`][agents.tool.function_tool], [`Agent.as_tool`][agents.agent.Agent.as_tool], [`ShellTool`][agents.tool.ShellTool], and [`ApplyPatchTool`][agents.tool.ApplyPatchTool]. Local MCP servers also support approvals through `require_approval` on [`MCPServerStdio`][agents.mcp.server.MCPServerStdio], [`MCPServerSse`][agents.mcp.server.MCPServerSse], and [`MCPServerStreamableHttp`][agents.mcp.server.MCPServerStreamableHttp]. Hosted MCP servers support approvals via [`HostedMCPTool`][agents.tool.HostedMCPTool] with `tool_config={"require_approval": "always"}` and an optional `on_approval_request` callback. Shell and apply_patch tools accept an `on_approval` callback if you want to auto-approve or auto-reject without surfacing an interruption.
+
+## How the approval flow works
+
+1. When the model emits a tool call, the runner evaluates `needs_approval`.
+2. If an approval decision for that tool call is already stored in the [`RunContextWrapper`][agents.run_context.RunContextWrapper] (for example, from `always_approve=True`), the runner proceeds without prompting. Per-call approvals are scoped to the specific call ID; use `always_approve=True` to allow future calls automatically.
+3. Otherwise, execution pauses and `RunResult.interruptions` (or `RunResultStreaming.interruptions`) contains `ToolApprovalItem` entries with details such as `agent.name`, `name`, and `arguments`.
+4. Convert the result to a `RunState` with `result.to_state()`, call `state.approve(...)` or `state.reject(...)` (optionally passing `always_approve` or `always_reject`), and then resume with `Runner.run(agent, state)` or `Runner.run_streamed(agent, state)`.
+5. The resumed run continues where it left off and will re-enter this flow if new approvals are needed.
+
+## Example: pause, approve, resume
+
+The snippet below mirrors the JavaScript HITL guide: it pauses when a tool needs approval, persists state to disk, reloads it, and resumes after collecting a decision.
+
+```python
+import asyncio
+import json
+from pathlib import Path
+
+from agents import Agent, Runner, RunState, function_tool
+
+
+async def needs_oakland_approval(_ctx, params, _call_id) -> bool:
+    return "Oakland" in params.get("city", "")
+
+
+@function_tool(needs_approval=needs_oakland_approval)
+async def get_temperature(city: str) -> str:
+    return f"The temperature in {city} is 20° Celsius"
+
+
+agent = Agent(
+    name="Weather assistant",
+    instructions="Answer weather questions with the provided tools.",
+    tools=[get_temperature],
+)
+
+STATE_PATH = Path(".cache/hitl_state.json")
+
+
+def prompt_approval(tool_name: str, arguments: str | None) -> bool:
+    answer = input(f"Approve {tool_name} with {arguments}? [y/N]: ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+async def main() -> None:
+    result = await Runner.run(agent, "What is the temperature in Oakland?")
+
+    while result.interruptions:
+        # Persist the paused state.
+        state = result.to_state()
+        STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        STATE_PATH.write_text(state.to_string())
+
+        # Load the state later (could be a different process).
+        stored = json.loads(STATE_PATH.read_text())
+        state = await RunState.from_json(agent, stored)
+
+        for interruption in result.interruptions:
+            approved = await asyncio.get_running_loop().run_in_executor(
+                None, prompt_approval, interruption.name or "unknown_tool", interruption.arguments
+            )
+            if approved:
+                state.approve(interruption, always_approve=False)
+            else:
+                state.reject(interruption)
+
+        result = await Runner.run(agent, state)
+
+    print(result.final_output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+In this example, `prompt_approval` is synchronous because it uses `input()` and is executed with `run_in_executor(...)`. If your approval source is already asynchronous (for example, an HTTP request or async database query), you can use an `async def` function and `await` it directly instead.
+
+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
+
+- **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.
+- **Shell and apply_patch tools**: `ShellTool` and `ApplyPatchTool` also support `needs_approval`. Use `state.approve(interruption, always_approve=True)` or `state.reject(..., always_reject=True)` to cache the decision for future calls. For automatic decisions, provide `on_approval` (see `examples/tools/shell.py`); for manual decisions, handle interruptions (see `examples/tools/shell_human_in_the_loop.py`).
+- **Local MCP servers**: Use `require_approval` on `MCPServerStdio` / `MCPServerSse` / `MCPServerStreamableHttp` to gate MCP tool calls (see `examples/mcp/get_all_mcp_tools_example/main.py` and `examples/mcp/tool_filter_example/main.py`).
+- **Hosted MCP servers**: Set `require_approval` to `"always"` on `HostedMCPTool` to force HITL, optionally providing `on_approval_request` to auto-approve or reject (see `examples/hosted_mcp/human_in_the_loop.py` and `examples/hosted_mcp/on_approval.py`). Use `"never"` for trusted servers (`examples/hosted_mcp/simple.py`).
+- **Sessions and memory**: Pass a session to `Runner.run` so approvals and conversation history survive multiple turns. SQLite and OpenAI Conversations session variants are in `examples/memory/memory_session_hitl_example.py` and `examples/memory/openai_session_hitl_example.py`.
+- **Realtime agents**: The realtime demo exposes WebSocket messages that approve or reject tool calls via `approve_tool_call` / `reject_tool_call` on the `RealtimeSession` (see `examples/realtime/app/server.py` for the server-side handlers).
+
+## Long-running approvals
+
+`RunState` is designed to be durable. Use `state.to_json()` or `state.to_string()` to store pending work in a database or queue and recreate it later with `RunState.from_json(...)` or `RunState.from_string(...)`. Pass `context_override` if you do not want to persist sensitive context data in the serialized payload.
+
+## Versioning pending tasks
+
+If approvals may sit for a while, store a version marker for your agent definitions or SDK alongside the serialized state. You can then route deserialization to the matching code path to avoid incompatibilities when models, prompts, or tool definitions change.

docs/mcp.md

@@ -24,6 +24,33 @@ matrix below summarises the options that the Python SDK supports.
 
 The sections below walk through each option, how to configure it, and when to prefer one transport over another.
 
+## Agent-level MCP configuration
+
+In addition to choosing a transport, you can tune how MCP tools are prepared by setting `Agent.mcp_config`.
+
+```python
+from agents import Agent
+
+agent = Agent(
+    name="Assistant",
+    mcp_servers=[server],
+    mcp_config={
+        # Try to convert MCP tool schemas to strict JSON schema.
+        "convert_schemas_to_strict": True,
+        # If None, MCP tool failures are raised as exceptions instead of
+        # returning model-visible error text.
+        "failure_error_function": None,
+    },
+)
+```
+
+Notes:
+
+- `convert_schemas_to_strict` is best-effort. If a schema cannot be converted, the original schema is used.
+- `failure_error_function` controls how MCP tool call failures are surfaced to the model.
+- 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.
+
 ## 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
@@ -178,6 +205,61 @@ The constructor accepts additional options:
 - `use_structured_content` toggles whether `tool_result.structured_content` is preferred over textual output.
 - `max_retry_attempts` and `retry_backoff_seconds_base` add automatic retries for `list_tools()` and `call_tool()`.
 - `tool_filter` lets you expose only a subset of tools (see [Tool filtering](#tool-filtering)).
+- `require_approval` enables human-in-the-loop approval policies on local MCP tools.
+- `failure_error_function` customizes model-visible MCP tool failure messages; set it to `None` to raise errors instead.
+- `tool_meta_resolver` injects per-call MCP `_meta` payloads before `call_tool()`.
+
+### Approval policies for local MCP servers
+
+`MCPServerStdio`, `MCPServerSse`, and `MCPServerStreamableHttp` all accept `require_approval`.
+
+Supported forms:
+
+- `"always"` or `"never"` for all tools.
+- `True` / `False` (equivalent to always/never).
+- A per-tool map, for example `{"delete_file": "always", "read_file": "never"}`.
+- A grouped object:
+  `{"always": {"tool_names": [...]}, "never": {"tool_names": [...]}}`.
+
+```python
+async with MCPServerStreamableHttp(
+    name="Filesystem MCP",
+    params={"url": "http://localhost:8000/mcp"},
+    require_approval={"always": {"tool_names": ["delete_file"]}},
+) as server:
+    ...
+```
+
+For a full pause/resume flow, see [Human-in-the-loop](human_in_the_loop.md) and `examples/mcp/get_all_mcp_tools_example/main.py`.
+
+### Per-call metadata with `tool_meta_resolver`
+
+Use `tool_meta_resolver` when your MCP server expects request metadata in `_meta` (for example, tenant IDs or trace context). The example below assumes you pass a `dict` as `context` to `Runner.run(...)`.
+
+```python
+from agents.mcp import MCPServerStreamableHttp, MCPToolMetaContext
+
+
+def resolve_meta(context: MCPToolMetaContext) -> dict[str, str] | None:
+    run_context_data = context.run_context.context or {}
+    tenant_id = run_context_data.get("tenant_id")
+    if tenant_id is None:
+        return None
+    return {"tenant_id": str(tenant_id), "source": "agents-sdk"}
+
+
+server = MCPServerStreamableHttp(
+    name="Metadata-aware MCP",
+    params={"url": "http://localhost:8000/mcp"},
+    tool_meta_resolver=resolve_meta,
+)
+```
+
+If your run context is a Pydantic model, dataclass, or custom class, read the tenant ID with attribute access instead.
+
+### MCP tool outputs: text and images
+
+When an MCP tool returns image content, the SDK maps it to image tool output entries automatically. Mixed text/image responses are forwarded as a list of output items, so agents can consume MCP image results the same way they consume image output from regular function tools.
 
 ## 3. HTTP with SSE MCP servers
 

docs/ref/agent_tool_input.md

@@ -0,0 +1,3 @@
+# `Agent Tool Input`
+
+::: agents.agent_tool_input

docs/ref/agent_tool_state.md

@@ -0,0 +1,3 @@
+# `Agent Tool State`
+
+::: agents.agent_tool_state

docs/ref/memory/session_settings.md

@@ -0,0 +1,3 @@
+# `Session Settings`
+
+::: agents.memory.session_settings

docs/ref/run_config.md

@@ -0,0 +1,3 @@
+# `Run Config`
+
+::: agents.run_config

docs/ref/run_error_handlers.md

@@ -0,0 +1,3 @@
+# `Run Error Handlers`
+
+::: agents.run_error_handlers

docs/ref/run_internal/agent_runner_helpers.md

@@ -0,0 +1,3 @@
+# `Agent Runner Helpers`
+
+::: agents.run_internal.agent_runner_helpers

docs/ref/run_internal/approvals.md

@@ -0,0 +1,3 @@
+# `Approvals`
+
+::: agents.run_internal.approvals

docs/ref/run_internal/error_handlers.md

@@ -0,0 +1,3 @@
+# `Error Handlers`
+
+::: agents.run_internal.error_handlers

docs/ref/run_internal/guardrails.md

@@ -0,0 +1,3 @@
+# `Guardrails`
+
+::: agents.run_internal.guardrails

docs/ref/run_internal/items.md

@@ -0,0 +1,3 @@
+# `Items`
+
+::: agents.run_internal.items

docs/ref/run_internal/oai_conversation.md

@@ -0,0 +1,3 @@
+# `Oai Conversation`
+
+::: agents.run_internal.oai_conversation

docs/ref/run_internal/run_loop.md

@@ -0,0 +1,3 @@
+# `Run Loop`
+
+::: agents.run_internal.run_loop

docs/ref/run_internal/run_steps.md

@@ -0,0 +1,3 @@
+# `Run Steps`
+
+::: agents.run_internal.run_steps

docs/ref/run_internal/session_persistence.md

@@ -0,0 +1,3 @@
+# `Session Persistence`
+
+::: agents.run_internal.session_persistence

docs/ref/run_internal/streaming.md

@@ -0,0 +1,3 @@
+# `Streaming`
+
+::: agents.run_internal.streaming

docs/ref/run_internal/tool_actions.md

@@ -0,0 +1,3 @@
+# `Tool Actions`
+
+::: agents.run_internal.tool_actions

docs/ref/run_internal/tool_execution.md

@@ -0,0 +1,3 @@
+# `Tool Execution`
+
+::: agents.run_internal.tool_execution

docs/ref/run_internal/tool_planning.md

@@ -0,0 +1,3 @@
+# `Tool Planning`
+
+::: agents.run_internal.tool_planning

docs/ref/run_internal/tool_use_tracker.md

@@ -0,0 +1,3 @@
+# `Tool Use Tracker`
+
+::: agents.run_internal.tool_use_tracker

docs/ref/run_internal/turn_preparation.md

@@ -0,0 +1,3 @@
+# `Turn Preparation`
+
+::: agents.run_internal.turn_preparation

docs/ref/run_internal/turn_resolution.md

@@ -0,0 +1,3 @@
+# `Turn Resolution`
+
+::: agents.run_internal.turn_resolution

docs/ref/run_state.md

@@ -0,0 +1,3 @@
+# `Run State`
+
+::: agents.run_state

docs/ref/tracing/context.md

@@ -0,0 +1,3 @@
+# `Context`
+
+::: agents.tracing.context

docs/ref/tracing/model_tracing.md

@@ -0,0 +1,3 @@
+# `Model Tracing`
+
+::: agents.tracing.model_tracing

docs/release.md

@@ -19,6 +19,20 @@ We will increment `Z` for non-breaking changes:
 
 ## Breaking change changelog
 
+### 0.8.0
+
+In this version, two runtime behavior changes may require migration work:
+
+- Function tools wrapping **synchronous** Python callables now execute on worker threads via `asyncio.to_thread(...)` instead of running on the event loop thread. If your tool logic depends on thread-local state or thread-affine resources, migrate to an async tool implementation or make thread affinity explicit in your tool code.
+- Local MCP tool failure handling is now configurable, and the default behavior can return model-visible error output instead of failing the whole run. If you rely on fail-fast semantics, set `mcp_config={"failure_error_function": None}`. Server-level `failure_error_function` values override the agent-level setting, so set `failure_error_function=None` on each local MCP server that has an explicit handler.
+
+### 0.7.0
+
+In this version, there were a few behavior changes that can affect existing applications:
+
+- Nested handoff history is now **opt-in** (disabled by default). If you depended on the v0.6.x default nested behavior, explicitly set `RunConfig(nest_handoff_history=True)`.
+- The default `reasoning.effort` for `gpt-5.1` / `gpt-5.2` changed to `"none"` (from the previous default `"low"` configured by SDK defaults). If your prompts or quality/cost profile relied on `"low"`, set it explicitly in `model_settings`.
+
 ### 0.6.0
 
 In this version, the default handoff history is now packaged into a single assistant message instead of exposing the raw user/assistant turns, giving downstream agents a concise, predictable recap

docs/results.md

@@ -52,3 +52,30 @@ The [`raw_responses`][agents.result.RunResultBase.raw_responses] property contai
 ### Original input
 
 The [`input`][agents.result.RunResultBase.input] property contains the original input you provided to the `run` method. In most cases you won't need this, but it's available in case you do.
+
+### Interruptions and resuming runs
+
+If a run pauses for tool approval, pending approvals are exposed in [`interruptions`][agents.result.RunResultBase.interruptions]. Convert the result into a [`RunState`][agents.run_state.RunState] with `to_state()`, approve or reject the interruption(s), and resume with `Runner.run(...)` or `Runner.run_streamed(...)`.
+
+```python
+from agents import Agent, Runner
+
+agent = Agent(name="Assistant", instructions="Use tools when needed.")
+result = await Runner.run(agent, "Delete temp files that are no longer needed.")
+
+if result.interruptions:
+    state = result.to_state()
+    for interruption in result.interruptions:
+        state.approve(interruption)
+    result = await Runner.run(agent, state)
+```
+
+Both [`RunResult`][agents.result.RunResult] and [`RunResultStreaming`][agents.result.RunResultStreaming] support `to_state()`.
+
+### Convenience helpers
+
+`RunResultBase` includes a few helper methods/properties that are useful in production flows:
+
+- [`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, useful for response chaining.
+- [`release_agents(...)`][agents.result.RunResultBase.release_agents] drops strong references to agents when you want to reduce memory pressure after inspecting results.

docs/running_agents.md

@@ -49,9 +49,10 @@ The `run_config` parameter lets you configure some global settings for the agent
 -   [`model`][agents.run.RunConfig.model]: Allows setting a global LLM model to use, irrespective of what `model` each Agent has.
 -   [`model_provider`][agents.run.RunConfig.model_provider]: A model provider for looking up model names, which defaults to OpenAI.
 -   [`model_settings`][agents.run.RunConfig.model_settings]: Overrides agent-specific settings. For example, you can set a global `temperature` or `top_p`.
+-   [`session_settings`][agents.run.RunConfig.session_settings]: Overrides session-level defaults (for example, `SessionSettings(limit=...)`) when retrieving history during a run.
 -   [`input_guardrails`][agents.run.RunConfig.input_guardrails], [`output_guardrails`][agents.run.RunConfig.output_guardrails]: A list of input or output guardrails to include on all runs.
 -   [`handoff_input_filter`][agents.run.RunConfig.handoff_input_filter]: A global input filter to apply to all handoffs, if the handoff doesn't already have one. The input filter allows you to edit the inputs that are sent to the new agent. See the documentation in [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] for more details.
--   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: Opt-in beta that collapses the prior transcript into a single assistant message before invoking the next agent. This is disabled by default while we stabilize nested handoffs; set to `True` to enable or leave `False` to pass through the raw transcript. All [`Runner` methods](agents.run.Runner) automatically create a `RunConfig` when you do not pass one, so the quickstarts and examples keep the default off, and any explicit [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] callbacks continue to override it. Individual handoffs can override this setting via [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history].
+-   [`nest_handoff_history`][agents.run.RunConfig.nest_handoff_history]: Opt-in beta that collapses the prior transcript into a single assistant message before invoking the next agent. This is disabled by default while we stabilize nested handoffs; set to `True` to enable or leave `False` to pass through the raw transcript. All [Runner methods][agents.run.Runner] automatically create a `RunConfig` when you do not pass one, so the quickstarts and examples keep the default off, and any explicit [`Handoff.input_filter`][agents.handoffs.Handoff.input_filter] callbacks continue to override it. Individual handoffs can override this setting via [`Handoff.nest_handoff_history`][agents.handoffs.Handoff.nest_handoff_history].
 -   [`handoff_history_mapper`][agents.run.RunConfig.handoff_history_mapper]: Optional callable that receives the normalized transcript (history + handoff items) whenever you opt in to `nest_handoff_history`. It must return the exact list of input items to forward to the next agent, allowing you to replace the built-in summary without writing a full handoff filter.
 -   [`tracing_disabled`][agents.run.RunConfig.tracing_disabled]: Allows you to disable [tracing](tracing.md) for the entire run.
 -   [`tracing`][agents.run.RunConfig.tracing]: Pass a [`TracingConfig`][agents.tracing.TracingConfig] to override exporters, processors, or tracing metadata for this run.
@@ -60,6 +61,7 @@ The `run_config` parameter lets you configure some global settings for the agent
 -   [`trace_metadata`][agents.run.RunConfig.trace_metadata]: Metadata to include on all traces.
 -   [`session_input_callback`][agents.run.RunConfig.session_input_callback]: Customize how new user input is merged with session history before each turn when using Sessions.
 -   [`call_model_input_filter`][agents.run.RunConfig.call_model_input_filter]: Hook to edit the fully prepared model input (instructions and input items) immediately before the model call, e.g., to trim history or inject a system prompt.
+-   [`tool_error_formatter`][agents.run.RunConfig.tool_error_formatter]: Customize the model-visible message when a tool call is rejected during approval flows.
 
 Nested handoffs are available as an opt-in beta. Enable the collapsed-transcript behavior by passing `RunConfig(nest_handoff_history=True)` or set `handoff(..., nest_handoff_history=True)` to turn it on for a specific handoff. If you prefer to keep the raw transcript (the default), leave the flag unset or provide a `handoff_input_filter` (or `handoff_history_mapper`) that forwards the conversation exactly as you need. To change the wrapper text used in the generated summary without writing a custom mapper, call [`set_conversation_history_wrappers`][agents.handoffs.set_conversation_history_wrappers] (and [`reset_conversation_history_wrappers`][agents.handoffs.reset_conversation_history_wrappers] to restore the defaults).
 
@@ -208,8 +210,43 @@ result = Runner.run_sync(
 
 Set the hook per run via `run_config` or as a default on your `Runner` to redact sensitive data, trim long histories, or inject additional system guidance.
 
+## Error handlers
+
+All `Runner` entry points accept `error_handlers`, a dict keyed by error kind. Today, the supported key is `"max_turns"`. Use it when you want to return a controlled final output instead of raising `MaxTurnsExceeded`.
+
+```python
+from agents import (
+    Agent,
+    RunErrorHandlerInput,
+    RunErrorHandlerResult,
+    Runner,
+)
+
+agent = Agent(name="Assistant", instructions="Be concise.")
+
+
+def on_max_turns(_data: RunErrorHandlerInput[None]) -> RunErrorHandlerResult:
+    return RunErrorHandlerResult(
+        final_output="I couldn't finish within the turn limit. Please narrow the request.",
+        include_in_history=False,
+    )
+
+
+result = Runner.run_sync(
+    agent,
+    "Analyze this long transcript",
+    max_turns=3,
+    error_handlers={"max_turns": on_max_turns},
+)
+print(result.final_output)
+```
+
+Set `include_in_history=False` when you do not want the fallback output appended to conversation history.
+
 ## Long running agents & human-in-the-loop
 
+For tool approval pause/resume patterns, see the dedicated [Human-in-the-loop guide](human_in_the_loop.md).
+
 ### Temporal
 
 You can use the Agents SDK [Temporal](https://temporal.io/) integration to run durable, long-running workflows, including human-in-the-loop tasks. View a demo of Temporal and the Agents SDK working in action to complete long-running tasks [in this video](https://www.youtube.com/watch?v=fFBZqzT4DD8), and [view docs here](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/openai_agents). 

docs/tools.md

@@ -321,7 +321,7 @@ async def main():
 
 ### Customizing tool-agents
 
-The `agent.as_tool` function is a convenience method to make it easy to turn an agent into a tool. It doesn't support all configuration though; for example, you can't set `max_turns`. For advanced use cases, use `Runner.run` directly in your tool implementation:
+The `agent.as_tool` function is a convenience method to make it easy to turn an agent into a tool. It supports common runtime options such as `max_turns`, `run_config`, `hooks`, `previous_response_id`, `conversation_id`, `session`, and `needs_approval`. It also supports structured input with `parameters`, `input_builder`, and `include_input_schema`. For advanced orchestration (for example, conditional retries, fallback behavior, or chaining multiple agent calls), use `Runner.run` directly in your tool implementation:
 
 ```python
 @function_tool
@@ -340,6 +340,40 @@ async def run_my_agent() -> str:
     return str(result.final_output)
 ```
 
+### Structured input for tool-agents
+
+By default, `Agent.as_tool()` expects a single string input (`{"input": "..."}`), but you can expose a structured schema by passing `parameters` (a Pydantic model or dataclass type).
+
+Additional options:
+
+- `include_input_schema=True` includes the full JSON Schema in the generated nested input.
+- `input_builder=...` lets you fully customize how structured tool arguments become nested agent input.
+- `RunContextWrapper.tool_input` contains the parsed structured payload inside the nested run context.
+
+```python
+from pydantic import BaseModel, Field
+
+
+class TranslationInput(BaseModel):
+    text: str = Field(description="Text to translate.")
+    source: str = Field(description="Source language.")
+    target: str = Field(description="Target language.")
+
+
+translator_tool = translator_agent.as_tool(
+    tool_name="translate_text",
+    tool_description="Translate text between languages.",
+    parameters=TranslationInput,
+    include_input_schema=True,
+)
+```
+
+See `examples/agent_patterns/agents_as_tools_structured.py` for a complete runnable example.
+
+### Approval gates for tool-agents
+
+`Agent.as_tool(..., needs_approval=...)` uses the same approval flow as `function_tool`. If approval is required, the run pauses and pending items appear in `result.interruptions`; then use `result.to_state()` and resume after calling `state.approve(...)` or `state.reject(...)`. See the [Human-in-the-loop guide](human_in_the_loop.md) for the full pause/resume pattern.
+
 ### Custom output extraction
 
 In certain cases, you might want to modify the output of the tool-agents before returning it to the central agent. This may be useful if you want to:
@@ -377,7 +411,7 @@ from agents import AgentToolStreamEvent
 
 async def handle_stream(event: AgentToolStreamEvent) -> None:
     # Inspect the underlying StreamEvent along with agent metadata.
-    print(f"[stream] {event['agent']['name']} :: {event['event'].type}")
+    print(f"[stream] {event['agent'].name} :: {event['event'].type}")
 
 
 billing_agent_tool = billing_agent.as_tool(
@@ -392,7 +426,7 @@ What to expect:
 - Event types mirror `StreamEvent["type"]`: `raw_response_event`, `run_item_stream_event`, `agent_updated_stream_event`.
 - Providing `on_stream` automatically runs the nested agent in streaming mode and drains the stream before returning the final output.
 - The handler may be synchronous or asynchronous; each event is delivered in order as it arrives.
-- `tool_call_id` is present when the tool is invoked via a model tool call; direct calls may leave it `None`.
+- `tool_call` is present when the tool is invoked via a model tool call; direct calls may leave it `None`.
 - See `examples/agent_patterns/agents_as_tools_streaming.py` for a complete runnable sample.
 
 ### Conditional tool enabling
@@ -472,7 +506,7 @@ during a tool call. This surface is experimental and may change.
 
 ```python
 from agents import Agent
-from agents.extensions.experimental.codex import ThreadOptions, codex_tool
+from agents.extensions.experimental.codex import ThreadOptions, TurnOptions, codex_tool
 
 agent = Agent(
     name="Codex Agent",
@@ -483,8 +517,13 @@ agent = Agent(
             working_directory="/path/to/repo",
             default_thread_options=ThreadOptions(
                 model="gpt-5.2-codex",
+                model_reasoning_effort="low",
                 network_access_enabled=True,
-                web_search_enabled=False,
+                web_search_mode="disabled",
+                approval_policy="never",
+            ),
+            default_turn_options=TurnOptions(
+                idle_timeout_seconds=60,
             ),
             persist_session=True,
         )
@@ -495,9 +534,13 @@ agent = Agent(
 What to know:
 
 -   Auth: set `CODEX_API_KEY` (preferred) or `OPENAI_API_KEY`, or pass `codex_options={"api_key": "..."}`.
--   Runtime: `codex_options.base_url` overrides the CLI base URL, and `codex_options.codex_path_override` (or `CODEX_PATH`) selects the binary.
+-   Runtime: `codex_options.base_url` overrides the CLI base URL.
+-   Binary resolution: set `codex_options.codex_path_override` (or `CODEX_PATH`) to pin the CLI path. Otherwise the SDK resolves `codex` from `PATH`, then falls back to the bundled vendor binary.
 -   Environment: `codex_options.env` fully controls the subprocess environment. When it is provided, the subprocess does not inherit `os.environ`.
+-   Stream limits: `codex_options.codex_subprocess_stream_limit_bytes` (or `OPENAI_AGENTS_CODEX_SUBPROCESS_STREAM_LIMIT_BYTES`) controls stdout/stderr reader limits. Valid range is `65536` to `67108864`; default is `8388608`.
 -   Inputs: tool calls must include at least one item in `inputs` with `{ "type": "text", "text": ... }` or `{ "type": "local_image", "path": ... }`.
+-   Thread defaults: configure `default_thread_options` for `model_reasoning_effort`, `web_search_mode` (preferred over legacy `web_search_enabled`), `approval_policy`, and `additional_directories`.
+-   Turn defaults: configure `default_turn_options` for `idle_timeout_seconds` and cancellation `signal`.
 -   Safety: pair `sandbox_mode` with `working_directory`; set `skip_git_repo_check=True` outside Git repos.
 -   Behavior: `persist_session=True` reuses a single Codex thread and returns its `thread_id`.
 -   Streaming: `on_stream` receives Codex events (reasoning, command execution, MCP tool calls, file changes, web search).

mkdocs.yml

@@ -64,6 +64,7 @@ plugins:
                     - sessions/encrypted_session.md
                 - results.md
                 - streaming.md
+                - human_in_the_loop.md
                 - repl.md
                 - tools.md
                 - mcp.md