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

agents/mcp/util.py

@@ -1,8 +1,9 @@
 import functools
 import json
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable, Optional, Protocol, Union
 
+import httpx
 from typing_extensions import NotRequired, TypedDict
 
 from .. import _debug
@@ -21,6 +22,21 @@ if TYPE_CHECKING:
     from .server import MCPServer
 
 
+class HttpClientFactory(Protocol):
+    """Protocol for HTTP client factory functions.
+
+    This interface matches the MCP SDK's McpHttpClientFactory but is defined locally
+    to avoid accessing internal MCP SDK modules.
+    """
+
+    def __call__(
+        self,
+        headers: Optional[dict[str, str]] = None,
+        timeout: Optional[httpx.Timeout] = None,
+        auth: Optional[httpx.Auth] = None,
+    ) -> httpx.AsyncClient: ...
+
+
 @dataclass
 class ToolFilterContext:
     """Context information available to tool filter functions."""
@@ -185,9 +201,14 @@ class MCPUtil:
 
         try:
             result = await server.call_tool(tool.name, json_data)
+        except UserError:
+            # Re-raise UserError as-is (it already has a good message)
+            raise
         except Exception as e:
-            logger.error(f"Error invoking MCP tool {tool.name}: {e}")
-            raise AgentsException(f"Error invoking MCP tool {tool.name}: {e}") from e
+            logger.error(f"Error invoking MCP tool {tool.name} on server '{server.name}': {e}")
+            raise AgentsException(
+                f"Error invoking MCP tool {tool.name} on server '{server.name}': {e}"
+            ) from e
 
         if _debug.DONT_LOG_TOOL_DATA:
             logger.debug(f"MCP tool {tool.name} completed.")

agents/memory/__init__.py

@@ -1,3 +1,23 @@
-from .session import Session, SQLiteSession
+from .openai_conversations_session import OpenAIConversationsSession
+from .openai_responses_compaction_session import OpenAIResponsesCompactionSession
+from .session import (
+    OpenAIResponsesCompactionArgs,
+    OpenAIResponsesCompactionAwareSession,
+    Session,
+    SessionABC,
+    is_openai_responses_compaction_aware_session,
+)
+from .sqlite_session import SQLiteSession
+from .util import SessionInputCallback
 
-__all__ = ["Session", "SQLiteSession"]
+__all__ = [
+    "Session",
+    "SessionABC",
+    "SessionInputCallback",
+    "SQLiteSession",
+    "OpenAIConversationsSession",
+    "OpenAIResponsesCompactionSession",
+    "OpenAIResponsesCompactionArgs",
+    "OpenAIResponsesCompactionAwareSession",
+    "is_openai_responses_compaction_aware_session",
+]

agents/memory/openai_conversations_session.py

