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

agents/mcp/server.py

@@ -3,10 +3,11 @@ from __future__ import annotations
 import abc
 import asyncio
 import inspect
+from collections.abc import Awaitable
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
 from datetime import timedelta
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, cast
+from typing import TYPE_CHECKING, Any, Callable, Literal, TypeVar
 
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp import ClientSession, StdioServerParameters, Tool as MCPTool, stdio_client
@@ -19,7 +20,9 @@ from typing_extensions import NotRequired, TypedDict
 from ..exceptions import UserError
 from ..logger import logger
 from ..run_context import RunContextWrapper
-from .util import ToolFilter, ToolFilterCallable, ToolFilterContext, ToolFilterStatic
+from .util import ToolFilter, ToolFilterContext, ToolFilterStatic
+
+T = TypeVar("T")
 
 if TYPE_CHECKING:
     from ..agent import AgentBase
@@ -98,6 +101,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         client_session_timeout_seconds: float | None,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """
         Args:
@@ -115,6 +120,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, used for exponential
+                backoff between retries.
         """
         super().__init__(use_structured_content=use_structured_content)
         self.session: ClientSession | None = None
@@ -124,6 +133,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         self.server_initialize_result: InitializeResult | None = None
 
         self.client_session_timeout_seconds = client_session_timeout_seconds
+        self.max_retry_attempts = max_retry_attempts
+        self.retry_backoff_seconds_base = retry_backoff_seconds_base
 
         # The cache is always dirty at startup, so that we fetch tools at least once
         self._cache_dirty = True
@@ -175,10 +186,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
     ) -> list[MCPTool]:
         """Apply dynamic tool filtering using a callable filter function."""
 
-        # Ensure we have a callable filter and cast to help mypy
+        # Ensure we have a callable filter
         if not callable(self.tool_filter):
             raise ValueError("Tool filter must be callable for dynamic filtering")
-        tool_filter_func = cast(ToolFilterCallable, self.tool_filter)
+        tool_filter_func = self.tool_filter
 
         # Create filter context
         filter_context = ToolFilterContext(
@@ -233,6 +244,18 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """Invalidate the tools cache."""
         self._cache_dirty = True
 
+    async def _run_with_retries(self, func: Callable[[], Awaitable[T]]) -> T:
+        attempts = 0
+        while True:
+            try:
+                return await func()
+            except Exception:
+                attempts += 1
+                if self.max_retry_attempts != -1 and attempts > self.max_retry_attempts:
+                    raise
+                backoff = self.retry_backoff_seconds_base * (2 ** (attempts - 1))
+                await asyncio.sleep(backoff)
+
     async def connect(self):
         """Connect to the server."""
         try:
@@ -267,15 +290,17 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """List the tools available on the server."""
         if not self.session:
             raise UserError("Server not initialized. Make sure you call `connect()` first.")
+        session = self.session
+        assert session is not None
 
         # Return from cache if caching is enabled, we have tools, and the cache is not dirty
         if self.cache_tools_list and not self._cache_dirty and self._tools_list:
             tools = self._tools_list
         else:
-            # Reset the cache dirty to False
-            self._cache_dirty = False
             # Fetch the tools from the server
-            self._tools_list = (await self.session.list_tools()).tools
+            result = await self._run_with_retries(lambda: session.list_tools())
+            self._tools_list = result.tools
+            self._cache_dirty = False
             tools = self._tools_list
 
         # Filter tools based on tool_filter
@@ -290,8 +315,10 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         """Invoke a tool on the server."""
         if not self.session:
             raise UserError("Server not initialized. Make sure you call `connect()` first.")
+        session = self.session
+        assert session is not None
 
-        return await self.session.call_tool(tool_name, arguments)
+        return await self._run_with_retries(lambda: session.call_tool(tool_name, arguments))
 
     async def list_prompts(
         self,
@@ -365,6 +392,8 @@ class MCPServerStdio(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the stdio transport.
 
@@ -388,12 +417,18 @@ class MCPServerStdio(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = StdioServerParameters(
@@ -455,6 +490,8 @@ class MCPServerSse(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the HTTP with SSE transport.
 
@@ -480,12 +517,18 @@ class MCPServerSse(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = params
@@ -547,6 +590,8 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
         use_structured_content: bool = False,
+        max_retry_attempts: int = 0,
+        retry_backoff_seconds_base: float = 1.0,
     ):
         """Create a new MCP server based on the Streamable HTTP transport.
 
@@ -573,12 +618,18 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
                 include the structured content in the `tool_result.content`, and using it by
                 default will cause duplicate content. You can set this to True if you know the
                 server will not duplicate the structured content in the `tool_result.content`.
+            max_retry_attempts: Number of times to retry failed list_tools/call_tool calls.
+                Defaults to no retries.
+            retry_backoff_seconds_base: The base delay, in seconds, for exponential
+                backoff between retries.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
             use_structured_content,
+            max_retry_attempts,
+            retry_backoff_seconds_base,
         )
 
         self.params = params

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()