openai-agents 0.3.2__py3-none-any.whl → 0.3.3__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/models/litellm_model.py

@@ -23,6 +23,7 @@ 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,
@@ -379,6 +384,121 @@ 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):
             return None

agents/models/chatcmpl_converter.py

@@ -533,7 +533,7 @@ class Converter:
 
                 if content_items and preserve_thinking_blocks:
                     # Reconstruct thinking blocks from content and signature
-                    pending_thinking_blocks = []
+                    reconstructed_thinking_blocks = []
                     for content_item in content_items:
                         if (
                             isinstance(content_item, dict)
@@ -546,7 +546,11 @@ class Converter:
                             # Add signatures if available
                             if signatures:
                                 thinking_block["signature"] = signatures.pop(0)
-                            pending_thinking_blocks.append(thinking_block)
+                            reconstructed_thinking_blocks.append(thinking_block)
+
+                    # Store thinking blocks as pending for the next assistant message
+                    # This preserves the original behavior
+                    pending_thinking_blocks = reconstructed_thinking_blocks
 
             # 8) If we haven't recognized it => fail or ignore
             else:

agents/result.py

@@ -31,6 +31,7 @@ from .util._pretty_print import (
 if TYPE_CHECKING:
     from ._run_impl import QueueCompleteSentinel
     from .agent import Agent
+    from .tool_guardrails import ToolInputGuardrailResult, ToolOutputGuardrailResult
 
 T = TypeVar("T")
 
@@ -59,6 +60,12 @@ class RunResultBase(abc.ABC):
     output_guardrail_results: list[OutputGuardrailResult]
     """Guardrail results for the final output of the agent."""
 
+    tool_input_guardrail_results: list[ToolInputGuardrailResult]
+    """Tool input guardrail results from all tools executed during the run."""
+
+    tool_output_guardrail_results: list[ToolOutputGuardrailResult]
+    """Tool output guardrail results from all tools executed during the run."""
+
     context_wrapper: RunContextWrapper[Any]
     """The context wrapper for the agent run."""
 

agents/run.py

@@ -68,6 +68,7 @@ from .stream_events import (
     StreamEvent,
 )
 from .tool import Tool
+from .tool_guardrails import ToolInputGuardrailResult, ToolOutputGuardrailResult
 from .tracing import Span, SpanError, agent_span, get_current_trace, trace
 from .tracing.span_data import AgentSpanData
 from .usage import Usage
@@ -494,6 +495,8 @@ class AgentRunner:
             )
 
             input_guardrail_results: list[InputGuardrailResult] = []
+            tool_input_guardrail_results: list[ToolInputGuardrailResult] = []
+            tool_output_guardrail_results: list[ToolOutputGuardrailResult] = []
 
             current_span: Span[AgentSpanData] | None = None
             current_agent = starting_agent
@@ -584,6 +587,10 @@ class AgentRunner:
                     original_input = turn_result.original_input
                     generated_items = turn_result.generated_items
 
+                    # Collect tool guardrail results from this turn
+                    tool_input_guardrail_results.extend(turn_result.tool_input_guardrail_results)
+                    tool_output_guardrail_results.extend(turn_result.tool_output_guardrail_results)
+
                     if isinstance(turn_result.next_step, NextStepFinalOutput):
                         output_guardrail_results = await self._run_output_guardrails(
                             current_agent.output_guardrails + (run_config.output_guardrails or []),
@@ -599,6 +606,8 @@ class AgentRunner:
                             _last_agent=current_agent,
                             input_guardrail_results=input_guardrail_results,
                             output_guardrail_results=output_guardrail_results,
+                            tool_input_guardrail_results=tool_input_guardrail_results,
+                            tool_output_guardrail_results=tool_output_guardrail_results,
                             context_wrapper=context_wrapper,
                         )
                         await self._save_result_to_session(session, [], turn_result.new_step_items)
@@ -706,6 +715,8 @@ class AgentRunner:
             max_turns=max_turns,
             input_guardrail_results=[],
             output_guardrail_results=[],
+            tool_input_guardrail_results=[],
+            tool_output_guardrail_results=[],
             _current_agent_output_schema=output_schema,
             trace=new_trace,
             context_wrapper=context_wrapper,

agents/tool.py

@@ -27,6 +27,7 @@ from .logger import logger
 from .run_context import RunContextWrapper
 from .strict_schema import ensure_strict_json_schema
 from .tool_context import ToolContext
+from .tool_guardrails import ToolInputGuardrail, ToolOutputGuardrail
 from .tracing import SpanError
 from .util import _error_tracing
 from .util._types import MaybeAwaitable
@@ -94,6 +95,13 @@ class FunctionTool:
     and returns whether the tool is enabled. You can use this to dynamically enable/disable a tool
     based on your context/state."""
 
+    # Tool-specific guardrails
+    tool_input_guardrails: list[ToolInputGuardrail[Any]] | None = None
+    """Optional list of input guardrails to run before invoking this tool."""
+
+    tool_output_guardrails: list[ToolOutputGuardrail[Any]] | None = None
+    """Optional list of output guardrails to run after invoking this tool."""
+
     def __post_init__(self):
         if self.strict_json_schema:
             self.params_json_schema = ensure_strict_json_schema(self.params_json_schema)