openai-agents 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

agents/extensions/memory/redis_session.py

@@ -0,0 +1,267 @@
+"""Redis-powered Session backend.
+
+Usage::
+
+    from agents.extensions.memory import RedisSession
+
+    # Create from Redis URL
+    session = RedisSession.from_url(
+        session_id="user-123",
+        url="redis://localhost:6379/0",
+    )
+
+    # Or pass an existing Redis client that your application already manages
+    session = RedisSession(
+        session_id="user-123",
+        redis_client=my_redis_client,
+    )
+
+    await Runner.run(agent, "Hello", session=session)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any
+from urllib.parse import urlparse
+
+try:
+    import redis.asyncio as redis
+    from redis.asyncio import Redis
+except ImportError as e:
+    raise ImportError(
+        "RedisSession requires the 'redis' package. Install it with: pip install redis"
+    ) from e
+
+from ...items import TResponseInputItem
+from ...memory.session import SessionABC
+
+
+class RedisSession(SessionABC):
+    """Redis implementation of :pyclass:`agents.memory.session.Session`."""
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        redis_client: Redis,
+        key_prefix: str = "agents:session",
+        ttl: int | None = None,
+    ):
+        """Initializes a new RedisSession.
+
+        Args:
+            session_id (str): Unique identifier for the conversation.
+            redis_client (Redis[bytes]): A pre-configured Redis async client.
+            key_prefix (str, optional): Prefix for Redis keys to avoid collisions.
+                Defaults to "agents:session".
+            ttl (int | None, optional): Time-to-live in seconds for session data.
+                If None, data persists indefinitely. Defaults to None.
+        """
+        self.session_id = session_id
+        self._redis = redis_client
+        self._key_prefix = key_prefix
+        self._ttl = ttl
+        self._lock = asyncio.Lock()
+        self._owns_client = False  # Track if we own the Redis client
+
+        # Redis key patterns
+        self._session_key = f"{self._key_prefix}:{self.session_id}"
+        self._messages_key = f"{self._session_key}:messages"
+        self._counter_key = f"{self._session_key}:counter"
+
+    @classmethod
+    def from_url(
+        cls,
+        session_id: str,
+        *,
+        url: str,
+        redis_kwargs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> RedisSession:
+        """Create a session from a Redis URL string.
+
+        Args:
+            session_id (str): Conversation ID.
+            url (str): Redis URL, e.g. "redis://localhost:6379/0" or "rediss://host:6380".
+            redis_kwargs (dict[str, Any] | None): Additional keyword arguments forwarded to
+                redis.asyncio.from_url.
+            **kwargs: Additional keyword arguments forwarded to the main constructor
+                (e.g., key_prefix, ttl, etc.).
+
+        Returns:
+            RedisSession: An instance of RedisSession connected to the specified Redis server.
+        """
+        redis_kwargs = redis_kwargs or {}
+
+        # Parse URL to determine if we need SSL
+        parsed = urlparse(url)
+        if parsed.scheme == "rediss":
+            redis_kwargs.setdefault("ssl", True)
+
+        redis_client = redis.from_url(url, **redis_kwargs)
+        session = cls(session_id, redis_client=redis_client, **kwargs)
+        session._owns_client = True  # We created the client, so we own it
+        return session
+
+    async def _serialize_item(self, item: TResponseInputItem) -> str:
+        """Serialize an item to JSON string. Can be overridden by subclasses."""
+        return json.dumps(item, separators=(",", ":"))
+
+    async def _deserialize_item(self, item: str) -> TResponseInputItem:
+        """Deserialize a JSON string to an item. Can be overridden by subclasses."""
+        return json.loads(item)  # type: ignore[no-any-return]  # json.loads returns Any but we know the structure
+
+    async def _get_next_id(self) -> int:
+        """Get the next message ID using Redis INCR for atomic increment."""
+        result = await self._redis.incr(self._counter_key)
+        return int(result)
+
+    async def _set_ttl_if_configured(self, *keys: str) -> None:
+        """Set TTL on keys if configured."""
+        if self._ttl is not None:
+            pipe = self._redis.pipeline()
+            for key in keys:
+                pipe.expire(key, self._ttl)
+            await pipe.execute()
+
+    # ------------------------------------------------------------------
+    # Session protocol implementation
+    # ------------------------------------------------------------------
+
+    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 with self._lock:
+            if limit is None:
+                # Get all messages in chronological order
+                raw_messages = await self._redis.lrange(self._messages_key, 0, -1)  # type: ignore[misc]  # Redis library returns Union[Awaitable[T], T] in async context
+            else:
+                if limit <= 0:
+                    return []
+                # Get the latest N messages (Redis list is ordered chronologically)
+                # Use negative indices to get from the end - Redis uses -N to -1 for last N items
+                raw_messages = await self._redis.lrange(self._messages_key, -limit, -1)  # type: ignore[misc]  # Redis library returns Union[Awaitable[T], T] in async context
+
+            items: list[TResponseInputItem] = []
+            for raw_msg in raw_messages:
+                try:
+                    # Handle both bytes (default) and str (decode_responses=True) Redis clients
+                    if isinstance(raw_msg, bytes):
+                        msg_str = raw_msg.decode("utf-8")
+                    else:
+                        msg_str = raw_msg  # Already a string
+                    item = await self._deserialize_item(msg_str)
+                    items.append(item)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    # Skip corrupted messages
+                    continue
+
+            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
+
+        async with self._lock:
+            pipe = self._redis.pipeline()
+
+            # Set session metadata with current timestamp
+            pipe.hset(
+                self._session_key,
+                mapping={
+                    "session_id": self.session_id,
+                    "created_at": str(int(time.time())),
+                    "updated_at": str(int(time.time())),
+                },
+            )
+
+            # Add all items to the messages list
+            serialized_items = []
+            for item in items:
+                serialized = await self._serialize_item(item)
+                serialized_items.append(serialized)
+
+            if serialized_items:
+                pipe.rpush(self._messages_key, *serialized_items)
+
+            # Update the session timestamp
+            pipe.hset(self._session_key, "updated_at", str(int(time.time())))
+
+            # Execute all commands
+            await pipe.execute()
+
+            # Set TTL if configured
+            await self._set_ttl_if_configured(
+                self._session_key, self._messages_key, self._counter_key
+            )
+
+    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 with self._lock:
+            # Use RPOP to atomically remove and return the rightmost (most recent) item
+            raw_msg = await self._redis.rpop(self._messages_key)  # type: ignore[misc]  # Redis library returns Union[Awaitable[T], T] in async context
+
+            if raw_msg is None:
+                return None
+
+            try:
+                # Handle both bytes (default) and str (decode_responses=True) Redis clients
+                if isinstance(raw_msg, bytes):
+                    msg_str = raw_msg.decode("utf-8")
+                else:
+                    msg_str = raw_msg  # Already a string
+                return await self._deserialize_item(msg_str)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                # Return None for corrupted messages (already removed)
+                return None
+
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
+        async with self._lock:
+            # Delete all keys associated with this session
+            await self._redis.delete(
+                self._session_key,
+                self._messages_key,
+                self._counter_key,
+            )
+
+    async def close(self) -> None:
+        """Close the Redis connection.
+
+        Only closes the connection if this session owns the Redis client
+        (i.e., created via from_url). If the client was injected externally,
+        the caller is responsible for managing its lifecycle.
+        """
+        if self._owns_client:
+            await self._redis.aclose()
+
+    async def ping(self) -> bool:
+        """Test Redis connectivity.
+
+        Returns:
+            True if Redis is reachable, False otherwise.
+        """
+        try:
+            await self._redis.ping()
+            return True
+        except Exception:
+            return False

agents/extensions/memory/sqlalchemy_session.py

@@ -195,7 +195,10 @@ class SQLAlchemySession(SessionABC):
                 stmt = (
                     select(self._messages.c.message_data)
                     .where(self._messages.c.session_id == self.session_id)
-                    .order_by(self._messages.c.created_at.asc())
+                    .order_by(
+                        self._messages.c.created_at.asc(),
+                        self._messages.c.id.asc(),
+                    )
                 )
             else:
                 stmt = (
@@ -203,7 +206,10 @@ class SQLAlchemySession(SessionABC):
                     .where(self._messages.c.session_id == self.session_id)
                     # Use DESC + LIMIT to get the latest N
                     # then reverse later for chronological order.
-                    .order_by(self._messages.c.created_at.desc())
+                    .order_by(
+                        self._messages.c.created_at.desc(),
+                        self._messages.c.id.desc(),
+                    )
                     .limit(limit)
                 )
 
@@ -278,7 +284,10 @@ class SQLAlchemySession(SessionABC):
                 subq = (
                     select(self._messages.c.id)
                     .where(self._messages.c.session_id == self.session_id)
-                    .order_by(self._messages.c.created_at.desc())
+                    .order_by(
+                        self._messages.c.created_at.desc(),
+                        self._messages.c.id.desc(),
+                    )
                     .limit(1)
                 )
                 res = await sess.execute(subq)

agents/extensions/models/litellm_model.py

@@ -18,11 +18,12 @@ except ImportError as _e:
         "dependency group: `pip install 'openai-agents[litellm]'`."
     ) from _e
 
-from openai import NOT_GIVEN, AsyncStream, NotGiven
+from openai import AsyncStream, NotGiven, omit
 from openai.types.chat import (
     ChatCompletionChunk,
     ChatCompletionMessageCustomToolCall,
     ChatCompletionMessageFunctionToolCall,
+    ChatCompletionMessageParam,
 )
 from openai.types.chat.chat_completion_message import (
     Annotation,
@@ -267,6 +268,10 @@ class LitellmModel(Model):
             input, preserve_thinking_blocks=preserve_thinking_blocks
         )
 
+        # Fix for interleaved thinking bug: reorder messages to ensure tool_use comes before tool_result  # noqa: E501
+        if preserve_thinking_blocks:
+            converted_messages = self._fix_tool_message_ordering(converted_messages)
+
         if system_instructions:
             converted_messages.insert(
                 0,
@@ -369,7 +374,7 @@ class LitellmModel(Model):
             object="response",
             output=[],
             tool_choice=cast(Literal["auto", "required", "none"], tool_choice)
-            if tool_choice != NOT_GIVEN
+            if tool_choice is not omit
             else "auto",
             top_p=model_settings.top_p,
             temperature=model_settings.temperature,
@@ -379,8 +384,123 @@ class LitellmModel(Model):
         )
         return response, ret
 
+    def _fix_tool_message_ordering(
+        self, messages: list[ChatCompletionMessageParam]
+    ) -> list[ChatCompletionMessageParam]:
+        """
+        Fix the ordering of tool messages to ensure tool_use messages come before tool_result messages.
+
+        This addresses the interleaved thinking bug where conversation histories may contain
+        tool results before their corresponding tool calls, causing Anthropic API to reject the request.
+        """  # noqa: E501
+        if not messages:
+            return messages
+
+        # Collect all tool calls and tool results
+        tool_call_messages = {}  # tool_id -> (index, message)
+        tool_result_messages = {}  # tool_id -> (index, message)
+        other_messages = []  # (index, message) for non-tool messages
+
+        for i, message in enumerate(messages):
+            if not isinstance(message, dict):
+                other_messages.append((i, message))
+                continue
+
+            role = message.get("role")
+
+            if role == "assistant" and message.get("tool_calls"):
+                # Extract tool calls from this assistant message
+                tool_calls = message.get("tool_calls", [])
+                if isinstance(tool_calls, list):
+                    for tool_call in tool_calls:
+                        if isinstance(tool_call, dict):
+                            tool_id = tool_call.get("id")
+                            if tool_id:
+                                # Create a separate assistant message for each tool call
+                                single_tool_msg = cast(dict[str, Any], message.copy())
+                                single_tool_msg["tool_calls"] = [tool_call]
+                                tool_call_messages[tool_id] = (
+                                    i,
+                                    cast(ChatCompletionMessageParam, single_tool_msg),
+                                )
+
+            elif role == "tool":
+                tool_call_id = message.get("tool_call_id")
+                if tool_call_id:
+                    tool_result_messages[tool_call_id] = (i, message)
+                else:
+                    other_messages.append((i, message))
+            else:
+                other_messages.append((i, message))
+
+        # First, identify which tool results will be paired to avoid duplicates
+        paired_tool_result_indices = set()
+        for tool_id in tool_call_messages:
+            if tool_id in tool_result_messages:
+                tool_result_idx, _ = tool_result_messages[tool_id]
+                paired_tool_result_indices.add(tool_result_idx)
+
+        # Create the fixed message sequence
+        fixed_messages: list[ChatCompletionMessageParam] = []
+        used_indices = set()
+
+        # Add messages in their original order, but ensure tool_use → tool_result pairing
+        for i, original_message in enumerate(messages):
+            if i in used_indices:
+                continue
+
+            if not isinstance(original_message, dict):
+                fixed_messages.append(original_message)
+                used_indices.add(i)
+                continue
+
+            role = original_message.get("role")
+
+            if role == "assistant" and original_message.get("tool_calls"):
+                # Process each tool call in this assistant message
+                tool_calls = original_message.get("tool_calls", [])
+                if isinstance(tool_calls, list):
+                    for tool_call in tool_calls:
+                        if isinstance(tool_call, dict):
+                            tool_id = tool_call.get("id")
+                            if (
+                                tool_id
+                                and tool_id in tool_call_messages
+                                and tool_id in tool_result_messages
+                            ):
+                                # Add tool_use → tool_result pair
+                                _, tool_call_msg = tool_call_messages[tool_id]
+                                tool_result_idx, tool_result_msg = tool_result_messages[tool_id]
+
+                                fixed_messages.append(tool_call_msg)
+                                fixed_messages.append(tool_result_msg)
+
+                                # Mark both as used
+                                used_indices.add(tool_call_messages[tool_id][0])
+                                used_indices.add(tool_result_idx)
+                            elif tool_id and tool_id in tool_call_messages:
+                                # Tool call without result - add just the tool call
+                                _, tool_call_msg = tool_call_messages[tool_id]
+                                fixed_messages.append(tool_call_msg)
+                                used_indices.add(tool_call_messages[tool_id][0])
+
+                used_indices.add(i)  # Mark original multi-tool message as used
+
+            elif role == "tool":
+                # Only preserve unmatched tool results to avoid duplicates
+                if i not in paired_tool_result_indices:
+                    fixed_messages.append(original_message)
+                used_indices.add(i)
+
+            else:
+                # Regular message - add it normally
+                fixed_messages.append(original_message)
+                used_indices.add(i)
+
+        return fixed_messages
+
     def _remove_not_given(self, value: Any) -> Any:
-        if isinstance(value, NotGiven):
+        if value is omit or isinstance(value, NotGiven):
             return None
         return value
 

agents/items.py

@@ -21,6 +21,12 @@ from openai.types.responses import (
 from openai.types.responses.response_code_interpreter_tool_call import (
     ResponseCodeInterpreterToolCall,
 )
+from openai.types.responses.response_function_call_output_item_list_param import (
+    ResponseFunctionCallOutputItemListParam,
+    ResponseFunctionCallOutputItemParam,
+)
+from openai.types.responses.response_input_file_content_param import ResponseInputFileContentParam
+from openai.types.responses.response_input_image_content_param import ResponseInputImageContentParam
 from openai.types.responses.response_input_item_param import (
     ComputerCallOutput,
     FunctionCallOutput,
@@ -36,9 +42,17 @@ from openai.types.responses.response_output_item import (
 )
 from openai.types.responses.response_reasoning_item import ResponseReasoningItem
 from pydantic import BaseModel
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, assert_never
 
 from .exceptions import AgentsException, ModelBehaviorError
+from .logger import logger
+from .tool import (
+    ToolOutputFileContent,
+    ToolOutputImage,
+    ToolOutputText,
+    ValidToolOutputPydanticModels,
+    ValidToolOutputPydanticModelsTypeAdapter,
+)
 from .usage import Usage
 
 if TYPE_CHECKING:
@@ -298,11 +312,93 @@ class ItemHelpers:
 
     @classmethod
     def tool_call_output_item(
-        cls, tool_call: ResponseFunctionToolCall, output: str
+        cls, tool_call: ResponseFunctionToolCall, output: Any
     ) -> FunctionCallOutput:
-        """Creates a tool call output item from a tool call and its output."""
+        """Creates a tool call output item from a tool call and its output.
+
+        Accepts either plain values (stringified) or structured outputs using
+        input_text/input_image/input_file shapes. Structured outputs may be
+        provided as Pydantic models or dicts, or an iterable of such items.
+        """
+
+        converted_output = cls._convert_tool_output(output)
+
         return {
             "call_id": tool_call.call_id,
-            "output": output,
+            "output": converted_output,
             "type": "function_call_output",
         }
+
+    @classmethod
+    def _convert_tool_output(cls, output: Any) -> str | ResponseFunctionCallOutputItemListParam:
+        """Converts a tool return value into an output acceptable by the Responses API."""
+
+        # If the output is either a single or list of the known structured output types, convert to
+        # ResponseFunctionCallOutputItemListParam. Else, just stringify.
+        if isinstance(output, (list, tuple)):
+            maybe_converted_output_list = [
+                cls._maybe_get_output_as_structured_function_output(item) for item in output
+            ]
+            if all(maybe_converted_output_list):
+                return [
+                    cls._convert_single_tool_output_pydantic_model(item)
+                    for item in maybe_converted_output_list
+                    if item is not None
+                ]
+            else:
+                return str(output)
+        else:
+            maybe_converted_output = cls._maybe_get_output_as_structured_function_output(output)
+            if maybe_converted_output:
+                return [cls._convert_single_tool_output_pydantic_model(maybe_converted_output)]
+            else:
+                return str(output)
+
+    @classmethod
+    def _maybe_get_output_as_structured_function_output(
+        cls, output: Any
+    ) -> ValidToolOutputPydanticModels | None:
+        if isinstance(output, (ToolOutputText, ToolOutputImage, ToolOutputFileContent)):
+            return output
+        elif isinstance(output, dict):
+            try:
+                return ValidToolOutputPydanticModelsTypeAdapter.validate_python(output)
+            except pydantic.ValidationError:
+                logger.debug("dict was not a valid tool output pydantic model")
+                return None
+
+        return None
+
+    @classmethod
+    def _convert_single_tool_output_pydantic_model(
+        cls, output: ValidToolOutputPydanticModels
+    ) -> ResponseFunctionCallOutputItemParam:
+        if isinstance(output, ToolOutputText):
+            return {"type": "input_text", "text": output.text}
+        elif isinstance(output, ToolOutputImage):
+            # Forward all provided optional fields so the Responses API receives
+            # the correct identifiers and settings for the image resource.
+            result: ResponseInputImageContentParam = {"type": "input_image"}
+            if output.image_url is not None:
+                result["image_url"] = output.image_url
+            if output.file_id is not None:
+                result["file_id"] = output.file_id
+            if output.detail is not None:
+                result["detail"] = output.detail
+            return result
+        elif isinstance(output, ToolOutputFileContent):
+            # Forward all provided optional fields so the Responses API receives
+            # the correct identifiers and metadata for the file resource.
+            result_file: ResponseInputFileContentParam = {"type": "input_file"}
+            if output.file_data is not None:
+                result_file["file_data"] = output.file_data
+            if output.file_url is not None:
+                result_file["file_url"] = output.file_url
+            if output.file_id is not None:
+                result_file["file_id"] = output.file_id
+            if output.filename is not None:
+                result_file["filename"] = output.filename
+            return result_file
+        else:
+            assert_never(output)
+            raise ValueError(f"Unexpected tool output type: {output}")