Fix #1564 Add conversations API support

Author: seratch

pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.9"
 license = "MIT"
 authors = [{ name = "OpenAI", email = "[email protected]" }]
 dependencies = [
-    "openai>=1.99.6,<2",
+    "openai>=1.101.0,<2",
     "pydantic>=2.10, <3",
     "griffe>=1.5.6, <2",
     "typing-extensions>=4.12.2, <5",

src/agents/extensions/models/litellm_model.py

@@ -82,7 +82,8 @@ async def get_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: Any | None = None,
     ) -> ModelResponse:
         with generation_span(
@@ -171,7 +172,8 @@ async def stream_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: Any | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         with generation_span(

src/agents/models/interface.py

@@ -48,6 +48,7 @@ async def get_response(
         tracing: ModelTracing,
         *,
         previous_response_id: str | None,
+        conversation_id: str | None,
         prompt: ResponsePromptParam | None,
     ) -> ModelResponse:
         """Get a response from the model.
@@ -62,6 +63,7 @@ async def get_response(
             tracing: Tracing configuration.
             previous_response_id: the ID of the previous response. Generally not used by the model,
                 except for the OpenAI Responses API.
+            conversation_id: The ID of the stored conversation, if any.
             prompt: The prompt config to use for the model.
 
         Returns:
@@ -81,6 +83,7 @@ def stream_response(
         tracing: ModelTracing,
         *,
         previous_response_id: str | None,
+        conversation_id: str | None,
         prompt: ResponsePromptParam | None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         """Stream a response from the model.
@@ -95,6 +98,7 @@ def stream_response(
             tracing: Tracing configuration.
             previous_response_id: the ID of the previous response. Generally not used by the model,
                 except for the OpenAI Responses API.
+            conversation_id: The ID of the stored conversation, if any.
             prompt: The prompt config to use for the model.
 
         Returns:

src/agents/models/openai_chatcompletions.py

@@ -55,7 +55,8 @@ async def get_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with generation_span(
@@ -142,7 +143,8 @@ async def stream_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         """

src/agents/models/openai_responses.py

@@ -75,7 +75,8 @@ async def get_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         prompt: ResponsePromptParam | None = None,
     ) -> ModelResponse:
         with response_span(disabled=tracing.is_disabled()) as span_response:
@@ -87,7 +88,8 @@ async def get_response(
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=False,
                     prompt=prompt,
                 )
@@ -150,7 +152,8 @@ async def stream_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         tracing: ModelTracing,
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,  # unused
+        conversation_id: str | None = None,  # unused
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncIterator[ResponseStreamEvent]:
         """
@@ -165,7 +168,8 @@ async def stream_response(
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=True,
                     prompt=prompt,
                 )
@@ -203,6 +207,7 @@ async def _fetch_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[True],
         prompt: ResponsePromptParam | None = None,
     ) -> AsyncStream[ResponseStreamEvent]: ...
@@ -217,6 +222,7 @@ async def _fetch_response(
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
         previous_response_id: str | None,
+        conversation_id: str | None,
         stream: Literal[False],
         prompt: ResponsePromptParam | None = None,
     ) -> Response: ...
@@ -229,7 +235,8 @@ async def _fetch_response(
         tools: list[Tool],
         output_schema: AgentOutputSchemaBase | None,
         handoffs: list[Handoff],
-        previous_response_id: str | None,
+        previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         stream: Literal[True] | Literal[False] = False,
         prompt: ResponsePromptParam | None = None,
     ) -> Response | AsyncStream[ResponseStreamEvent]:
@@ -265,6 +272,7 @@ async def _fetch_response(
                 f"Tool choice: {tool_choice}\n"
                 f"Response format: {response_format}\n"
                 f"Previous response id: {previous_response_id}\n"
+                f"Conversation id: {conversation_id}\n"
             )
 
         extra_args = dict(model_settings.extra_args or {})
@@ -278,6 +286,7 @@ async def _fetch_response(
 
         return await self._client.responses.create(
             previous_response_id=self._non_null_or_not_given(previous_response_id),
+            conversation=self._non_null_or_not_given(conversation_id),
             instructions=self._non_null_or_not_given(system_instructions),
             model=self.model,
             input=list_input,

src/agents/run.py

@@ -199,6 +199,9 @@ class RunOptions(TypedDict, Generic[TContext]):
     previous_response_id: NotRequired[str | None]
     """The ID of the previous response, if any."""
 
+    conversation_id: NotRequired[str | None]
+    """The ID of the stored conversation, if any."""
+
     session: NotRequired[Session | None]
     """The session for the run."""
 
@@ -215,6 +218,7 @@ async def run(
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         session: Session | None = None,
     ) -> RunResult:
         """Run a workflow starting at the given agent. The agent will run in a loop until a final
@@ -239,6 +243,7 @@ async def run(
             run_config: Global settings for the entire agent run.
             previous_response_id: The ID of the previous response, if using OpenAI models via the
                 Responses API, this allows you to skip passing in input from the previous turn.
+            conversation_id: The ID of the stored conversation, if any.
         Returns:
             A run result containing all the inputs, guardrail results and the output of the last
             agent. Agents may perform handoffs, so we don't know the specific type of the output.
@@ -252,6 +257,7 @@ async def run(
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            conversation_id=conversation_id,
             session=session,
         )
 
@@ -266,6 +272,7 @@ def run_sync(
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         session: Session | None = None,
     ) -> RunResult:
         """Run a workflow synchronously, starting at the given agent. Note that this just wraps the
@@ -293,6 +300,7 @@ def run_sync(
             run_config: Global settings for the entire agent run.
             previous_response_id: The ID of the previous response, if using OpenAI models via the
                 Responses API, this allows you to skip passing in input from the previous turn.
+            conversation_id: The ID of the stored conversation, if any.
         Returns:
             A run result containing all the inputs, guardrail results and the output of the last
             agent. Agents may perform handoffs, so we don't know the specific type of the output.
@@ -306,6 +314,7 @@ def run_sync(
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            conversation_id=conversation_id,
             session=session,
         )
 
@@ -319,6 +328,7 @@ def run_streamed(
         hooks: RunHooks[TContext] | None = None,
         run_config: RunConfig | None = None,
         previous_response_id: str | None = None,
+        conversation_id: str | None = None,
         session: Session | None = None,
     ) -> RunResultStreaming:
         """Run a workflow starting at the given agent in streaming mode. The returned result object
@@ -344,6 +354,7 @@ def run_streamed(
             run_config: Global settings for the entire agent run.
             previous_response_id: The ID of the previous response, if using OpenAI models via the
                 Responses API, this allows you to skip passing in input from the previous turn.
+            conversation_id: The ID of the stored conversation, if any.
         Returns:
             A result object that contains data about the run, as well as a method to stream events.
         """
@@ -356,6 +367,7 @@ def run_streamed(
             hooks=hooks,
             run_config=run_config,
             previous_response_id=previous_response_id,
+            conversation_id=conversation_id,
             session=session,
         )
 
@@ -377,6 +389,7 @@ async def run(
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
         if hooks is None:
             hooks = RunHooks[Any]()
@@ -469,6 +482,7 @@ async def run(
                                 should_run_agent_start_hooks=should_run_agent_start_hooks,
                                 tool_use_tracker=tool_use_tracker,
                                 previous_response_id=previous_response_id,
+                                conversation_id=conversation_id,
                             ),
                         )
                     else:
@@ -483,6 +497,7 @@ async def run(
                             should_run_agent_start_hooks=should_run_agent_start_hooks,
                             tool_use_tracker=tool_use_tracker,
                             previous_response_id=previous_response_id,
+                            conversation_id=conversation_id,
                         )
                     should_run_agent_start_hooks = False
 
@@ -549,6 +564,7 @@ def run_sync(
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
 
         return asyncio.get_event_loop().run_until_complete(
@@ -561,6 +577,7 @@ def run_sync(
                 hooks=hooks,
                 run_config=run_config,
                 previous_response_id=previous_response_id,
+                conversation_id=conversation_id,
             )
         )
 
@@ -575,6 +592,7 @@ def run_streamed(
         hooks = kwargs.get("hooks")
         run_config = kwargs.get("run_config")
         previous_response_id = kwargs.get("previous_response_id")
+        conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
 
         if hooks is None:
@@ -629,6 +647,7 @@ def run_streamed(
                 context_wrapper=context_wrapper,
                 run_config=run_config,
                 previous_response_id=previous_response_id,
+                conversation_id=conversation_id,
                 session=session,
             )
         )
@@ -729,6 +748,7 @@ async def _start_streaming(
         context_wrapper: RunContextWrapper[TContext],
         run_config: RunConfig,
         previous_response_id: str | None,
+        conversation_id: str | None,
         session: Session | None,
     ):
         if streamed_result.trace:
@@ -812,6 +832,7 @@ async def _start_streaming(
                         tool_use_tracker,
                         all_tools,
                         previous_response_id,
+                        conversation_id,
                     )
                     should_run_agent_start_hooks = False
 
@@ -914,6 +935,7 @@ async def _run_single_turn_streamed(
         tool_use_tracker: AgentToolUseTracker,
         all_tools: list[Tool],
         previous_response_id: str | None,
+        conversation_id: str | None,
     ) -> SingleStepResult:
         emitted_tool_call_ids: set[str] = set()
 
@@ -974,6 +996,7 @@ async def _run_single_turn_streamed(
                 run_config.tracing_disabled, run_config.trace_include_sensitive_data
             ),
             previous_response_id=previous_response_id,
+            conversation_id=conversation_id,
             prompt=prompt_config,
         ):
             if isinstance(event, ResponseCompletedEvent):
@@ -1082,6 +1105,7 @@ async def _run_single_turn(
         should_run_agent_start_hooks: bool,
         tool_use_tracker: AgentToolUseTracker,
         previous_response_id: str | None,
+        conversation_id: str | None,
     ) -> SingleStepResult:
         # Ensure we run the hooks before anything else
         if should_run_agent_start_hooks:
@@ -1115,6 +1139,7 @@ async def _run_single_turn(
             run_config,
             tool_use_tracker,
             previous_response_id,
+            conversation_id,
             prompt_config,
         )
 
@@ -1309,6 +1334,7 @@ async def _get_new_response(
         run_config: RunConfig,
         tool_use_tracker: AgentToolUseTracker,
         previous_response_id: str | None,
+        conversation_id: str | None,
         prompt_config: ResponsePromptParam | None,
     ) -> ModelResponse:
         # Allow user to modify model input right before the call, if configured
@@ -1343,6 +1369,7 @@ async def _get_new_response(
                 run_config.tracing_disabled, run_config.trace_include_sensitive_data
             ),
             previous_response_id=previous_response_id,
+            conversation_id=conversation_id,
             prompt=prompt_config,
         )
         # If the agent has hooks, we need to call them after the LLM call