openai-agents 0.4.2__py3-none-any.whl → 0.5.0__py3-none-any.whl

agents/extensions/memory/__init__.py

@@ -11,10 +11,13 @@ from __future__ import annotations
 from typing import Any
 
 __all__: list[str] = [
+    "AdvancedSQLiteSession",
+    "DAPR_CONSISTENCY_EVENTUAL",
+    "DAPR_CONSISTENCY_STRONG",
+    "DaprSession",
     "EncryptedSession",
     "RedisSession",
     "SQLAlchemySession",
-    "AdvancedSQLiteSession",
 ]
 
 
@@ -60,4 +63,37 @@ def __getattr__(name: str) -> Any:
         except ModuleNotFoundError as e:
             raise ImportError(f"Failed to import AdvancedSQLiteSession: {e}") from e
 
+    if name == "DaprSession":
+        try:
+            from .dapr_session import DaprSession  # noqa: F401
+
+            return DaprSession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DaprSession requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
+    if name == "DAPR_CONSISTENCY_EVENTUAL":
+        try:
+            from .dapr_session import DAPR_CONSISTENCY_EVENTUAL  # noqa: F401
+
+            return DAPR_CONSISTENCY_EVENTUAL
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DAPR_CONSISTENCY_EVENTUAL requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
+    if name == "DAPR_CONSISTENCY_STRONG":
+        try:
+            from .dapr_session import DAPR_CONSISTENCY_STRONG  # noqa: F401
+
+            return DAPR_CONSISTENCY_STRONG
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DAPR_CONSISTENCY_STRONG requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
     raise AttributeError(f"module {__name__} has no attribute {name}")

agents/extensions/memory/dapr_session.py

