openai-agents 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

agents/mcp/server.py

@@ -13,7 +13,7 @@ from mcp import ClientSession, StdioServerParameters, Tool as MCPTool, stdio_cli
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import GetSessionIdCallback, streamablehttp_client
 from mcp.shared.message import SessionMessage
-from mcp.types import CallToolResult, InitializeResult
+from mcp.types import CallToolResult, GetPromptResult, InitializeResult, ListPromptsResult
 from typing_extensions import NotRequired, TypedDict
 
 from ..exceptions import UserError
@@ -22,12 +22,23 @@ from ..run_context import RunContextWrapper
 from .util import ToolFilter, ToolFilterCallable, ToolFilterContext, ToolFilterStatic
 
 if TYPE_CHECKING:
-    from ..agent import Agent
+    from ..agent import AgentBase
 
 
 class MCPServer(abc.ABC):
     """Base class for Model Context Protocol servers."""
 
+    def __init__(self, use_structured_content: bool = False):
+        """
+        Args:
+            use_structured_content: Whether to use `tool_result.structured_content` when calling an
+                MCP tool.Defaults to False for backwards compatibility - most MCP servers still
+                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`.
+        """
+        self.use_structured_content = use_structured_content
+
     @abc.abstractmethod
     async def connect(self):
         """Connect to the server. For example, this might mean spawning a subprocess or
@@ -52,8 +63,8 @@ class MCPServer(abc.ABC):
     @abc.abstractmethod
     async def list_tools(
         self,
-        run_context: RunContextWrapper[Any],
-        agent: Agent[Any],
+        run_context: RunContextWrapper[Any] | None = None,
+        agent: AgentBase | None = None,
     ) -> list[MCPTool]:
         """List the tools available on the server."""
         pass
@@ -63,6 +74,20 @@ class MCPServer(abc.ABC):
         """Invoke a tool on the server."""
         pass
 
+    @abc.abstractmethod
+    async def list_prompts(
+        self,
+    ) -> ListPromptsResult:
+        """List the prompts available on the server."""
+        pass
+
+    @abc.abstractmethod
+    async def get_prompt(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> GetPromptResult:
+        """Get a specific prompt from the server."""
+        pass
+
 
 class _MCPServerWithClientSession(MCPServer, abc.ABC):
     """Base class for MCP servers that use a `ClientSession` to communicate with the server."""
@@ -72,6 +97,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         cache_tools_list: bool,
         client_session_timeout_seconds: float | None,
         tool_filter: ToolFilter = None,
+        use_structured_content: bool = False,
     ):
         """
         Args:
@@ -84,7 +110,13 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
 
             client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
             tool_filter: The tool filter to use for filtering tools.
