openai-agents 0.2.9__py3-none-any.whl → 0.2.11__py3-none-any.whl

agents/memory/sqlite_session.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import threading
+from pathlib import Path
+
+from ..items import TResponseInputItem
+from .session import SessionABC
+
+
+class SQLiteSession(SessionABC):
+    """SQLite-based implementation of session storage.
+
+    This implementation stores conversation history in a SQLite database.
+    By default, uses an in-memory database that is lost when the process ends.
+    For persistent storage, provide a file path.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        db_path: str | Path = ":memory:",
+        sessions_table: str = "agent_sessions",
+        messages_table: str = "agent_messages",
+    ):
+        """Initialize the SQLite session.
+
+        Args:
+            session_id: Unique identifier for the conversation session
+            db_path: Path to the SQLite database file. Defaults to ':memory:' (in-memory database)
+            sessions_table: Name of the table to store session metadata. Defaults to
+                'agent_sessions'
+            messages_table: Name of the table to store message data. Defaults to 'agent_messages'
+        """
+        self.session_id = session_id
+        self.db_path = db_path
+        self.sessions_table = sessions_table
+        self.messages_table = messages_table
+        self._local = threading.local()
+        self._lock = threading.Lock()
+
+        # For in-memory databases, we need a shared connection to avoid thread isolation
+        # For file databases, we use thread-local connections for better concurrency
+        self._is_memory_db = str(db_path) == ":memory:"
+        if self._is_memory_db:
+            self._shared_connection = sqlite3.connect(":memory:", check_same_thread=False)
+            self._shared_connection.execute("PRAGMA journal_mode=WAL")
+            self._init_db_for_connection(self._shared_connection)
+        else:
+            # For file databases, initialize the schema once since it persists
+            init_conn = sqlite3.connect(str(self.db_path), check_same_thread=False)
+            init_conn.execute("PRAGMA journal_mode=WAL")
+            self._init_db_for_connection(init_conn)
+            init_conn.close()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        """Get a database connection."""
+        if self._is_memory_db:
+            # Use shared connection for in-memory database to avoid thread isolation
+            return self._shared_connection
+        else:
+            # Use thread-local connections for file databases
+            if not hasattr(self._local, "connection"):
+                self._local.connection = sqlite3.connect(
+                    str(self.db_path),
+                    check_same_thread=False,
+                )
+                self._local.connection.execute("PRAGMA journal_mode=WAL")
+            assert isinstance(self._local.connection, sqlite3.Connection), (
+                f"Expected sqlite3.Connection, got {type(self._local.connection)}"
+            )
+            return self._local.connection
+
+    def _init_db_for_connection(self, conn: sqlite3.Connection) -> None:
+        """Initialize the database schema for a specific connection."""
+        conn.execute(
+            f"""
+            CREATE TABLE IF NOT EXISTS {self.sessions_table} (
+                session_id TEXT PRIMARY KEY,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """
+        )
+
+        conn.execute(
+            f"""
+            CREATE TABLE IF NOT EXISTS {self.messages_table} (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                session_id TEXT NOT NULL,
+                message_data TEXT NOT NULL,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (session_id) REFERENCES {self.sessions_table} (session_id)
+                    ON DELETE CASCADE
+            )
+        """
+        )
+
+        conn.execute(
+            f"""
+            CREATE INDEX IF NOT EXISTS idx_{self.messages_table}_session_id
+            ON {self.messages_table} (session_id, created_at)
+        """
+        )
+
+        conn.commit()
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        """Retrieve the conversation history for this session.
+
+        Args:
+            limit: Maximum number of items to retrieve. If None, retrieves all items.
+                   When specified, returns the latest N items in chronological order.
+
+        Returns:
+            List of input items representing the conversation history
+        """
+
+        def _get_items_sync():
+            conn = self._get_connection()
+            with self._lock if self._is_memory_db else threading.Lock():
+                if limit is None:
+                    # Fetch all items in chronological order
+                    cursor = conn.execute(
+                        f"""
+                        SELECT message_data FROM {self.messages_table}
+                        WHERE session_id = ?
+                        ORDER BY created_at ASC
+                    """,
+                        (self.session_id,),
+                    )
+                else:
+                    # Fetch the latest N items in chronological order
+                    cursor = conn.execute(
+                        f"""
+                        SELECT message_data FROM {self.messages_table}
+                        WHERE session_id = ?
+                        ORDER BY created_at DESC
+                        LIMIT ?
+                        """,
+                        (self.session_id, limit),
+                    )
+
+                rows = cursor.fetchall()
+
+                # Reverse to get chronological order when using DESC
+                if limit is not None:
+                    rows = list(reversed(rows))
+
+                items = []
+                for (message_data,) in rows:
+                    try:
+                        item = json.loads(message_data)
+                        items.append(item)
+                    except json.JSONDecodeError:
+                        # Skip invalid JSON entries
+                        continue
+
+                return items
+
+        return await asyncio.to_thread(_get_items_sync)
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        """Add new items to the conversation history.
+
+        Args:
+            items: List of input items to add to the history
+        """
+        if not items:
+            return
+
+        def _add_items_sync():
+            conn = self._get_connection()
+
+            with self._lock if self._is_memory_db else threading.Lock():
+                # Ensure session exists
+                conn.execute(
+                    f"""
+                    INSERT OR IGNORE INTO {self.sessions_table} (session_id) VALUES (?)
+                """,
+                    (self.session_id,),
+                )
+
+                # Add items
+                message_data = [(self.session_id, json.dumps(item)) for item in items]
+                conn.executemany(
+                    f"""
+                    INSERT INTO {self.messages_table} (session_id, message_data) VALUES (?, ?)
+                """,
+                    message_data,
+                )
+
+                # Update session timestamp
+                conn.execute(
+                    f"""
+                    UPDATE {self.sessions_table}
+                    SET updated_at = CURRENT_TIMESTAMP
+                    WHERE session_id = ?
+                """,
+                    (self.session_id,),
+                )
+
+                conn.commit()
+
+        await asyncio.to_thread(_add_items_sync)
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        """Remove and return the most recent item from the session.
+
+        Returns:
+            The most recent item if it exists, None if the session is empty
+        """
+
+        def _pop_item_sync():
+            conn = self._get_connection()
+            with self._lock if self._is_memory_db else threading.Lock():
+                # Use DELETE with RETURNING to atomically delete and return the most recent item
+                cursor = conn.execute(
+                    f"""
+                    DELETE FROM {self.messages_table}
+                    WHERE id = (
+                        SELECT id FROM {self.messages_table}
+                        WHERE session_id = ?
+                        ORDER BY created_at DESC
+                        LIMIT 1
+                    )
+                    RETURNING message_data
+                    """,
+                    (self.session_id,),
+                )
+
+                result = cursor.fetchone()
+                conn.commit()
+
+                if result:
+                    message_data = result[0]
+                    try:
+                        item = json.loads(message_data)
+                        return item
+                    except json.JSONDecodeError:
+                        # Return None for corrupted JSON entries (already deleted)
+                        return None
+
+                return None
+
+        return await asyncio.to_thread(_pop_item_sync)
+
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
+
+        def _clear_session_sync():
+            conn = self._get_connection()
+            with self._lock if self._is_memory_db else threading.Lock():
+                conn.execute(
+                    f"DELETE FROM {self.messages_table} WHERE session_id = ?",
+                    (self.session_id,),
+                )
+                conn.execute(
+                    f"DELETE FROM {self.sessions_table} WHERE session_id = ?",
+                    (self.session_id,),
+                )
+                conn.commit()
+
+        await asyncio.to_thread(_clear_session_sync)
+
+    def close(self) -> None:
+        """Close the database connection."""
+        if self._is_memory_db:
+            if hasattr(self, "_shared_connection"):
+                self._shared_connection.close()
+        else:
+            if hasattr(self._local, "connection"):
+                self._local.connection.close()

agents/model_settings.py

@@ -55,7 +55,6 @@ Headers: TypeAlias = Mapping[str, Union[str, Omit]]
 ToolChoice: TypeAlias = Union[Literal["auto", "required", "none"], str, MCPToolChoice, None]
 
 
-
 @dataclass
 class ModelSettings:
     """Settings to use when calling an LLM.
@@ -121,7 +120,10 @@ class ModelSettings:
     """Whether to include usage chunk.
     Only available for Chat Completions API."""
 
-    response_include: list[ResponseIncludable] | None = None
+    # TODO: revisit ResponseIncludable | str if ResponseIncludable covers more cases
+    # We've added str to support missing ones like
+    # "web_search_call.action.sources" etc.
+    response_include: list[ResponseIncludable | str] | None = None
     """Additional output data to include in the model response.
     [include parameter](https://platform.openai.com/docs/api-reference/responses/create#responses-create-include)"""
 

agents/models/chatcmpl_stream_handler.py

@@ -28,11 +28,17 @@ from openai.types.responses import (
     ResponseTextDeltaEvent,
     ResponseUsage,
 )
-from openai.types.responses.response_reasoning_item import Summary
+from openai.types.responses.response_reasoning_item import Content, Summary
 from openai.types.responses.response_reasoning_summary_part_added_event import (
     Part as AddedEventPart,
 )
 from openai.types.responses.response_reasoning_summary_part_done_event import Part as DoneEventPart
+from openai.types.responses.response_reasoning_text_delta_event import (
+    ResponseReasoningTextDeltaEvent,
+)
+from openai.types.responses.response_reasoning_text_done_event import (
+    ResponseReasoningTextDoneEvent,
+)
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
 
 from ..items import TResponseStreamEvent
@@ -95,7 +101,7 @@ class ChatCmplStreamHandler:
 
             delta = chunk.choices[0].delta
 
-            # Handle reasoning content
+            # Handle reasoning content for reasoning summaries
             if hasattr(delta, "reasoning_content"):
                 reasoning_content = delta.reasoning_content
                 if reasoning_content and not state.reasoning_content_index_and_output:
@@ -138,10 +144,55 @@ class ChatCmplStreamHandler:
                     )
 
                     # Create a new summary with updated text