@@ -0,0 +1,423 @@
+"""Dapr State Store-powered Session backend.
+
+Usage::
+
+    from agents.extensions.memory import DaprSession
+
+    # Create from Dapr sidecar address
+    session = DaprSession.from_address(
+        session_id="user-123",
+        state_store_name="statestore",
+        dapr_address="localhost:50001",
+    )
+
+    # Or pass an existing Dapr client that your application already manages
+    session = DaprSession(
+        session_id="user-123",
+        state_store_name="statestore",
+        dapr_client=my_dapr_client,
+    )
+
+    await Runner.run(agent, "Hello", session=session)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import time
+from typing import Any, Final, Literal
+
+try:
+    from dapr.aio.clients import DaprClient
+    from dapr.clients.grpc._state import Concurrency, Consistency, StateOptions
+except ImportError as e:
+    raise ImportError(
+        "DaprSession requires the 'dapr' package. Install it with: pip install dapr"
+    ) from e
+
+from ...items import TResponseInputItem
+from ...logger import logger
+from ...memory.session import SessionABC
+
+# Type alias for consistency levels
+ConsistencyLevel = Literal["eventual", "strong"]
+
+# Consistency level constants
+DAPR_CONSISTENCY_EVENTUAL: ConsistencyLevel = "eventual"
+DAPR_CONSISTENCY_STRONG: ConsistencyLevel = "strong"
+
+_MAX_WRITE_ATTEMPTS: Final[int] = 5
+_RETRY_BASE_DELAY_SECONDS: Final[float] = 0.05
+_RETRY_MAX_DELAY_SECONDS: Final[float] = 1.0
+
+
+class DaprSession(SessionABC):
+    """Dapr State Store implementation of :pyclass:`agents.memory.session.Session`."""
+
+    def __init__(
+        self,
+        session_id: str,
+        *,
+        state_store_name: str,
+        dapr_client: DaprClient,
+        ttl: int | None = None,
+        consistency: ConsistencyLevel = DAPR_CONSISTENCY_EVENTUAL,
+    ):
+        """Initializes a new DaprSession.
+
+        Args:
+            session_id (str): Unique identifier for the conversation.
+            state_store_name (str): Name of the Dapr state store component.
+            dapr_client (DaprClient): A pre-configured Dapr client.
+            ttl (int | None, optional): Time-to-live in seconds for session data.
+                If None, data persists indefinitely. Note that TTL support depends on
+                the underlying state store implementation. Defaults to None.
+            consistency (ConsistencyLevel, optional): Consistency level for state operations.
+                Use DAPR_CONSISTENCY_EVENTUAL or DAPR_CONSISTENCY_STRONG constants.
+                Defaults to DAPR_CONSISTENCY_EVENTUAL.
+        """
+        self.session_id = session_id
+        self._dapr_client = dapr_client
+        self._state_store_name = state_store_name
+        self._ttl = ttl
+        self._consistency = consistency
+        self._lock = asyncio.Lock()
+        self._owns_client = False  # Track if we own the Dapr client
+
+        # State keys
+        self._messages_key = f"{self.session_id}:messages"
+        self._metadata_key = f"{self.session_id}:metadata"
+
+    @classmethod
+    def from_address(
+        cls,
+        session_id: str,
+        *,
+        state_store_name: str,
+        dapr_address: str = "localhost:50001",
+        **kwargs: Any,
+    ) -> DaprSession:
+        """Create a session from a Dapr sidecar address.
+
+        Args:
+            session_id (str): Conversation ID.
+            state_store_name (str): Name of the Dapr state store component.
+            dapr_address (str): Dapr sidecar gRPC address. Defaults to "localhost:50001".
+            **kwargs: Additional keyword arguments forwarded to the main constructor
+                (e.g., ttl, consistency).
+
+        Returns:
+            DaprSession: An instance of DaprSession connected to the specified Dapr sidecar.
+
+        Note:
+            The Dapr Python SDK performs health checks on the HTTP endpoint (default: http://localhost:3500).
+            Ensure the Dapr sidecar is started with --dapr-http-port 3500. Alternatively, set one of
+            these environment variables: DAPR_HTTP_ENDPOINT (e.g., "http://localhost:3500") or
+            DAPR_HTTP_PORT (e.g., "3500") to avoid connection errors.
+        """
+        dapr_client = DaprClient(address=dapr_address)
+        session = cls(
+            session_id, state_store_name=state_store_name, dapr_client=dapr_client, **kwargs
+        )
+        session._owns_client = True  # We created the client, so we own it
+        return session
+
+    def _get_read_metadata(self) -> dict[str, str]:
+        """Get metadata for read operations including consistency.
+
+        The consistency level is passed through state_metadata as per Dapr's state API.
+        """
+        metadata: dict[str, str] = {}
+        # Add consistency level to metadata for read operations
+        if self._consistency:
+            metadata["consistency"] = self._consistency
+        return metadata
+
+    def _get_state_options(self, *, concurrency: Concurrency | None = None) -> StateOptions | None:
+        """Get StateOptions configured with consistency and optional concurrency."""
+        options_kwargs: dict[str, Any] = {}
+        if self._consistency == DAPR_CONSISTENCY_STRONG:
+            options_kwargs["consistency"] = Consistency.strong
+        elif self._consistency == DAPR_CONSISTENCY_EVENTUAL:
+            options_kwargs["consistency"] = Consistency.eventual
+        if concurrency is not None:
+            options_kwargs["concurrency"] = concurrency
+        if options_kwargs:
+            return StateOptions(**options_kwargs)
+        return None
+
+    def _get_metadata(self) -> dict[str, str]:
+        """Get metadata for state operations including TTL if configured."""
+        metadata = {}
+        if self._ttl is not None:
+            metadata["ttlInSeconds"] = str(self._ttl)
+        return metadata
+
+    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]
+
+    def _decode_messages(self, data: bytes | None) -> list[Any]:
+        if not data:
+            return []
+        try:
+            messages_json = data.decode("utf-8")
+            messages = json.loads(messages_json)
+            if isinstance(messages, list):
+                return list(messages)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return []
+        return []
+
+    def _calculate_retry_delay(self, attempt: int) -> float:
+        base: float = _RETRY_BASE_DELAY_SECONDS * (2 ** max(0, attempt - 1))
+        delay: float = min(base, _RETRY_MAX_DELAY_SECONDS)
+        # Add jitter (10%) similar to tracing processors to avoid thundering herd.
+        return delay + random.uniform(0, 0.1 * delay)
+
+    def _is_concurrency_conflict(self, error: Exception) -> bool:
+        code_attr = getattr(error, "code", None)
+        if callable(code_attr):
+            try:
+                status_code = code_attr()
+            except Exception:
+                status_code = None
+            if status_code is not None:
+                status_name = getattr(status_code, "name", str(status_code))
+                if status_name in {"ABORTED", "FAILED_PRECONDITION"}:
+                    return True
+        message = str(error).lower()
+        conflict_markers = (
+            "etag mismatch",
+            "etag does not match",
+            "precondition failed",
+            "concurrency conflict",
+            "invalid etag",
+            "failed to set key",  # Redis state store Lua script error during conditional write
+            "user_script",  # Redis script failure hint
+        )
+        return any(marker in message for marker in conflict_markers)
+
+    async def _handle_concurrency_conflict(self, error: Exception, attempt: int) -> bool:
+        if not self._is_concurrency_conflict(error):
+            return False
+        if attempt >= _MAX_WRITE_ATTEMPTS:
+            return False
+        delay = self._calculate_retry_delay(attempt)
+        if delay > 0:
+            await asyncio.sleep(delay)
+        return True
+
+    # ------------------------------------------------------------------
+    # 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:
+            # Get messages from state store with consistency level
+            response = await self._dapr_client.get_state(
+                store_name=self._state_store_name,
+                key=self._messages_key,
+                state_metadata=self._get_read_metadata(),
+            )
+
+            messages = self._decode_messages(response.data)
+            if not messages:
+                return []
+            if limit is not None:
+                if limit <= 0:
+                    return []
+                messages = messages[-limit:]
+            items: list[TResponseInputItem] = []
+            for msg in messages:
+                try:
+                    if isinstance(msg, str):
+                        item = await self._deserialize_item(msg)
+                    else:
+                        item = msg
+                    items.append(item)
+                except (json.JSONDecodeError, TypeError):
+                    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:
+            serialized_items: list[str] = [await self._serialize_item(item) for item in items]
+            attempt = 0
+            while True:
+                attempt += 1
+                response = await self._dapr_client.get_state(
+                    store_name=self._state_store_name,
+                    key=self._messages_key,
+                    state_metadata=self._get_read_metadata(),
+                )
+                existing_messages = self._decode_messages(response.data)
+                updated_messages = existing_messages + serialized_items
+                messages_json = json.dumps(updated_messages, separators=(",", ":"))
+                etag = response.etag
+                try:
+                    await self._dapr_client.save_state(
+                        store_name=self._state_store_name,
+                        key=self._messages_key,
+                        value=messages_json,
+                        etag=etag,
+                        state_metadata=self._get_metadata(),
+                        options=self._get_state_options(concurrency=Concurrency.first_write),
+                    )
+                    break
+                except Exception as error:
+                    should_retry = await self._handle_concurrency_conflict(error, attempt)
+                    if should_retry:
+                        continue
+                    raise
+
+            # Update metadata
+            metadata = {
+                "session_id": self.session_id,
+                "created_at": str(int(time.time())),
+                "updated_at": str(int(time.time())),
+            }
+            await self._dapr_client.save_state(
+                store_name=self._state_store_name,
+                key=self._metadata_key,
+                value=json.dumps(metadata),
+                state_metadata=self._get_metadata(),
+                options=self._get_state_options(),
+            )
+
+    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:
+            attempt = 0
+            while True:
+                attempt += 1
+                response = await self._dapr_client.get_state(
+                    store_name=self._state_store_name,
+                    key=self._messages_key,
+                    state_metadata=self._get_read_metadata(),
+                )
+                messages = self._decode_messages(response.data)
+                if not messages:
+                    return None
+                last_item = messages.pop()
+                messages_json = json.dumps(messages, separators=(",", ":"))
+                etag = getattr(response, "etag", None) or None
+                etag = getattr(response, "etag", None) or None
+                try:
+                    await self._dapr_client.save_state(
+                        store_name=self._state_store_name,
+                        key=self._messages_key,
+                        value=messages_json,
+                        etag=etag,
+                        state_metadata=self._get_metadata(),
+                        options=self._get_state_options(concurrency=Concurrency.first_write),
+                    )
+                    break
+                except Exception as error:
+                    should_retry = await self._handle_concurrency_conflict(error, attempt)
+                    if should_retry:
+                        continue
+                    raise
+            try:
+                if isinstance(last_item, str):
+                    return await self._deserialize_item(last_item)
+                return last_item  # type: ignore[no-any-return]
+            except (json.JSONDecodeError, TypeError):
+                return None
+
+    async def clear_session(self) -> None:
+        """Clear all items for this session."""
+        async with self._lock:
+            # Delete messages and metadata keys
+            await self._dapr_client.delete_state(
+                store_name=self._state_store_name,
+                key=self._messages_key,
+                options=self._get_state_options(),
+            )
+
+            await self._dapr_client.delete_state(
+                store_name=self._state_store_name,
+                key=self._metadata_key,
+                options=self._get_state_options(),
+            )
+
+    async def close(self) -> None:
+        """Close the Dapr client connection.
+
+        Only closes the connection if this session owns the Dapr client
+        (i.e., created via from_address). If the client was injected externally,
+        the caller is responsible for managing its lifecycle.
+        """
+        if self._owns_client:
+            await self._dapr_client.close()
+
+    async def __aenter__(self) -> DaprSession:
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit async context manager and close the connection."""
+        await self.close()
+
+    async def ping(self) -> bool:
+        """Test Dapr connectivity by checking metadata.
+
+        Returns:
+            True if Dapr is reachable, False otherwise.
+        """
+        try:
+            # First attempt a read; some stores may not be initialized yet.
+            await self._dapr_client.get_state(
+                store_name=self._state_store_name,
+                key="__ping__",
+                state_metadata=self._get_read_metadata(),
+            )
+            return True
+        except Exception as initial_error:
+            # If relation/table is missing or store isn't initialized,
+            # attempt a write to initialize it, then read again.
+            try:
+                await self._dapr_client.save_state(
+                    store_name=self._state_store_name,
+                    key="__ping__",
+                    value="ok",
+                    state_metadata=self._get_metadata(),
+                    options=self._get_state_options(),
+                )
+                # Read again after write.
+                await self._dapr_client.get_state(
+                    store_name=self._state_store_name,
+                    key="__ping__",
+                    state_metadata=self._get_read_metadata(),
+                )
+                return True
+            except Exception:
+                logger.error("Dapr connection failed: %s", initial_error)
+                return False

agents/lifecycle.py

@@ -62,7 +62,7 @@ class RunHooksBase(Generic[TContext, TAgent]):
         agent: TAgent,
         tool: Tool,
     ) -> None:
-        """Called concurrently with tool invocation."""
+        """Called immediately before a local tool is invoked."""
         pass
 
     async def on_tool_end(
@@ -72,7 +72,7 @@ class RunHooksBase(Generic[TContext, TAgent]):
         tool: Tool,
         result: str,
     ) -> None:
-        """Called after a tool is invoked."""
+        """Called immediately after a local tool is invoked."""
         pass
 
 
@@ -113,7 +113,7 @@ class AgentHooksBase(Generic[TContext, TAgent]):
         agent: TAgent,
         tool: Tool,
     ) -> None:
-        """Called concurrently with tool invocation."""
+        """Called immediately before a local tool is invoked."""
         pass
 
     async def on_tool_end(
@@ -123,7 +123,7 @@ class AgentHooksBase(Generic[TContext, TAgent]):
         tool: Tool,
         result: str,
     ) -> None:
-        """Called after a tool is invoked."""
+        """Called immediately after a local tool is invoked."""
         pass
 
     async def on_llm_start(

agents/models/chatcmpl_converter.py

@@ -51,6 +51,8 @@ from ..model_settings import MCPToolChoice
 from ..tool import FunctionTool, Tool
 from .fake_id import FAKE_RESPONSES_ID
 
+ResponseInputContentWithAudioParam = Union[ResponseInputContentParam, ResponseInputAudioParam]
+
 
 class Converter:
     @classmethod
@@ -136,7 +138,9 @@ class Converter:
         )
         if message.content:
             message_item.content.append(
-                ResponseOutputText(text=message.content, type="output_text", annotations=[])
+                ResponseOutputText(
+                    text=message.content, type="output_text", annotations=[], logprobs=[]
+                )
             )
         if message.refusal:
             message_item.content.append(
@@ -246,7 +250,7 @@ class Converter:
 
     @classmethod
     def extract_text_content(
-        cls, content: str | Iterable[ResponseInputContentParam]
+        cls, content: str | Iterable[ResponseInputContentWithAudioParam]
     ) -> str | list[ChatCompletionContentPartTextParam]:
         all_content = cls.extract_all_content(content)
         if isinstance(all_content, str):
@@ -259,7 +263,7 @@ class Converter:
 
     @classmethod
     def extract_all_content(
-        cls, content: str | Iterable[ResponseInputContentParam]
+        cls, content: str | Iterable[ResponseInputContentWithAudioParam]
     ) -> str | list[ChatCompletionContentPartParam]:
         if isinstance(content, str):
             return content
@@ -535,7 +539,7 @@ class Converter:
             elif func_output := cls.maybe_function_tool_call_output(item):
                 flush_assistant_message()
                 output_content = cast(
-                    Union[str, Iterable[ResponseInputContentParam]], func_output["output"]
+                    Union[str, Iterable[ResponseInputContentWithAudioParam]], func_output["output"]
                 )
                 msg: ChatCompletionToolMessageParam = {
                     "role": "tool",

agents/models/chatcmpl_stream_handler.py

@@ -231,6 +231,7 @@ class ChatCmplStreamHandler:
                             text="",
                             type="output_text",
                             annotations=[],
+                            logprobs=[],
                         ),
                     )
                     # Start a new assistant message stream