+            use_structured_content: Whether to use `tool_result.structured_content` when calling an
+                MCP tool. Defaults to False for backwards compatibility - most MCP servers still
+                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`.
         """
+        super().__init__(use_structured_content=use_structured_content)
         self.session: ClientSession | None = None
         self.exit_stack: AsyncExitStack = AsyncExitStack()
         self._cleanup_lock: asyncio.Lock = asyncio.Lock()
@@ -103,7 +135,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         self,
         tools: list[MCPTool],
         run_context: RunContextWrapper[Any],
-        agent: Agent[Any],
+        agent: AgentBase,
     ) -> list[MCPTool]:
         """Apply the tool filter to the list of tools."""
         if self.tool_filter is None:
@@ -118,9 +150,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
             return await self._apply_dynamic_tool_filter(tools, run_context, agent)
 
     def _apply_static_tool_filter(
-        self,
-        tools: list[MCPTool],
-        static_filter: ToolFilterStatic
+        self, tools: list[MCPTool], static_filter: ToolFilterStatic
     ) -> list[MCPTool]:
         """Apply static tool filtering based on allowlist and blocklist."""
         filtered_tools = tools
@@ -141,7 +171,7 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         self,
         tools: list[MCPTool],
         run_context: RunContextWrapper[Any],
-        agent: Agent[Any],
+        agent: AgentBase,
     ) -> list[MCPTool]:
         """Apply dynamic tool filtering using a callable filter function."""
 
@@ -231,8 +261,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
 
     async def list_tools(
         self,
-        run_context: RunContextWrapper[Any],
-        agent: Agent[Any],
+        run_context: RunContextWrapper[Any] | None = None,
+        agent: AgentBase | None = None,
     ) -> list[MCPTool]:
         """List the tools available on the server."""
         if not self.session:
@@ -251,6 +281,8 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
         # Filter tools based on tool_filter
         filtered_tools = tools
         if self.tool_filter is not None:
+            if run_context is None or agent is None:
+                raise UserError("run_context and agent are required for dynamic tool filtering")
             filtered_tools = await self._apply_tool_filter(filtered_tools, run_context, agent)
         return filtered_tools
 
@@ -261,6 +293,24 @@ class _MCPServerWithClientSession(MCPServer, abc.ABC):
 
         return await self.session.call_tool(tool_name, arguments)
 
+    async def list_prompts(
+        self,
+    ) -> ListPromptsResult:
+        """List the prompts available on the server."""
+        if not self.session:
+            raise UserError("Server not initialized. Make sure you call `connect()` first.")
+
+        return await self.session.list_prompts()
+
+    async def get_prompt(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> GetPromptResult:
+        """Get a specific prompt from the server."""
+        if not self.session:
+            raise UserError("Server not initialized. Make sure you call `connect()` first.")
+
+        return await self.session.get_prompt(name, arguments)
+
     async def cleanup(self):
         """Cleanup the server."""
         async with self._cleanup_lock:
@@ -314,6 +364,7 @@ class MCPServerStdio(_MCPServerWithClientSession):
         name: str | None = None,
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
+        use_structured_content: bool = False,
     ):
         """Create a new MCP server based on the stdio transport.
 
@@ -332,11 +383,17 @@ class MCPServerStdio(_MCPServerWithClientSession):
                 command.
             client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
             tool_filter: The tool filter to use for filtering tools.
+            use_structured_content: Whether to use `tool_result.structured_content` when calling an
+                MCP tool. Defaults to False for backwards compatibility - most MCP servers still
+                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`.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
+            use_structured_content,
         )
 
         self.params = StdioServerParameters(
@@ -397,6 +454,7 @@ class MCPServerSse(_MCPServerWithClientSession):
         name: str | None = None,
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
+        use_structured_content: bool = False,
     ):
         """Create a new MCP server based on the HTTP with SSE transport.
 
@@ -417,11 +475,17 @@ class MCPServerSse(_MCPServerWithClientSession):
 
             client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
             tool_filter: The tool filter to use for filtering tools.
+            use_structured_content: Whether to use `tool_result.structured_content` when calling an
+                MCP tool. Defaults to False for backwards compatibility - most MCP servers still
+                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`.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
+            use_structured_content,
         )
 
         self.params = params
@@ -482,6 +546,7 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
         name: str | None = None,
         client_session_timeout_seconds: float | None = 5,
         tool_filter: ToolFilter = None,
+        use_structured_content: bool = False,
     ):
         """Create a new MCP server based on the Streamable HTTP transport.
 
@@ -503,11 +568,17 @@ class MCPServerStreamableHttp(_MCPServerWithClientSession):
 
             client_session_timeout_seconds: the read timeout passed to the MCP ClientSession.
             tool_filter: The tool filter to use for filtering tools.
