Fix #1564 Add conversations API support (#1587)

This pull request resolves #1564

---------

Co-authored-by: Rohan Mehta <[email protected]>

Author: seratch

examples/memory/openai_session_example.py

@@ -0,0 +1,78 @@
+"""
+Example demonstrating session memory functionality.
+
+This example shows how to use session memory to maintain conversation history
+across multiple agent runs without manually handling .to_input_list().
+"""
+
+import asyncio
+
+from agents import Agent, OpenAIConversationsSession, Runner
+
+
+async def main():
+    # Create an agent
+    agent = Agent(
+        name="Assistant",
+        instructions="Reply very concisely.",
+    )
+
+    # Create a session instance that will persist across runs
+    session = OpenAIConversationsSession()
+
+    print("=== Session Example ===")
+    print("The agent will remember previous messages automatically.\n")
+
+    # First turn
+    print("First turn:")
+    print("User: What city is the Golden Gate Bridge in?")
+    result = await Runner.run(
+        agent,
+        "What city is the Golden Gate Bridge in?",
+        session=session,
+    )
+    print(f"Assistant: {result.final_output}")
+    print()
+
+    # Second turn - the agent will remember the previous conversation
+    print("Second turn:")
+    print("User: What state is it in?")
+    result = await Runner.run(agent, "What state is it in?", session=session)
+    print(f"Assistant: {result.final_output}")
+    print()
+
+    # Third turn - continuing the conversation
+    print("Third turn:")
+    print("User: What's the population of that state?")
+    result = await Runner.run(
+        agent,
+        "What's the population of that state?",
+        session=session,
+    )
+    print(f"Assistant: {result.final_output}")
+    print()
+
+    print("=== Conversation Complete ===")
+    print("Notice how the agent remembered the context from previous turns!")
+    print("Sessions automatically handles conversation history.")
+
+    # Demonstrate the limit parameter - get only the latest 2 items
+    print("\n=== Latest Items Demo ===")
+    latest_items = await session.get_items(limit=2)
+    # print(latest_items)
+    print("Latest 2 items:")
+    for i, msg in enumerate(latest_items, 1):
+        role = msg.get("role", "unknown")
+        content = msg.get("content", "")
+        print(f"  {i}. {role}: {content}")
+
+    print(f"\nFetched {len(latest_items)} out of total conversation history.")
+
+    # Get all items to show the difference
+    all_items = await session.get_items()
+    # print(all_items)
+    print(f"Total items in session: {len(all_items)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/basic/sqlalchemy_session_example.py renamed to examples/memory/sqlalchemy_session_example.py

@@ -20,28 +20,56 @@ async def main():
         create_tables=True,
     )
 
-    print("=== SQLAlchemySession Example ===")
+    print("=== Session Example ===")
     print("The agent will remember previous messages automatically.\n")
 
     # First turn
+    print("First turn:")
     print("User: What city is the Golden Gate Bridge in?")
     result = await Runner.run(
         agent,
         "What city is the Golden Gate Bridge in?",
         session=session,
     )
-    print(f"Assistant: {result.final_output}\n")
+    print(f"Assistant: {result.final_output}")
+    print()
 
     # Second turn - the agent will remember the previous conversation
+    print("Second turn:")
     print("User: What state is it in?")
+    result = await Runner.run(agent, "What state is it in?", session=session)
+    print(f"Assistant: {result.final_output}")
+    print()
+
+    # Third turn - continuing the conversation
+    print("Third turn:")
+    print("User: What's the population of that state?")
     result = await Runner.run(
         agent,
-        "What state is it in?",
+        "What's the population of that state?",
         session=session,
     )
-    print(f"Assistant: {result.final_output}\n")
+    print(f"Assistant: {result.final_output}")
+    print()
 
     print("=== Conversation Complete ===")
+    print("Notice how the agent remembered the context from previous turns!")
+    print("Sessions automatically handles conversation history.")
+
+    # Demonstrate the limit parameter - get only the latest 2 items
+    print("\n=== Latest Items Demo ===")
+    latest_items = await session.get_items(limit=2)
+    print("Latest 2 items:")
+    for i, msg in enumerate(latest_items, 1):
+        role = msg.get("role", "unknown")
+        content = msg.get("content", "")
+        print(f"  {i}. {role}: {content}")
+
+    print(f"\nFetched {len(latest_items)} out of total conversation history.")
+
+    # Get all items to show the difference
+    all_items = await session.get_items()
+    print(f"Total items in session: {len(all_items)}")
 
 
 if __name__ == "__main__":