-                    current_summary = state.reasoning_content_index_and_output[1].summary[0]
-                    updated_text = current_summary.text + reasoning_content
-                    new_summary = Summary(text=updated_text, type="summary_text")
-                    state.reasoning_content_index_and_output[1].summary[0] = new_summary
+                    current_content = state.reasoning_content_index_and_output[1].summary[0]
+                    updated_text = current_content.text + reasoning_content
+                    new_content = Summary(text=updated_text, type="summary_text")
+                    state.reasoning_content_index_and_output[1].summary[0] = new_content
+
+            # Handle reasoning content from 3rd party platforms
+            if hasattr(delta, "reasoning"):
+                reasoning_text = delta.reasoning
+                if reasoning_text and not state.reasoning_content_index_and_output:
+                    state.reasoning_content_index_and_output = (
+                        0,
+                        ResponseReasoningItem(
+                            id=FAKE_RESPONSES_ID,
+                            summary=[],
+                            content=[Content(text="", type="reasoning_text")],
+                            type="reasoning",
+                        ),
+                    )
+                    yield ResponseOutputItemAddedEvent(
+                        item=ResponseReasoningItem(
+                            id=FAKE_RESPONSES_ID,
+                            summary=[],
+                            content=[Content(text="", type="reasoning_text")],
+                            type="reasoning",
+                        ),
+                        output_index=0,
+                        type="response.output_item.added",
+                        sequence_number=sequence_number.get_and_increment(),
+                    )
+
+                if reasoning_text and state.reasoning_content_index_and_output:
+                    yield ResponseReasoningTextDeltaEvent(
+                        delta=reasoning_text,
+                        item_id=FAKE_RESPONSES_ID,
+                        output_index=0,
+                        content_index=0,
+                        type="response.reasoning_text.delta",
+                        sequence_number=sequence_number.get_and_increment(),
+                    )
+
+                    # Create a new summary with updated text
+                    if state.reasoning_content_index_and_output[1].content is None:
+                        state.reasoning_content_index_and_output[1].content = [
+                            Content(text="", type="reasoning_text")
+                        ]
+                    current_text = state.reasoning_content_index_and_output[1].content[0]
+                    updated_text = current_text.text + reasoning_text
+                    new_text_content = Content(text=updated_text, type="reasoning_text")
+                    state.reasoning_content_index_and_output[1].content[0] = new_text_content
 
             # Handle regular content
             if delta.content is not None:
@@ -344,17 +395,30 @@ class ChatCmplStreamHandler:
                         )
 
         if state.reasoning_content_index_and_output:
-            yield ResponseReasoningSummaryPartDoneEvent(
-                item_id=FAKE_RESPONSES_ID,
-                output_index=0,
-                summary_index=0,
-                part=DoneEventPart(
-                    text=state.reasoning_content_index_and_output[1].summary[0].text,
-                    type="summary_text",
-                ),
-                type="response.reasoning_summary_part.done",
-                sequence_number=sequence_number.get_and_increment(),
-            )
+            if (
+                state.reasoning_content_index_and_output[1].summary
+                and len(state.reasoning_content_index_and_output[1].summary) > 0
+            ):
+                yield ResponseReasoningSummaryPartDoneEvent(
+                    item_id=FAKE_RESPONSES_ID,
+                    output_index=0,
+                    summary_index=0,
+                    part=DoneEventPart(
+                        text=state.reasoning_content_index_and_output[1].summary[0].text,
+                        type="summary_text",
+                    ),
+                    type="response.reasoning_summary_part.done",
+                    sequence_number=sequence_number.get_and_increment(),
+                )
+            elif state.reasoning_content_index_and_output[1].content is not None:
+                yield ResponseReasoningTextDoneEvent(
+                    item_id=FAKE_RESPONSES_ID,
+                    output_index=0,
+                    content_index=0,
+                    text=state.reasoning_content_index_and_output[1].content[0].text,
+                    type="response.reasoning_text.done",
+                    sequence_number=sequence_number.get_and_increment(),
+                )
             yield ResponseOutputItemDoneEvent(
                 item=state.reasoning_content_index_and_output[1],
                 output_index=0,

agents/models/interface.py

@@ -48,6 +48,7 @@ class Model(abc.ABC):
         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 @@ class Model(abc.ABC):
             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 @@ class Model(abc.ABC):
         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 @@ class Model(abc.ABC):
             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:

agents/models/openai_chatcompletions.py

@@ -55,7 +55,8 @@ class OpenAIChatCompletionsModel(Model):
         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 @@ class OpenAIChatCompletionsModel(Model):
         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]:
         """

agents/models/openai_responses.py

@@ -14,7 +14,6 @@ from openai.types.responses import (
     ResponseStreamEvent,
     ResponseTextConfigParam,
     ToolParam,
-    WebSearchToolParam,
     response_create_params,
 )
 from openai.types.responses.response_prompt_param import ResponsePromptParam
@@ -75,7 +74,8 @@ class OpenAIResponsesModel(Model):
         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 +87,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=False,
                     prompt=prompt,
                 )
@@ -150,7 +151,8 @@ class OpenAIResponsesModel(Model):
         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,
     ) -> AsyncIterator[ResponseStreamEvent]:
         """