+            use_structured_content: Whether to use `tool_result.structured_content` when calling an
+                MCP tool. Defaults to False for backwards compatibility - most MCP servers still
+                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`.
         """
         super().__init__(
             cache_tools_list,
             client_session_timeout_seconds,
             tool_filter,
+            use_structured_content,
         )
 
         self.params = params

agents/mcp/util.py

@@ -5,12 +5,11 @@ from typing import TYPE_CHECKING, Any, Callable, Optional, Union
 
 from typing_extensions import NotRequired, TypedDict
 
-from agents.strict_schema import ensure_strict_json_schema
-
 from .. import _debug
 from ..exceptions import AgentsException, ModelBehaviorError, UserError
 from ..logger import logger
 from ..run_context import RunContextWrapper
+from ..strict_schema import ensure_strict_json_schema
 from ..tool import FunctionTool, Tool
 from ..tracing import FunctionSpanData, get_current_span, mcp_tools_span
 from ..util._types import MaybeAwaitable
@@ -18,7 +17,7 @@ from ..util._types import MaybeAwaitable
 if TYPE_CHECKING:
     from mcp.types import Tool as MCPTool
 
-    from ..agent import Agent
+    from ..agent import AgentBase
     from .server import MCPServer
 
 
@@ -29,7 +28,7 @@ class ToolFilterContext:
     run_context: RunContextWrapper[Any]
     """The current run context."""
 
-    agent: "Agent[Any]"
+    agent: "AgentBase"
     """The agent that is requesting the tool list."""
 
     server_name: str
@@ -100,7 +99,7 @@ class MCPUtil:
         servers: list["MCPServer"],
         convert_schemas_to_strict: bool,
         run_context: RunContextWrapper[Any],
-        agent: "Agent[Any]",
+        agent: "AgentBase",
     ) -> list[Tool]:
         """Get all function tools from a list of MCP servers."""
         tools = []
@@ -126,7 +125,7 @@ class MCPUtil:
         server: "MCPServer",
         convert_schemas_to_strict: bool,
         run_context: RunContextWrapper[Any],
-        agent: "Agent[Any]",
+        agent: "AgentBase",
     ) -> list[Tool]:
         """Get all function tools from a single MCP server."""
 
@@ -199,11 +198,19 @@ class MCPUtil:
         # string. We'll try to convert.
         if len(result.content) == 1:
             tool_output = result.content[0].model_dump_json()
+            # Append structured content if it exists and we're using it.
+            if server.use_structured_content and result.structuredContent:
+                tool_output = f"{tool_output}\n{json.dumps(result.structuredContent)}"
         elif len(result.content) > 1:
-            tool_output = json.dumps([item.model_dump(mode="json") for item in result.content])
+            tool_results = [item.model_dump(mode="json") for item in result.content]
+            if server.use_structured_content and result.structuredContent:
+                tool_results.append(result.structuredContent)
+            tool_output = json.dumps(tool_results)
+        elif server.use_structured_content and result.structuredContent:
+            tool_output = json.dumps(result.structuredContent)
         else:
-            logger.error(f"Errored MCP tool result: {result}")
-            tool_output = "Error running tool."
+            # Empty content is a valid result (e.g., "no results found")
+            tool_output = "[]"
 
         current_span = get_current_span()
         if current_span:

agents/memory/__init__.py

@@ -0,0 +1,3 @@
+from .session import Session, SQLiteSession
+
+__all__ = ["Session", "SQLiteSession"]

agents/memory/session.py

@@ -0,0 +1,369 @@
+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:
+    from ..items import TResponseInputItem
+
+
+@runtime_checkable
+class Session(Protocol):
+    """Protocol for session implementations.
+
+    Session stores conversation history for a specific session, allowing
+    agents to maintain context without requiring explicit manual memory management.
+    """
+
+    session_id: str
+
+    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
+        """
+        ...
+
+    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
+        """
+        ...
+
+    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
+        """
+        ...
+
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
+        ...
+
+
+class SessionABC(ABC):
+    """Abstract base class for session implementations.
+
+    Session stores conversation history for a specific session, allowing
+    agents to maintain context without requiring explicit manual memory management.
+
+    This ABC is intended for internal use and as a base class for concrete implementations.
+    Third-party libraries should implement the Session protocol instead.
+    """
+
+    session_id: str
+
+    @abstractmethod
+    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
+        """
+        ...
+
+    @abstractmethod
+    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
+        """
+        ...
+
+    @abstractmethod
+    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
+        """
+        ...
+
+    @abstractmethod
+    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()