fix: persist reasoning item ID policy across resumes and streamed follow-up turns (#2512)

Author: seratch

src/agents/__init__.py

@@ -86,7 +86,13 @@
 from .prompts import DynamicPromptFunction, GenerateDynamicPromptData, Prompt
 from .repl import run_demo_loop
 from .result import RunResult, RunResultStreaming
-from .run import RunConfig, Runner, ToolErrorFormatter, ToolErrorFormatterArgs
+from .run import (
+    ReasoningItemIdPolicy,
+    RunConfig,
+    Runner,
+    ToolErrorFormatter,
+    ToolErrorFormatterArgs,
+)
 from .run_context import AgentHookContext, RunContextWrapper, TContext
 from .run_error_handlers import (
     RunErrorData,
@@ -345,6 +351,7 @@ def enable_verbose_stdout_logging():
     "RunResult",
     "RunResultStreaming",
     "RunConfig",
+    "ReasoningItemIdPolicy",
     "ToolErrorFormatter",
     "ToolErrorFormatterArgs",
     "RunState",

src/agents/result.py

@@ -29,6 +29,7 @@
 )
 from .logger import logger
 from .run_context import RunContextWrapper
+from .run_internal.items import run_item_to_input_item
 from .run_internal.run_steps import (
     NextStepInterruption,
     ProcessedResponse,
@@ -78,6 +79,7 @@ def _populate_state_from_result(
     state._conversation_id = conversation_id
     state._previous_response_id = previous_response_id
     state._auto_previous_response_id = auto_previous_response_id
+    state._reasoning_item_id_policy = getattr(result, "_reasoning_item_id_policy", None)
 
     interruptions = list(getattr(result, "interruptions", []))
     if interruptions:
@@ -193,10 +195,12 @@ def to_input_list(self) -> list[TResponseInputItem]:
         """Creates a new input list, merging the original input with all the new items generated."""
         original_items: list[TResponseInputItem] = ItemHelpers.input_to_new_input_list(self.input)
         new_items: list[TResponseInputItem] = []
+        reasoning_item_id_policy = getattr(self, "_reasoning_item_id_policy", None)
         for item in self.new_items:
-            if isinstance(item, ToolApprovalItem):
+            converted = run_item_to_input_item(item, reasoning_item_id_policy)
+            if converted is None:
                 continue
-            new_items.append(item.to_input_item())
+            new_items.append(converted)
 
         return original_items + new_items
 
@@ -237,6 +241,10 @@ class RunResult(RunResultBase):
     """Response identifier returned by the server for the last turn."""
     _auto_previous_response_id: bool = field(default=False, repr=False)
     """Whether automatic previous response tracking was enabled."""
+    _reasoning_item_id_policy: Literal["preserve", "omit"] | None = field(
+        default=None, init=False, repr=False
+    )
+    """How reasoning IDs should be represented when converting to input history."""
     max_turns: int = 10
     """The maximum number of turns allowed for this run."""
     interruptions: list[ToolApprovalItem] = field(default_factory=list)
@@ -399,6 +407,10 @@ class RunResultStreaming(RunResultBase):
     """Response identifier returned by the server for the last turn."""
     _auto_previous_response_id: bool = field(default=False, repr=False)
     """Whether automatic previous response tracking was enabled."""
+    _reasoning_item_id_policy: Literal["preserve", "omit"] | None = field(
+        default=None, init=False, repr=False
+    )
+    """How reasoning IDs should be represented when converting to input history."""
     _run_impl_task: InitVar[asyncio.Task[Any] | None] = None
 
     def __post_init__(self, _run_impl_task: asyncio.Task[Any] | None) -> None:

src/agents/run.py

@@ -34,6 +34,7 @@
     CallModelData,
     CallModelInputFilter,
     ModelInputData,
+    ReasoningItemIdPolicy,
     RunConfig,
     RunOptions,
     ToolErrorFormatter,
@@ -124,6 +125,7 @@
     "ModelInputData",
     "CallModelData",
     "CallModelInputFilter",
+    "ReasoningItemIdPolicy",
     "ToolErrorFormatter",
     "ToolErrorFormatterArgs",
     "DEFAULT_MAX_TURNS",
@@ -490,6 +492,14 @@ async def run(
                 )
                 original_input_for_state = prepared_input
 
+        resolved_reasoning_item_id_policy: ReasoningItemIdPolicy | None = (
+            run_config.reasoning_item_id_policy
+            if run_config.reasoning_item_id_policy is not None
+            else (run_state._reasoning_item_id_policy if run_state is not None else None)
+        )
+        if run_state is not None:
+            run_state._reasoning_item_id_policy = resolved_reasoning_item_id_policy
+
         # Check whether to enable OpenAI server-managed conversation
         if (
             conversation_id is not None
@@ -500,6 +510,7 @@ async def run(
                 conversation_id=conversation_id,
                 previous_response_id=previous_response_id,
                 auto_previous_response_id=auto_previous_response_id,
+                reasoning_item_id_policy=resolved_reasoning_item_id_policy,
             )
         else:
             server_conversation_tracker = None
@@ -566,8 +577,15 @@ async def run(
                     previous_response_id=previous_response_id,
                     auto_previous_response_id=auto_previous_response_id,
                 )
+                run_state._reasoning_item_id_policy = resolved_reasoning_item_id_policy
                 run_state.set_trace(get_current_trace())
 
+            def _with_reasoning_item_id_policy(result: RunResult) -> RunResult:
+                result._reasoning_item_id_policy = resolved_reasoning_item_id_policy
+                if run_state is not None:
+                    run_state._reasoning_item_id_policy = resolved_reasoning_item_id_policy
+                return result
+
             pending_server_items: list[RunItem] | None = None
             input_guardrail_results: list[InputGuardrailResult] = (
                 list(run_state._input_guardrail_results) if run_state is not None else []
@@ -675,6 +693,9 @@ async def run(
                                             run_state._current_turn_persisted_item_count
                                         ),
                                         response_id=turn_result.model_response.response_id,
+                                        reasoning_item_id_policy=(
+                                            run_state._reasoning_item_id_policy
+                                        ),
                                         store=store_setting,
                                     )
                                 )
@@ -727,7 +748,7 @@ async def run(
                                     original_input=original_input,
                                 )
                                 return finalize_conversation_tracking(
-                                    result,
+                                    _with_reasoning_item_id_policy(result),
                                     server_conversation_tracker=server_conversation_tracker,
                                     run_state=run_state,
                                 )
@@ -792,7 +813,7 @@ async def run(
                                     )
                                 result._original_input = copy_input_items(original_input)
                                 return finalize_conversation_tracking(
-                                    result,
+                                    _with_reasoning_item_id_policy(result),
                                     server_conversation_tracker=server_conversation_tracker,
                                     run_state=run_state,
                                 )
@@ -852,6 +873,7 @@ async def run(
                             new_items=session_items,
                             raw_responses=model_responses,
                             last_agent=current_agent,
+                            reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                         )
                         handler_result = await resolve_run_error_handler_result(
                             error_handlers=error_handlers,
@@ -921,7 +943,7 @@ async def run(
                             )
                         result._original_input = copy_input_items(original_input)
                         return finalize_conversation_tracking(
-                            result,
+                            _with_reasoning_item_id_policy(result),
                             server_conversation_tracker=server_conversation_tracker,
                             run_state=run_state,
                         )
@@ -995,6 +1017,7 @@ async def run(
                                     if not is_resumed_state and session_persistence_enabled
                                     else None
                                 ),
+                                reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                             )
                         )
 
@@ -1048,6 +1071,7 @@ async def run(
                                 if not is_resumed_state and session_persistence_enabled
                                 else None
                             ),
+                            reasoning_item_id_policy=resolved_reasoning_item_id_policy,
                         )
 
                     # Start hooks should only run on the first turn unless reset by a handoff.
@@ -1116,6 +1140,9 @@ async def run(
                                         items_to_save_turn,
                                         None,
                                         response_id=turn_result.model_response.response_id,
+                                        reasoning_item_id_policy=(
+                                            run_state._reasoning_item_id_policy
+                                        ),
                                         store=store_setting,
                                     )
                                     run_state._current_turn_persisted_item_count += saved_count
@@ -1181,7 +1208,7 @@ async def run(
                             )
                             result._original_input = copy_input_items(original_input)
                             return finalize_conversation_tracking(
-                                result,
+                                _with_reasoning_item_id_policy(result),
                                 server_conversation_tracker=server_conversation_tracker,
                                 run_state=run_state,
                             )
@@ -1242,7 +1269,7 @@ async def run(
                                 original_input=original_input,
                             )
                             return finalize_conversation_tracking(
-                                result,
+                                _with_reasoning_item_id_policy(result),
                                 server_conversation_tracker=server_conversation_tracker,
                                 run_state=run_state,
                             )
@@ -1473,6 +1500,14 @@ def run_streamed(
                 auto_previous_response_id=auto_previous_response_id,
             )
 
+        resolved_reasoning_item_id_policy: ReasoningItemIdPolicy | None = (
+            run_config.reasoning_item_id_policy
+            if run_config.reasoning_item_id_policy is not None
+            else (run_state._reasoning_item_id_policy if run_state is not None else None)
+        )
+        if run_state is not None:
+            run_state._reasoning_item_id_policy = resolved_reasoning_item_id_policy
+
         (
             trace_workflow_name,
             trace_id,
@@ -1551,6 +1586,7 @@ def run_streamed(
         streamed_result._model_input_items = (
             list(run_state._generated_items) if run_state is not None else []
         )
+        streamed_result._reasoning_item_id_policy = resolved_reasoning_item_id_policy
         if run_state is not None:
             streamed_result._trace_state = run_state._trace_state
         # Store run_state in streamed_result._state so it's accessible throughout streaming

src/agents/run_config.py

@@ -51,6 +51,7 @@ class CallModelData(Generic[TContext]):
 
 
 CallModelInputFilter = Callable[[CallModelData[Any]], MaybeAwaitable[ModelInputData]]
+ReasoningItemIdPolicy = Literal["preserve", "omit"]
 
 
 @dataclass
@@ -183,6 +184,13 @@ class RunConfig:
     settings. Used to control session behavior like the number of items to retrieve.
     """
 
+    reasoning_item_id_policy: ReasoningItemIdPolicy | None = None
+    """Controls how reasoning items are converted to next-turn model input.
+
+    - ``None`` / ``"preserve"`` keeps reasoning item IDs as-is.
+    - ``"omit"`` strips reasoning item IDs from model input built by the runner.
+    """
+
 
 class RunOptions(TypedDict, Generic[TContext]):
     """Arguments for ``AgentRunner`` methods."""
@@ -220,6 +228,7 @@ class RunOptions(TypedDict, Generic[TContext]):
     "CallModelData",
     "CallModelInputFilter",
     "ModelInputData",
+    "ReasoningItemIdPolicy",
     "RunConfig",
     "RunOptions",
     "ToolErrorFormatter",

src/agents/run_internal/approvals.py

@@ -13,6 +13,7 @@
 
 from ..agent import Agent
 from ..items import ItemHelpers, RunItem, ToolApprovalItem, ToolCallOutputItem, TResponseInputItem
+from .items import ReasoningItemIdPolicy, run_item_to_input_item
 
 # --------------------------
 # Public helpers
@@ -55,12 +56,14 @@ def approvals_from_step(step: Any) -> list[ToolApprovalItem]:
 def append_input_items_excluding_approvals(
     base_input: list[TResponseInputItem],
     items: Sequence[RunItem],
+    reasoning_item_id_policy: ReasoningItemIdPolicy | None = None,
 ) -> None:
     """Append tool outputs to model input while skipping approval placeholders."""
     for item in items:
-        if item.type == "tool_approval_item":
+        converted = run_item_to_input_item(item, reasoning_item_id_policy)
+        if converted is None:
             continue
-        base_input.append(item.to_input_item())
+        base_input.append(converted)
 
 
 # --------------------------

src/agents/run_internal/error_handlers.py

@@ -14,7 +14,6 @@
     MessageOutputItem,
     ModelResponse,
     RunItem,
-    ToolApprovalItem,
     TResponseInputItem,
 )
 from ..models.fake_id import FAKE_RESPONSES_ID
@@ -25,6 +24,7 @@
     RunErrorHandlerResult,
     RunErrorHandlers,
 )
+from .items import ReasoningItemIdPolicy, run_item_to_input_item
 from .turn_preparation import get_output_schema
 
 
@@ -34,13 +34,15 @@ def build_run_error_data(
     new_items: list[RunItem],
     raw_responses: list[ModelResponse],
     last_agent: Agent[Any],
+    reasoning_item_id_policy: ReasoningItemIdPolicy | None = None,
 ) -> RunErrorData:
     history = ItemHelpers.input_to_new_input_list(input)
     output = []
     for item in new_items:
-        if isinstance(item, ToolApprovalItem):
+        converted = run_item_to_input_item(item, reasoning_item_id_policy)
+        if converted is None:
             continue
-        output.append(item.to_input_item())
+        output.append(converted)
     history = history + list(output)
     return RunErrorData(
         input=input,