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

agents/__init__.py

@@ -46,7 +46,7 @@ from .items import (
     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 @@ __all__ = [
     "RunHooks",
     "AgentHooks",
     "Session",
+    "SessionABC",
     "SQLiteSession",
+    "OpenAIConversationsSession",
     "RunContextWrapper",
     "TContext",
     "RunErrorDetails",

agents/_run_impl.py

@@ -509,13 +509,29 @@ class RunImpl:
             # Regular function tool call
             else:
                 if output.name not in function_map:
-                    _error_tracing.attach_error_to_current_span(
-                        SpanError(
-                            message="Tool not found",
-                            data={"tool_name": output.name},
+                    if output_schema is not None and output.name == "json_tool_call":
+                        # LiteLLM could generate non-existent tool calls for structured outputs
+                        items.append(ToolCallItem(raw_item=output, agent=agent))
+                        functions.append(
+                            ToolRunFunction(
+                                tool_call=output,
+                                # this tool does not exist in function_map, so generate ad-hoc one,
+                                # which just parses the input if it's a string, and returns the
+                                # value otherwise
+                                function_tool=_build_litellm_json_tool_call(output),
+                            )
                         )
-                    )
-                    raise ModelBehaviorError(f"Tool {output.name} not found in agent {agent.name}")
+                        continue
+                    else:
+                        _error_tracing.attach_error_to_current_span(
+                            SpanError(
+                                message="Tool not found",
+                                data={"tool_name": output.name},
+                            )
+                        )
+                        error = f"Tool {output.name} not found in agent {agent.name}"
+                        raise ModelBehaviorError(error)
+
                 items.append(ToolCallItem(raw_item=output, agent=agent))
                 functions.append(
                     ToolRunFunction(
@@ -1193,3 +1209,21 @@ class LocalShellAction:
                 # "id": "out" + call.tool_call.id,  # TODO remove this, it should be optional
             },
         )
+
+
+def _build_litellm_json_tool_call(output: ResponseFunctionToolCall) -> FunctionTool:
+    async def on_invoke_tool(_ctx: ToolContext[Any], value: Any) -> Any:
+        if isinstance(value, str):
+            import json
+
+            return json.loads(value)
+        return value
+
+    return FunctionTool(
+        name=output.name,
+        description=output.name,
+        params_json_schema={},
+        on_invoke_tool=on_invoke_tool,
+        strict_json_schema=True,
+        is_enabled=True,
+    )

agents/extensions/memory/sqlalchemy_session.py

@@ -64,23 +64,19 @@ class SQLAlchemySession(SessionABC):
         create_tables: bool = False,
         sessions_table: str = "agent_sessions",
         messages_table: str = "agent_messages",
-    ):  # noqa: D401 – short description on the class-level docstring
-        """Create a new session.
-
-        Parameters
-        ----------
-        session_id
-            Unique identifier for the conversation.
-        engine
-            A pre-configured SQLAlchemy *async* engine.  The engine **must** be
-            created with an async driver (``postgresql+asyncpg://``,
-            ``mysql+aiomysql://`` or ``sqlite+aiosqlite://``).
-        create_tables
-            Whether to automatically create the required tables & indexes.
-            Defaults to *False* for production use. Set to *True* for development
-            and testing when migrations aren't used.
-        sessions_table, messages_table
-            Override default table names if needed.
+    ):
+        """Initializes a new SQLAlchemySession.
+
+        Args:
+            session_id (str): Unique identifier for the conversation.
+            engine (AsyncEngine): A pre-configured SQLAlchemy async engine. The engine
+                must be created with an async driver (e.g., 'postgresql+asyncpg://',
+                'mysql+aiomysql://', or 'sqlite+aiosqlite://').
+            create_tables (bool, optional): Whether to automatically create the required
+                tables and indexes. Defaults to False for production use. Set to True for
+                development and testing when migrations aren't used.
+            sessions_table (str, optional): Override the default table name for sessions if needed.
+            messages_table (str, optional): Override the default table name for messages if needed.
         """
         self.session_id = session_id
         self._engine = engine
@@ -132,9 +128,7 @@ class SQLAlchemySession(SessionABC):
         )
 
         # Async session factory
-        self._session_factory = async_sessionmaker(
-            self._engine, expire_on_commit=False
-        )
+        self._session_factory = async_sessionmaker(self._engine, expire_on_commit=False)
 
         self._create_tables = create_tables
 
@@ -152,16 +146,16 @@ class SQLAlchemySession(SessionABC):
     ) -> SQLAlchemySession:
         """Create a session from a database URL string.
 
-        Parameters
-        ----------
-        session_id
-            Conversation ID.
-        url
-            Any SQLAlchemy async URL – e.g. ``"postgresql+asyncpg://user:pass@host/db"``.
-        engine_kwargs
-            Additional kwargs forwarded to :pyfunc:`sqlalchemy.ext.asyncio.create_async_engine`.
-        kwargs
-            Forwarded to the main constructor (``create_tables``, custom table names, …).
+        Args:
+            session_id (str): Conversation ID.
+            url (str): Any SQLAlchemy async URL, e.g. "postgresql+asyncpg://user:pass@host/db".
+            engine_kwargs (dict[str, Any] | None): Additional keyword arguments forwarded to
+                sqlalchemy.ext.asyncio.create_async_engine.
+            **kwargs: Additional keyword arguments forwarded to the main constructor
+                (e.g., create_tables, custom table names, etc.).
+
+        Returns:
+            SQLAlchemySession: An instance of SQLAlchemySession connected to the specified database.
         """
         engine_kwargs = engine_kwargs or {}
         engine = create_async_engine(url, **engine_kwargs)
@@ -186,6 +180,15 @@ class SQLAlchemySession(SessionABC):
             self._create_tables = False  # Only create once
 
     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
+        """
         await self._ensure_tables()
         async with self._session_factory() as sess:
             if limit is None:
@@ -220,6 +223,11 @@ class SQLAlchemySession(SessionABC):
             return items
 
     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
 
@@ -258,6 +266,11 @@ class SQLAlchemySession(SessionABC):
                 )
 
     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
+        """
         await self._ensure_tables()
         async with self._session_factory() as sess:
             async with sess.begin():
@@ -286,7 +299,8 @@ class SQLAlchemySession(SessionABC):
                 except json.JSONDecodeError:
                     return None
 
-    async def clear_session(self) -> None:  # noqa: D401 – imperative mood is fine
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
         await self._ensure_tables()
         async with self._session_factory() as sess:
             async with sess.begin():

agents/extensions/models/litellm_model.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import time
 from collections.abc import AsyncIterator
+from copy import copy
 from typing import Any, Literal, cast, overload
 
 from openai.types.responses.response_usage import InputTokensDetails, OutputTokensDetails
@@ -82,7 +83,8 @@ class LitellmModel(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: Any | None = None,
     ) -> ModelResponse:
         with generation_span(
@@ -171,7 +173,8 @@ class LitellmModel(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: Any | None = None,
     ) -> AsyncIterator[TResponseStreamEvent]:
         with generation_span(
@@ -300,9 +303,9 @@ class LitellmModel(Model):
 
         extra_kwargs = {}
         if model_settings.extra_query:
-            extra_kwargs["extra_query"] = model_settings.extra_query
+            extra_kwargs["extra_query"] = copy(model_settings.extra_query)
         if model_settings.metadata:
-            extra_kwargs["metadata"] = model_settings.metadata
+            extra_kwargs["metadata"] = copy(model_settings.metadata)
         if model_settings.extra_body and isinstance(model_settings.extra_body, dict):
             extra_kwargs.update(model_settings.extra_body)
 

agents/handoffs.py

@@ -119,9 +119,9 @@ class Handoff(Generic[TContext, TAgent]):
     True, as it increases the likelihood of correct JSON input.
     """
 
-    is_enabled: bool | Callable[
-        [RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]
-    ] = True
+    is_enabled: bool | Callable[[RunContextWrapper[Any], AgentBase[Any]], MaybeAwaitable[bool]] = (
+        True
+    )
     """Whether the handoff is enabled. Either a bool or a Callable that takes the run context and
     agent and returns whether the handoff is enabled. You can use this to dynamically enable/disable
     a handoff based on your context/state."""

agents/memory/__init__.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",
+]

agents/memory/openai_conversations_session.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()

agents/memory/session.py

@@ -1,11 +1,6 @@
 from __future__ import annotations
 
-import asyncio
-import json
-import sqlite3
-import threading
 from abc import ABC, abstractmethod
-from pathlib import Path
 from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
@@ -102,268 +97,3 @@ class SessionABC(ABC):
     async def clear_session(self) -> None:
         """Clear all items for this session."""
         ...
-
-
-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()