@@ -0,0 +1,91 @@
+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
+
+
+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(exclude_unset=True))
+        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(exclude_unset=True))
+                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/openai_responses_compaction_session.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Callable
+
+from openai import AsyncOpenAI
+
+from ..models._openai_shared import get_default_openai_client
+from .openai_conversations_session import OpenAIConversationsSession
+from .session import (
+    OpenAIResponsesCompactionArgs,
+    OpenAIResponsesCompactionAwareSession,
+    SessionABC,
+)
+
+if TYPE_CHECKING:
+    from ..items import TResponseInputItem
+    from .session import Session
+
+logger = logging.getLogger("openai-agents.openai.compaction")
+
+DEFAULT_COMPACTION_THRESHOLD = 10
+
+
+def select_compaction_candidate_items(
+    items: list[TResponseInputItem],
+) -> list[TResponseInputItem]:
+    """Select compaction candidate items.
+
+    Excludes user messages and compaction items.
+    """
+
+    def _is_user_message(item: TResponseInputItem) -> bool:
+        if not isinstance(item, dict):
+            return False
+        if item.get("type") == "message":
+            return item.get("role") == "user"
+        return item.get("role") == "user" and "content" in item
+
+    return [
+        item
+        for item in items
+        if not (
+            _is_user_message(item) or (isinstance(item, dict) and item.get("type") == "compaction")
+        )
+    ]
+
+
+def default_should_trigger_compaction(context: dict[str, Any]) -> bool:
+    """Default decision: compact when >= 10 candidate items exist."""
+    return len(context["compaction_candidate_items"]) >= DEFAULT_COMPACTION_THRESHOLD
+
+
+def is_openai_model_name(model: str) -> bool:
+    """Validate model name follows OpenAI conventions."""
+    trimmed = model.strip()
+    if not trimmed:
+        return False
+
+    # Handle fine-tuned models: ft:gpt-4.1:org:proj:suffix
+    without_ft_prefix = trimmed[3:] if trimmed.startswith("ft:") else trimmed
+    root = without_ft_prefix.split(":", 1)[0]
+
+    # Allow gpt-* and o* models
+    if root.startswith("gpt-"):
+        return True
+    if root.startswith("o") and root[1:2].isdigit():
+        return True
+
+    return False
+
+
+class OpenAIResponsesCompactionSession(SessionABC, OpenAIResponsesCompactionAwareSession):
+    """Session decorator that triggers responses.compact when stored history grows.
+
+    Works with OpenAI Responses API models only. Wraps any Session (except
+    OpenAIConversationsSession) and automatically calls the OpenAI responses.compact
+    API after each turn when the decision hook returns True.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        underlying_session: Session,
+        *,
+        client: AsyncOpenAI | None = None,
+        model: str = "gpt-4.1",
+        should_trigger_compaction: Callable[[dict[str, Any]], bool] | None = None,
+    ):
+        """Initialize the compaction session.
+
+        Args:
+            session_id: Identifier for this session.
+            underlying_session: Session store that holds the compacted history. Cannot be
+                OpenAIConversationsSession.
+            client: OpenAI client for responses.compact API calls. Defaults to
+                get_default_openai_client() or new AsyncOpenAI().
+            model: Model to use for responses.compact. Defaults to "gpt-4.1". Must be an
+                OpenAI model name (gpt-*, o*, or ft:gpt-*).
+            should_trigger_compaction: Custom decision hook. Defaults to triggering when
+                10+ compaction candidates exist.
+        """
+        if isinstance(underlying_session, OpenAIConversationsSession):
+            raise ValueError(
+                "OpenAIResponsesCompactionSession cannot wrap OpenAIConversationsSession "
+                "because it manages its own history on the server."
+            )
+
+        if not is_openai_model_name(model):
+            raise ValueError(f"Unsupported model for OpenAI responses compaction: {model}")
+
+        self.session_id = session_id
+        self.underlying_session = underlying_session
+        self._client = client
+        self.model = model
+        self.should_trigger_compaction = (
+            should_trigger_compaction or default_should_trigger_compaction
+        )
+
+        # cache for incremental candidate tracking
+        self._compaction_candidate_items: list[TResponseInputItem] | None = None
+        self._session_items: list[TResponseInputItem] | None = None
+        self._response_id: str | None = None
+        self._deferred_response_id: str | None = None
+
+    @property
+    def client(self) -> AsyncOpenAI:
+        if self._client is None:
+            self._client = get_default_openai_client() or AsyncOpenAI()
+        return self._client
+
+    async def run_compaction(self, args: OpenAIResponsesCompactionArgs | None = None) -> None:
+        """Run compaction using responses.compact API."""
+        if args and args.get("response_id"):
+            self._response_id = args["response_id"]
+
+        if not self._response_id:
+            raise ValueError(
+                "OpenAIResponsesCompactionSession.run_compaction requires a response_id"
+            )
+
+        compaction_candidate_items, session_items = await self._ensure_compaction_candidates()
+
+        force = args.get("force", False) if args else False
+        should_compact = force or self.should_trigger_compaction(
+            {
+                "response_id": self._response_id,
+                "compaction_candidate_items": compaction_candidate_items,
+                "session_items": session_items,
+            }
+        )
+
+        if not should_compact:
+            logger.debug(f"skip: decision hook declined compaction for {self._response_id}")
+            return
+
+        self._deferred_response_id = None
+        logger.debug(f"compact: start for {self._response_id} using {self.model}")
+
+        compacted = await self.client.responses.compact(
+            previous_response_id=self._response_id,
+            model=self.model,
+        )
+
+        await self.underlying_session.clear_session()
+        output_items: list[TResponseInputItem] = []
+        if compacted.output:
+            for item in compacted.output:
+                if isinstance(item, dict):
+                    output_items.append(item)
+                else:
+                    # Suppress Pydantic literal warnings: responses.compact can return
+                    # user-style input_text content inside ResponseOutputMessage.
+                    output_items.append(
+                        item.model_dump(exclude_unset=True, warnings=False)  # type: ignore
+                    )
+
+        if output_items:
+            await self.underlying_session.add_items(output_items)
+
+        self._compaction_candidate_items = select_compaction_candidate_items(output_items)
+        self._session_items = output_items
+
+        logger.debug(
+            f"compact: done for {self._response_id} "
+            f"(output={len(output_items)}, candidates={len(self._compaction_candidate_items)})"
+        )
+
+    async def get_items(self, limit: int | None = None) -> list[TResponseInputItem]:
+        return await self.underlying_session.get_items(limit)
+
+    async def _defer_compaction(self, response_id: str) -> None:
+        if self._deferred_response_id is not None:
+            return
+        compaction_candidate_items, session_items = await self._ensure_compaction_candidates()
+        should_compact = self.should_trigger_compaction(
+            {
+                "response_id": response_id,
+                "compaction_candidate_items": compaction_candidate_items,
+                "session_items": session_items,
+            }
+        )
+        if should_compact:
+            self._deferred_response_id = response_id
+
+    def _get_deferred_compaction_response_id(self) -> str | None:
+        return self._deferred_response_id
+
+    def _clear_deferred_compaction(self) -> None:
+        self._deferred_response_id = None
+
+    async def add_items(self, items: list[TResponseInputItem]) -> None:
+        await self.underlying_session.add_items(items)
+        if self._compaction_candidate_items is not None:
+            new_candidates = select_compaction_candidate_items(items)
+            if new_candidates:
+                self._compaction_candidate_items.extend(new_candidates)
+        if self._session_items is not None:
+            self._session_items.extend(items)
+
+    async def pop_item(self) -> TResponseInputItem | None:
+        popped = await self.underlying_session.pop_item()
+        if popped:
+            self._compaction_candidate_items = None
+            self._session_items = None
+        return popped
+
+    async def clear_session(self) -> None:
+        await self.underlying_session.clear_session()
+        self._compaction_candidate_items = []
+        self._session_items = []
+        self._deferred_response_id = None
+
+    async def _ensure_compaction_candidates(
+        self,
+    ) -> tuple[list[TResponseInputItem], list[TResponseInputItem]]:
+        """Lazy-load and cache compaction candidates."""
+        if self._compaction_candidate_items is not None and self._session_items is not None:
+            return (self._compaction_candidate_items[:], self._session_items[:])
+
+        history = await self.underlying_session.get_items()
+        candidates = select_compaction_candidate_items(history)
+        self._compaction_candidate_items = candidates
+        self._session_items = history
+
+        logger.debug(
+            f"candidates: initialized (history={len(history)}, candidates={len(candidates)})"
+        )
+        return (candidates[:], history[:])