docs: update details; change the default model for translation

Author: seratch

docs/human_in_the_loop.md

@@ -123,7 +123,21 @@ To stream output while waiting for approvals, call `Runner.run_streamed`, consum
 
 ## 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.
+`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(...)`.
+
+Useful serialization options:
+
+-   `context_serializer`: Customize how non-mapping context objects are serialized.
+-   `strict_context=True`: Fail serialization or deserialization unless the context is already a
+    mapping or you provide the appropriate serializer/deserializer.
+-   `context_override`: Replace the serialized context when loading state. This is useful when you
+    do not want to restore the original context object, but it does not remove that context from an
+    already serialized payload.
+-   `include_tracing_api_key=True`: Include the tracing API key in the serialized trace payload
+    when you need resumed work to keep exporting traces with the same credentials.
+
+`RunState` also preserves trace metadata and server-managed conversation settings, so a resumed run
+can continue the same trace and the same `conversation_id` / `previous_response_id` chain.
 
 ## Versioning pending tasks
 

docs/results.md

@@ -55,7 +55,11 @@ The [`input`][agents.result.RunResultBase.input] property contains the original
 
 ### 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(...)`.
+If a run pauses for tool approval, pending approvals are exposed in
+[`RunResult.interruptions`][agents.result.RunResult.interruptions] or
+[`RunResultStreaming.interruptions`][agents.result.RunResultStreaming.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
@@ -70,7 +74,9 @@ if result.interruptions:
     result = await Runner.run(agent, state)
 ```
 
-Both [`RunResult`][agents.result.RunResult] and [`RunResultStreaming`][agents.result.RunResultStreaming] support `to_state()`.
+Both [`RunResult`][agents.result.RunResult] and
+[`RunResultStreaming`][agents.result.RunResultStreaming] support `to_state()`. For durable
+approval workflows, see the [human-in-the-loop guide](human_in_the_loop.md).
 
 ### Convenience helpers
 

docs/running_agents.md

@@ -25,7 +25,11 @@ Read more in the [results guide](results.md).
 
 ### The agent loop
 
-When you use the run method in `Runner`, you pass in a starting agent and input. The input can either be a string (which is considered a user message), or a list of input items, which are the items in the OpenAI Responses API.
+When you use the run method in `Runner`, you pass in a starting agent and input. The input can be:
+
+-   a string (treated as a user message),
+-   a list of input items in the OpenAI Responses API format, or
+-   a [`RunState`][agents.run_state.RunState] when resuming an interrupted run.
 
 The runner then runs a loop:
 
@@ -123,7 +127,7 @@ Use `RunConfig` to override behavior for a single run without changing each agen
 -   [`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.
--   [`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.
+-   [`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. The callback can be sync or async.
 
 ##### Guardrails, handoffs, and model input shaping
 
@@ -345,6 +349,10 @@ async def main():
         print(f"Assistant: {result.final_output}")
 ```
 
+If a run pauses for approval and you resume from a [`RunState`][agents.run_state.RunState], the
+SDK keeps the saved `conversation_id` / `previous_response_id` / `auto_previous_response_id`
+settings so the resumed turn continues in the same server-managed conversation.
+
 !!! note
 
     The SDK automatically retries `conversation_locked` errors with backoff. In server-managed
@@ -378,7 +386,7 @@ 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.
+Set the hook per run via `run_config` to redact sensitive data, trim long histories, or inject additional system guidance.
 
 ## Errors and recovery
 

docs/scripts/translate_docs.py

@@ -11,7 +11,7 @@
 # logging.basicConfig(level=logging.INFO)
 # logging.getLogger("openai").setLevel(logging.DEBUG)
 
-OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.2")
+OPENAI_MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.3-codex")
 
 ENABLE_CODE_SNIPPET_EXCLUSION = True
 # gpt-4.5 needed this for better quality

docs/streaming.md

@@ -35,6 +35,22 @@ if __name__ == "__main__":
 
 [`RunItemStreamEvent`][agents.stream_events.RunItemStreamEvent]s are higher level events. They inform you when an item has been fully generated. This allows you to push progress updates at the level of "message generated", "tool ran", etc, instead of each token. Similarly, [`AgentUpdatedStreamEvent`][agents.stream_events.AgentUpdatedStreamEvent] gives you updates when the current agent changes (e.g. as the result of a handoff).
 
+### Run item event names
+
+`RunItemStreamEvent.name` uses a fixed set of semantic event names:
+
+-   `message_output_created`
+-   `handoff_requested`
+-   `handoff_occured`
+-   `tool_called`
+-   `tool_output`
+-   `reasoning_item_created`
+-   `mcp_approval_requested`
+-   `mcp_approval_response`
+-   `mcp_list_tools`
+
+`handoff_occured` is intentionally misspelled for backward compatibility.
+
 For example, this will ignore raw events and stream updates to the user.
 
 ```python