@@ -258,6 +259,7 @@ class ChatCmplStreamHandler:
                             text="",
                             type="output_text",
                             annotations=[],
+                            logprobs=[],
                         ),
                         type="response.content_part.added",
                         sequence_number=sequence_number.get_and_increment(),
@@ -309,12 +311,10 @@ class ChatCmplStreamHandler:
                     yield ResponseContentPartAddedEvent(
                         content_index=state.refusal_content_index_and_output[0],
                         item_id=FAKE_RESPONSES_ID,
-                        output_index=state.reasoning_content_index_and_output
-                        is not None,  # fixed 0 -> 0 or 1
-                        part=ResponseOutputText(
-                            text="",
-                            type="output_text",
-                            annotations=[],
+                        output_index=(1 if state.reasoning_content_index_and_output else 0),
+                        part=ResponseOutputRefusal(
+                            refusal="",
+                            type="refusal",
                         ),
                         type="response.content_part.added",
                         sequence_number=sequence_number.get_and_increment(),

agents/realtime/events.py

@@ -69,6 +69,10 @@ class RealtimeToolStart:
     """The agent that updated."""
 
     tool: Tool
+    """The tool being called."""
+
+    arguments: str
+    """The arguments passed to the tool as a JSON string."""
 
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
@@ -86,6 +90,9 @@ class RealtimeToolEnd:
     tool: Tool
     """The tool that was called."""
 
+    arguments: str
+    """The arguments passed to the tool as a JSON string."""
+
     output: Any
     """The output of the tool call."""
 

agents/realtime/model.py

@@ -139,6 +139,13 @@ class RealtimeModelConfig(TypedDict):
     is played to the user.
     """
 
+    call_id: NotRequired[str]
+    """Attach to an existing realtime call instead of creating a new session.
+
+    When provided, the transport connects using the `call_id` query string parameter rather than a
+    model name. This is used for SIP-originated calls that are accepted via the Realtime Calls API.
+    """
+
 
 class RealtimeModel(abc.ABC):
     """Interface for connecting to a realtime model and sending/receiving events."""

agents/realtime/openai_realtime.py

@@ -208,7 +208,18 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
         self._playback_tracker = options.get("playback_tracker", None)
 
-        self.model = model_settings.get("model_name", self.model)
+        call_id = options.get("call_id")
+        model_name = model_settings.get("model_name")
+        if call_id and model_name:
+            error_message = (
+                "Cannot specify both `call_id` and `model_name` "
+                "when attaching to an existing realtime call."
+            )
+            raise UserError(error_message)
+
+        if model_name:
+            self.model = model_name
+
         api_key = await get_api_key(options.get("api_key"))
 
         if "tracing" in model_settings:
@@ -216,7 +227,10 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         else:
             self._tracing_config = "auto"
 
-        url = options.get("url", f"wss://api.openai.com/v1/realtime?model={self.model}")
+        if call_id:
+            url = options.get("url", f"wss://api.openai.com/v1/realtime?call_id={call_id}")
+        else:
+            url = options.get("url", f"wss://api.openai.com/v1/realtime?model={self.model}")
 
         headers: dict[str, str] = {}
         if options.get("headers") is not None:
@@ -629,8 +643,9 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                 )
                 if not automatic_response_cancellation_enabled:
                     await self._cancel_response()
-            # Avoid sending conversation.item.truncate here; when GA is set to
-            # interrupt on VAD start, the server will handle truncation.
+            # Avoid sending conversation.item.truncate here. When the session's
+            # turn_detection.interrupt_response is enabled (GA default), the server emits
+            # conversation.item.truncated after the VAD start and takes care of history updates.
         elif parsed.type == "response.created":
             self._ongoing_response = True
             await self._emit_event(RealtimeModelTurnStartedEvent())
@@ -929,6 +944,18 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         return converted_tools
 
 
+class OpenAIRealtimeSIPModel(OpenAIRealtimeWebSocketModel):
+    """Realtime model that attaches to SIP-originated calls using a call ID."""
+
+    async def connect(self, options: RealtimeModelConfig) -> None:
+        call_id = options.get("call_id")
+        if not call_id:
+            raise UserError("OpenAIRealtimeSIPModel requires `call_id` in the model configuration.")
+
+        sip_options = options.copy()
+        await super().connect(sip_options)
+
+
 class _ConversionHelper:
     @classmethod
     def conversation_item_to_realtime_message_item(

agents/realtime/session.py

@@ -411,6 +411,7 @@ class RealtimeSession(RealtimeModelListener):
                     info=self._event_info,
                     tool=function_map[event.name],
                     agent=agent,
+                    arguments=event.arguments,
                 )
             )
 
@@ -436,6 +437,7 @@ class RealtimeSession(RealtimeModelListener):
                     tool=func_tool,
                     output=result,
                     agent=agent,
+                    arguments=event.arguments,
                 )
             )
         elif event.name in handoff_map:

agents/run.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import inspect
 import os
+import warnings
 from dataclasses import dataclass, field
 from typing import Any, Callable, Generic, cast, get_args
 
@@ -720,7 +722,40 @@ class AgentRunner:
         conversation_id = kwargs.get("conversation_id")
         session = kwargs.get("session")
 
-        return asyncio.get_event_loop().run_until_complete(
+        # Python 3.14 stopped implicitly wiring up a default event loop
+        # when synchronous code touches asyncio APIs for the first time.
+        # Several of our synchronous entry points (for example the Redis/SQLAlchemy session helpers)
+        # construct asyncio primitives like asyncio.Lock during __init__,
+        # which binds them to whatever loop happens to be the thread's default at that moment.
+        # To keep those locks usable we must ensure that run_sync reuses that same default loop
+        # instead of hopping over to a brand-new asyncio.run() loop.
+        try:
+            already_running_loop = asyncio.get_running_loop()
+        except RuntimeError:
+            already_running_loop = None
+
+        if already_running_loop is not None:
+            # This method is only expected to run when no loop is already active.
+            # (Each thread has its own default loop; concurrent sync runs should happen on
+            # different threads. In a single thread use the async API to interleave work.)
+            raise RuntimeError(
+                "AgentRunner.run_sync() cannot be called when an event loop is already running."
+            )
+
+        policy = asyncio.get_event_loop_policy()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            try:
+                default_loop = policy.get_event_loop()
+            except RuntimeError:
+                default_loop = policy.new_event_loop()
+                policy.set_event_loop(default_loop)
+
+        # We intentionally leave the default loop open even if we had to create one above. Session
+        # instances and other helpers stash loop-bound primitives between calls and expect to find
+        # the same default loop every time run_sync is invoked on this thread.
+        # Schedule the async run on the default loop so that we can manage cancellation explicitly.
+        task = default_loop.create_task(
             self.run(
                 starting_agent,
                 input,
@@ -734,6 +769,24 @@ class AgentRunner:
             )
         )
 
+        try:
+            # Drive the coroutine to completion, harvesting the final RunResult.
+            return default_loop.run_until_complete(task)
+        except BaseException:
+            # If the sync caller aborts (KeyboardInterrupt, etc.), make sure the scheduled task
+            # does not linger on the shared loop by cancelling it and waiting for completion.
+            if not task.done():
+                task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    default_loop.run_until_complete(task)
+            raise
+        finally:
+            if not default_loop.is_closed():
+                # The loop stays open for subsequent runs, but we still need to flush any pending
+                # async generators so their cleanup code executes promptly.
+                with contextlib.suppress(RuntimeError):
+                    default_loop.run_until_complete(default_loop.shutdown_asyncgens())
+
     def run_streamed(
         self,
         starting_agent: Agent[TContext],

agents/usage.py

@@ -4,6 +4,26 @@ from openai.types.responses.response_usage import InputTokensDetails, OutputToke
 from pydantic.dataclasses import dataclass
 
 
+@dataclass
+class RequestUsage:
+    """Usage details for a single API request."""
+
+    input_tokens: int
+    """Input tokens for this individual request."""
+
+    output_tokens: int
+    """Output tokens for this individual request."""
+
+    total_tokens: int
+    """Total tokens (input + output) for this individual request."""
+
+    input_tokens_details: InputTokensDetails
+    """Details about the input tokens for this individual request."""
+
+    output_tokens_details: OutputTokensDetails
+    """Details about the output tokens for this individual request."""
+
+
 @dataclass
 class Usage:
     requests: int = 0
@@ -27,7 +47,37 @@ class Usage:
     total_tokens: int = 0
     """Total tokens sent and received, across all requests."""
 
+    request_usage_entries: list[RequestUsage] = field(default_factory=list)
+    """List of RequestUsage entries for accurate per-request cost calculation.
+
+    Each call to `add()` automatically creates an entry in this list if the added usage
+    represents a new request (i.e., has non-zero tokens).
+
+    Example:
+        For a run that makes 3 API calls with 100K, 150K, and 80K input tokens each,
+        the aggregated `input_tokens` would be 330K, but `request_usage_entries` would
+        preserve the [100K, 150K, 80K] breakdown, which could be helpful for detailed
+        cost calculation or context window management.
+    """
+
+    def __post_init__(self) -> None:
+        # Some providers don't populate optional token detail fields
+        # (cached_tokens, reasoning_tokens), and the OpenAI SDK's generated
+        # code can bypass Pydantic validation (e.g., via model_construct),
+        # allowing None values. We normalize these to 0 to prevent TypeErrors.
+        if self.input_tokens_details.cached_tokens is None:
+            self.input_tokens_details = InputTokensDetails(cached_tokens=0)
+        if self.output_tokens_details.reasoning_tokens is None:
+            self.output_tokens_details = OutputTokensDetails(reasoning_tokens=0)
+
     def add(self, other: "Usage") -> None:
+        """Add another Usage object to this one, aggregating all fields.
+
+        This method automatically preserves request_usage_entries.
+
+        Args:
+            other: The Usage object to add to this one.
+        """
         self.requests += other.requests if other.requests else 0
         self.input_tokens += other.input_tokens if other.input_tokens else 0
         self.output_tokens += other.output_tokens if other.output_tokens else 0
@@ -41,3 +91,18 @@ class Usage:
             reasoning_tokens=self.output_tokens_details.reasoning_tokens
             + other.output_tokens_details.reasoning_tokens
         )
+
+        # Automatically preserve request_usage_entries.
+        # If the other Usage represents a single request with tokens, record it.
+        if other.requests == 1 and other.total_tokens > 0:
+            request_usage = RequestUsage(
+                input_tokens=other.input_tokens,
+                output_tokens=other.output_tokens,
+                total_tokens=other.total_tokens,
+                input_tokens_details=other.input_tokens_details,
+                output_tokens_details=other.output_tokens_details,
+            )
+            self.request_usage_entries.append(request_usage)
+        elif other.request_usage_entries:
+            # If the other Usage already has individual request breakdowns, merge them.
+            self.request_usage_entries.extend(other.request_usage_entries)

{openai_agents-0.4.2.dist-info → openai_agents-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.4.2
+Version: 0.5.0
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -16,16 +16,20 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Requires-Dist: griffe<2,>=1.5.6
 Requires-Dist: mcp<2,>=1.11.0; python_version >= '3.10'
-Requires-Dist: openai<3,>=2.2
-Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: openai<3,>=2.7.1
+Requires-Dist: pydantic<3,>=2.12.3
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0
 Requires-Dist: typing-extensions<5,>=4.12.2
+Provides-Extra: dapr
+Requires-Dist: dapr>=1.16.0; extra == 'dapr'
+Requires-Dist: grpcio>=1.60.0; extra == 'dapr'
 Provides-Extra: encrypt
 Requires-Dist: cryptography<46,>=45.0; extra == 'encrypt'
 Provides-Extra: litellm
@@ -352,6 +356,12 @@ make lint   # run linter
 make format-check # run style checker
 ```
 
+Format code if `make format-check` fails above by running:
+
+```
+make format
+```
+
 ## Acknowledgements
 
 We'd like to acknowledge the excellent work of the open-source community, especially:

{openai_agents-0.4.2.dist-info → openai_agents-0.5.0.dist-info}/RECORD

@@ -10,28 +10,29 @@ agents/function_schema.py,sha256=njtbLt44DOkIU0a0U8TeDNEx-iQZU8oohwy3k7-k4A8,148
 agents/guardrail.py,sha256=7P-kd9rKPhgB8rtI31MCV5ho4ZrEaNCQxHvE8IK3EOk,9582
 agents/handoffs.py,sha256=kDTM3nj3E_0khiJPMJAIN00gektMTRNbaYSbc5ZCnBM,11411
 agents/items.py,sha256=YoAhxwb2PSgClGGWrkTIWufAxg0F1cS1KohLYonwz6I,14370
-agents/lifecycle.py,sha256=hGsqzumOSaal6oAjTqTfvBXl-ShAOkC42sthJigB5Fg,4308
+agents/lifecycle.py,sha256=2dhFi8CBH-EHDiAnj-_h1UmZ2ayC8Tmv5K61P-Kem9w,4362
 agents/logger.py,sha256=p_ef7vWKpBev5FFybPJjhrCCQizK08Yy1A2EDO1SNNg,60
 agents/model_settings.py,sha256=7Ul-Xg-aNVXIbK6V4Rm2t5EEfNR0tsy_A9ac_wFqLLk,6828
 agents/prompts.py,sha256=Ss5y_7s2HFcRAOAKu4WTxQszs5ybI8TfbxgEYdnj9sg,2231
 agents/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 agents/repl.py,sha256=NX0BE5YDnmGQ2rdQsmLm3CKkQZ5m4GC95xXmUsAXJVs,2539
 agents/result.py,sha256=FW3-fsYOIJrn7pjiDjWPHN58pPpYfNoFNTympFV_96k,13963
-agents/run.py,sha256=I3KwURXqqQwDYF3gCN9KmpIpxakJhwIj6NnYvxvvd5I,74925
+agents/run.py,sha256=g4Z8I28pKaefbMxB0rNVqT4JBbLqHNYSH8_W1WHHmmM,77816
 agents/run_context.py,sha256=vuSUQM8O4CLensQY27-22fOqECnw7yvwL9U3WO8b_bk,851
 agents/stream_events.py,sha256=vW7O5T6iwFuRFvds1Bq3zMB60fRCz7lWryMkHSL-bAo,1733
 agents/strict_schema.py,sha256=HFm4j753-UKDfJ0zSiQYf5V1qGuHY6TRm2zzwI0f0E0,6382
 agents/tool.py,sha256=yNCqv4gu1g0Gxrt9YPYdSkZaWlO3d84vlEwxOegVRng,20304
 agents/tool_context.py,sha256=g53mgaeX7kCwPaIReiwuUejD8qC7QejMS-F3Wnkuhhg,1866
 agents/tool_guardrails.py,sha256=2uXEr_R5AWy9NHtBjd7G7upc3uZSuoP86Hfsc-qTadM,8344
-agents/usage.py,sha256=Tb5udGd3DPgD0JBdRD8fDctTE4M-zKML5uRn8ZG1yBc,1675
+agents/usage.py,sha256=azQmy1Oyx0vk6dpq-gSAFPvP5L54zIM2CwbJbozTOR0,4517
 agents/version.py,sha256=_1knUwzSK-HUeZTpRUkk6Z-CIcurqXuEplbV5TLJ08E,230
 agents/extensions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 agents/extensions/handoff_filters.py,sha256=CS-k7TGCtT8TW3GeXb04OoFBXKdjg8-85QXswWAYBmI,2095
 agents/extensions/handoff_prompt.py,sha256=oGWN0uNh3Z1L7E-Ev2up8W084fFrDNOsLDy7P6bcmic,1006
 agents/extensions/visualization.py,sha256=sf9D_C-HMwkbWdZccTZvvMPRy_NSiwbm48tRJlESQBI,5144
-agents/extensions/memory/__init__.py,sha256=jhx0pa1TVRFooiI0ERRhklkaeiZ-NDGA_b9tJXp3VfM,2201
+agents/extensions/memory/__init__.py,sha256=ckEgIcbSh7ptmJzoHtVI7YeC6TjI3IkxrYKG-NQApBA,3498
 agents/extensions/memory/advanced_sqlite_session.py,sha256=rCrXM878foAuBN-rN2fibP2GHs-1hTtRx-TQcDKIfGI,52883
+agents/extensions/memory/dapr_session.py,sha256=AZ2fOsHLqDIcS8Ash9jRYRsqB7lpcV1zJLeIMNVe41I,16663
 agents/extensions/memory/encrypt_session.py,sha256=PVnZIEj50bjUq16OLnMKrbZiinLkrVpamPPEw8RnUCA,6485
 agents/extensions/memory/redis_session.py,sha256=JwXY6zUTMgq9bRezlyFZ4Tze7DO7T0hioTc23qjSHjU,9838
 agents/extensions/memory/sqlalchemy_session.py,sha256=fnlZkNF_XZekP44uhiR4rjlCkwG7JJEiFm35TJfiCtc,12325
@@ -48,9 +49,9 @@ agents/memory/sqlite_session.py,sha256=6HGzSL70mQgutITIPZUC2x2Qtj6U4hXiZTceu3Da7
 agents/memory/util.py,sha256=ZAHOrNVA36xICFzuNgHgEA1_s_oEMO6Wsu6-EecY8JU,586
 agents/models/__init__.py,sha256=E0XVqWayVAsFqxucDLBW30siaqfNQsVrAnfidG_C3ok,287
 agents/models/_openai_shared.py,sha256=4Ngwo2Fv2RXY61Pqck1cYPkSln2tDnb8Ai-ao4QG-iE,836
-agents/models/chatcmpl_converter.py,sha256=qEobLnIJjrK6WRi_tsVkrDrGq78EGro3MZXlVMpMK2c,26011
+agents/models/chatcmpl_converter.py,sha256=cwc2JSQpsYzzc_Pk-j_wcQWArWnHWOHglE5N_vdPv5Y,26185
 agents/models/chatcmpl_helpers.py,sha256=YC2krp_-uBgRCrCEImLjNvONTWRWfwLlPKHI4kBmNXE,1483
-agents/models/chatcmpl_stream_handler.py,sha256=1h0esxmnlBk9NwDjjwSlWYzjzuMgIpMLtRU9kaszfyg,29212
+agents/models/chatcmpl_stream_handler.py,sha256=_ZlFgwoiBOHMHbN-WN3hN5lTIEy04M3uoWctDb4H4VM,29209
 agents/models/default_models.py,sha256=mlvBePn8H4UkHo7lN-wh7A3k2ciLgBUFKpROQxzdTfs,2098
 agents/models/fake_id.py,sha256=lbXjUUSMeAQ8eFx4V5QLUnBClHE6adJlYYav55RlG5w,268
 agents/models/interface.py,sha256=-AFUHC8iRuGZmtQwguDw4s-M4OPL2y2mct4TAmWvVrU,4057
@@ -65,15 +66,15 @@ agents/realtime/_util.py,sha256=ehBzUN1RTD2m2TXq73Jm4WohQzJ6y_MfnF5MaK8uu14,341
 agents/realtime/agent.py,sha256=bkegBJ_lc3z3NtnlIyEkVZFxZWBJwVjsQVzpQZAu7PM,4283
 agents/realtime/audio_formats.py,sha256=DBUWVVff4XY5BT6Mol86tF4PFMp5OIS3LmAbqUmQn_k,1019
 agents/realtime/config.py,sha256=vnjgkeZXcOSLFopoAiGj4Vki_75pEJIKTagJtQpCWmg,7072
-agents/realtime/events.py,sha256=eANiNNyYlp_1Ybdl-MOwXRVTDtrK9hfgn6iw0xNxnaY,5889
+agents/realtime/events.py,sha256=BkktfS4cCpz53Fn6Di-8kgRXlxzE9NvzqJFevDVE3uc,6084
 agents/realtime/handoffs.py,sha256=iJ4lr5RVdDkw5W3_AOGB_Az-hlRt1CoFFFNFDfd3ues,6698
 agents/realtime/items.py,sha256=5EG768FkKpbk-dhe4b_7BfFpdUEFWtxoiVUtNI9KXsc,5517
-agents/realtime/model.py,sha256=Lnb9pEcvnlIdXJUcldVyioaX5lpmrBou5FZoNJe4XfA,6457
+agents/realtime/model.py,sha256=jVZBhPRc2yDQfAFn2pqnnVNtkgsguKS8qO-KbQCtuEs,6774
 agents/realtime/model_events.py,sha256=2NKofzLszKHwtlcsogsNnH6hdeFfO7S96yWDB4AlxB8,4340
 agents/realtime/model_inputs.py,sha256=-pl8Oj0WVrA5Gt-dqP5Va3ZHqXyIXpsjMsf9UL-suEY,2789
-agents/realtime/openai_realtime.py,sha256=jN3OvcEQt9X-59t6InllkOOEd8Tdw69K5vuKfXBeObg,44763
+agents/realtime/openai_realtime.py,sha256=5tLF_gglC1GAKcJNjleSPdVZbM7656SxtqnLzVynrpk,45806
 agents/realtime/runner.py,sha256=KfU7utmc9QFH2htIKN2IN9H-5EnB0qN9ezmvlRTnOm4,2511
-agents/realtime/session.py,sha256=79WqKWwGOsutQRLs7fDsijE-OxEJjGm-aOpjL5F7Fn8,36983
+agents/realtime/session.py,sha256=TmMZdw-1qpQh22Oa_XDy1T6NrnPnGXXRAZ-yKKKFj_w,37077
 agents/tracing/__init__.py,sha256=5HO_6na5S6EwICgwl50OMtxiIIosUrqalhvldlYvSVc,2991
 agents/tracing/create.py,sha256=xpJ4ZRnGyUDPKoVVkA_8hmdhtwOKGhSkwRco2AQIhAo,18003
 agents/tracing/logger.py,sha256=J4KUDRSGa7x5UVfUwWe-gbKwoaq8AeETRqkPt3QvtGg,68
@@ -108,7 +109,7 @@ agents/voice/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 agents/voice/models/openai_model_provider.py,sha256=Khn0uT-VhsEbe7_OhBMGFQzXNwL80gcWZyTHl3CaBII,3587
 agents/voice/models/openai_stt.py,sha256=Lb_F9160VNKDHXZ9zylSzeig7sB8lBjiYhQLDZsp6NQ,17257
 agents/voice/models/openai_tts.py,sha256=4KoLQuFDHKu5a1VTJlu9Nj3MHwMlrn9wfT_liJDJ2dw,1477
-openai_agents-0.4.2.dist-info/METADATA,sha256=UUyVoFXNYwTLrBnkpo7MFwT73-kJH0rQX53xwF3pFXw,13046
-openai_agents-0.4.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-openai_agents-0.4.2.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
-openai_agents-0.4.2.dist-info/RECORD,,
+openai_agents-0.5.0.dist-info/METADATA,sha256=GcCRv8byD4gVjMUNanTpvOaCeAbNxQLN1gPncRMHbBI,13295
+openai_agents-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openai_agents-0.5.0.dist-info/licenses/LICENSE,sha256=E994EspT7Krhy0qGiES7WYNzBHrh1YDk3r--8d1baRU,1063
+openai_agents-0.5.0.dist-info/RECORD,,