examples/basic/session_example.py renamed to examples/memory/sqlite_session_example.py

@@ -47,6 +47,7 @@ async def stream_with_reasoning_content():
         handoffs=[],
         tracing=ModelTracing.DISABLED,
         previous_response_id=None,
+        conversation_id=None,
         prompt=None,
     ):
         if event.type == "response.reasoning_summary_text.delta":
@@ -83,6 +84,7 @@ async def get_response_with_reasoning_content():
         handoffs=[],
         tracing=ModelTracing.DISABLED,
         previous_response_id=None,
+        conversation_id=None,
         prompt=None,
     )
 

examples/reasoning_content/main.py

@@ -46,7 +46,7 @@
     TResponseInputItem,
 )
 from .lifecycle import AgentHooks, RunHooks
-from .memory import Session, SQLiteSession
+from .memory import OpenAIConversationsSession, Session, SessionABC, SQLiteSession
 from .model_settings import ModelSettings
 from .models.interface import Model, ModelProvider, ModelTracing
 from .models.multi_provider import MultiProvider
@@ -221,7 +221,9 @@ def enable_verbose_stdout_logging():
     "RunHooks",
     "AgentHooks",
     "Session",
+    "SessionABC",
     "SQLiteSession",
+    "OpenAIConversationsSession",
     "RunContextWrapper",
     "TContext",
     "RunErrorDetails",

src/agents/__init__.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/extensions/models/litellm_model.py

@@ -1,3 +1,10 @@
-from .session import Session, SQLiteSession
+from .openai_conversations_session import OpenAIConversationsSession
+from .session import Session, SessionABC
+from .sqlite_session import SQLiteSession
 
-__all__ = ["Session", "SQLiteSession"]
+__all__ = [
+    "Session",
+    "SessionABC",
+    "SQLiteSession",
+    "OpenAIConversationsSession",
+]

src/agents/memory/__init__.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+from agents.models._openai_shared import get_default_openai_client
+
+from ..items import TResponseInputItem
+from .session import SessionABC
+
+
+async def start_openai_conversations_session(openai_client: AsyncOpenAI | None = None) -> str:
+    _maybe_openai_client = openai_client
+    if openai_client is None:
+        _maybe_openai_client = get_default_openai_client() or AsyncOpenAI()
+    # this never be None here
+    _openai_client: AsyncOpenAI = _maybe_openai_client  # type: ignore [assignment]
+
+    response = await _openai_client.conversations.create(items=[])
+    return response.id
+
+
+_EMPTY_SESSION_ID = ""
+
+
+class OpenAIConversationsSession(SessionABC):
+    def __init__(
+        self,
+        *,
+        conversation_id: str | None = None,
+        openai_client: AsyncOpenAI | None = None,
+    ):
+        self._session_id: str | None = conversation_id
+        _openai_client = openai_client
+        if _openai_client is None:
+            _openai_client = get_default_openai_client() or AsyncOpenAI()
+        # this never be None here
+        self._openai_client: AsyncOpenAI = _openai_client
+
+    async def _get_session_id(self) -> str:
+        if self._session_id is None:
+            self._session_id = await start_openai_conversations_session(self._openai_client)
+        return self._session_id
+
+    async def _clear_session_id(self) -> None:
+        self._session_id = None
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        session_id = await self._get_session_id()
+        all_items = []
+        if limit is None:
+            async for item in self._openai_client.conversations.items.list(
+                conversation_id=session_id,
+                order="asc",
+            ):
+                # calling model_dump() to make this serializable
+                all_items.append(item.model_dump())
+        else:
+            async for item in self._openai_client.conversations.items.list(
+                conversation_id=session_id,
+                limit=limit,
+                order="desc",
+            ):
+                # calling model_dump() to make this serializable
+                all_items.append(item.model_dump())
+                if limit is not None and len(all_items) >= limit:
+                    break
+            all_items.reverse()
+
+        return all_items  # type: ignore
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        session_id = await self._get_session_id()
+        await self._openai_client.conversations.items.create(
+            conversation_id=session_id,
+            items=items,
+        )
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        session_id = await self._get_session_id()
+        items = await self.get_items(limit=1)
+        if not items:
+            return None
+        item_id: str = str(items[0]["id"])  # type: ignore [typeddict-item]
+        await self._openai_client.conversations.items.delete(
+            conversation_id=session_id, item_id=item_id
+        )
+        return items[0]
+
+    async def clear_session(self) -> None:
+        session_id = await self._get_session_id()
+        await self._openai_client.conversations.delete(
+            conversation_id=session_id,
+        )
+        await self._clear_session_id()