@@ -165,7 +167,8 @@ class OpenAIResponsesModel(Model):
                     tools,
                     output_schema,
                     handoffs,
-                    previous_response_id,
+                    previous_response_id=previous_response_id,
+                    conversation_id=conversation_id,
                     stream=True,
                     prompt=prompt,
                 )
@@ -203,6 +206,7 @@ class OpenAIResponsesModel(Model):
         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 +221,7 @@ class OpenAIResponsesModel(Model):
         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 +234,8 @@ class OpenAIResponsesModel(Model):
         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 +271,7 @@ class OpenAIResponsesModel(Model):
                 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 +285,7 @@ class OpenAIResponsesModel(Model):
 
         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,
@@ -336,6 +344,11 @@ class Converter:
             return {
                 "type": "file_search",
             }
+        elif tool_choice == "web_search":
+            return {
+                # TODO: revist the type: ignore comment when ToolChoice is updated in the future
+                "type": "web_search",  # type: ignore [typeddict-item]
+            }
         elif tool_choice == "web_search_preview":
             return {
                 "type": "web_search_preview",
@@ -416,12 +429,13 @@ class Converter:
             }
             includes: ResponseIncludable | None = None
         elif isinstance(tool, WebSearchTool):
-            ws: WebSearchToolParam = {
-                "type": "web_search_preview",
+            # TODO: revist the type: ignore comment when ToolParam is updated in the future
+            converted_tool = {
+                "type": "web_search",
+                "filters": tool.filters.model_dump() if tool.filters is not None else None,  # type: ignore [typeddict-item]
                 "user_location": tool.user_location,
                 "search_context_size": tool.search_context_size,
             }
-            converted_tool = ws
             includes = None
         elif isinstance(tool, FileSearchTool):
             converted_tool = {

agents/realtime/model.py

@@ -118,6 +118,12 @@ class RealtimeModelConfig(TypedDict):
     the OpenAI Realtime model will use the default OpenAI WebSocket URL.
     """
 
+    headers: NotRequired[dict[str, str]]
+    """The headers to use when connecting. If unset, the model will use a sane default.
+    Note that, when you set this, authorization header won't be set under the hood.
+    e.g., {"api-key": "your api key here"} for Azure OpenAI Realtime WebSocket connections.
+    """
+
     initial_model_settings: NotRequired[RealtimeSessionModelSettings]
     """The initial model settings to use when connecting."""