openai-agents 0.3.1__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,
@@ -39,7 +40,7 @@ from ...items import ModelResponse, TResponseInputItem, TResponseStreamEvent
 from ...logger import logger
 from ...model_settings import ModelSettings
 from ...models.chatcmpl_converter import Converter
-from ...models.chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE
+from ...models.chatcmpl_helpers import HEADERS, HEADERS_OVERRIDE
 from ...models.chatcmpl_stream_handler import ChatCmplStreamHandler
 from ...models.fake_id import FAKE_RESPONSES_ID
 from ...models.interface import Model, ModelTracing
@@ -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,17 +384,128 @@ 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
         return value
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {**HEADERS, **(model_settings.extra_headers or {}), **(HEADERS_OVERRIDE.get() or {})}
 
 
 class LitellmConverter:

agents/models/chatcmpl_converter.py

@@ -107,7 +107,7 @@ class Converter:
             if hasattr(message, "thinking_blocks") and message.thinking_blocks:
                 # Store thinking text in content and signature in encrypted_content
                 reasoning_item.content = []
-                signature = None
+                signatures: list[str] = []
                 for block in message.thinking_blocks:
                     if isinstance(block, dict):
                         thinking_text = block.get("thinking", "")
@@ -116,15 +116,12 @@ class Converter:
                                 Content(text=thinking_text, type="reasoning_text")
                             )
                         # Store the signature if present
-                        if block.get("signature"):
-                            signature = block.get("signature")
+                        if signature := block.get("signature"):
+                            signatures.append(signature)
 
-                # Store only the last signature in encrypted_content
-                # If there are multiple thinking blocks, this should be a problem.
-                # In practice, there should only be one signature for the entire reasoning step.
-                # Tested with: claude-sonnet-4-20250514
-                if signature:
-                    reasoning_item.encrypted_content = signature
+                # Store the signatures in encrypted_content with newline delimiter
+                if signatures:
+                    reasoning_item.encrypted_content = "\n".join(signatures)
 
             items.append(reasoning_item)
 
@@ -483,7 +480,20 @@ class Converter:
                 # If we have pending thinking blocks, use them as the content
                 # This is required for Anthropic API tool calls with interleaved thinking
                 if pending_thinking_blocks:
-                    asst["content"] = pending_thinking_blocks  # type: ignore
+                    # If there is a text content, save it to append after thinking blocks
+                    # content type is Union[str, Iterable[ContentArrayOfContentPart], None]
+                    if "content" in asst and isinstance(asst["content"], str):
+                        text_content = ChatCompletionContentPartTextParam(
+                            text=asst["content"], type="text"
+                        )
+                        asst["content"] = [text_content]
+
+                    if "content" not in asst or asst["content"] is None:
+                        asst["content"] = []
+
+                    # Thinking blocks MUST come before any other content
+                    # We ignore type errors because pending_thinking_blocks is not openai standard
+                    asst["content"] = pending_thinking_blocks + asst["content"]  # type: ignore
                     pending_thinking_blocks = None  # Clear after using
 
                 tool_calls = list(asst.get("tool_calls", []))
@@ -518,11 +528,12 @@ class Converter:
             elif reasoning_item := cls.maybe_reasoning_message(item):
                 # Reconstruct thinking blocks from content (text) and encrypted_content (signature)
                 content_items = reasoning_item.get("content", [])
-                signature = reasoning_item.get("encrypted_content")
+                encrypted_content = reasoning_item.get("encrypted_content")
+                signatures = encrypted_content.split("\n") if encrypted_content else []
 
                 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)
@@ -532,10 +543,14 @@ class Converter:
                                 "type": "thinking",
                                 "thinking": content_item.get("text", ""),
                             }
-                            # Add signature if available
-                            if signature:
-                                thinking_block["signature"] = signature
-                            pending_thinking_blocks.append(thinking_block)
+                            # Add signatures if available
+                            if signatures:
+                                thinking_block["signature"] = signatures.pop(0)
+                            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/models/chatcmpl_helpers.py

@@ -10,8 +10,8 @@ from ..version import __version__
 _USER_AGENT = f"Agents/Python {__version__}"
 HEADERS = {"User-Agent": _USER_AGENT}
 
-USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
-    "openai_chatcompletions_user_agent_override", default=None
+HEADERS_OVERRIDE: ContextVar[dict[str, str] | None] = ContextVar(
+    "openai_chatcompletions_headers_override", default=None
 )
 
 

agents/models/openai_chatcompletions.py

@@ -25,7 +25,7 @@ from ..tracing.spans import Span
 from ..usage import Usage
 from ..util._json import _to_dump_compatible
 from .chatcmpl_converter import Converter
-from .chatcmpl_helpers import HEADERS, USER_AGENT_OVERRIDE, ChatCmplHelpers
+from .chatcmpl_helpers import HEADERS, HEADERS_OVERRIDE, ChatCmplHelpers
 from .chatcmpl_stream_handler import ChatCmplStreamHandler
 from .fake_id import FAKE_RESPONSES_ID
 from .interface import Model, ModelTracing
@@ -351,8 +351,8 @@ class OpenAIChatCompletionsModel(Model):
         return self._client
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {
+            **HEADERS,
+            **(model_settings.extra_headers or {}),
+            **(HEADERS_OVERRIDE.get() or {}),
+        }

agents/models/openai_responses.py

@@ -50,9 +50,9 @@ if TYPE_CHECKING:
 _USER_AGENT = f"Agents/Python {__version__}"
 _HEADERS = {"User-Agent": _USER_AGENT}
 
-# Override for the User-Agent header used by the Responses API.
-_USER_AGENT_OVERRIDE: ContextVar[str | None] = ContextVar(
-    "openai_responses_user_agent_override", default=None
+# Override headers used by the Responses API.
+_HEADERS_OVERRIDE: ContextVar[dict[str, str] | None] = ContextVar(
+    "openai_responses_headers_override", default=None
 )
 
 
@@ -334,11 +334,11 @@ class OpenAIResponsesModel(Model):
         return self._client
 
     def _merge_headers(self, model_settings: ModelSettings):
-        merged = {**_HEADERS, **(model_settings.extra_headers or {})}
-        ua_ctx = _USER_AGENT_OVERRIDE.get()
-        if ua_ctx is not None:
-            merged["User-Agent"] = ua_ctx
-        return merged
+        return {
+            **_HEADERS,
+            **(model_settings.extra_headers or {}),
+            **(_HEADERS_OVERRIDE.get() or {}),
+        }
 
 
 @dataclass

agents/realtime/session.py

@@ -408,6 +408,7 @@ class RealtimeSession(RealtimeModelListener):
                 usage=self._context_wrapper.usage,
                 tool_name=event.name,
                 tool_call_id=event.call_id,
+                tool_arguments=event.arguments,
             )
             result = await func_tool.on_invoke_tool(tool_context, event.arguments)
 
@@ -432,6 +433,7 @@ class RealtimeSession(RealtimeModelListener):
                 usage=self._context_wrapper.usage,
                 tool_name=event.name,
                 tool_call_id=event.call_id,
+                tool_arguments=event.arguments,
             )
 
             # Execute the handoff to get the new agent

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."""