openai-agents 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

agents/agent.py

@@ -214,7 +214,7 @@ class Agent(AgentBase, Generic[TContext]):
       calls result in a final output.
 
       NOTE: This configuration is specific to FunctionTools. Hosted tools, such as file search,
-      web search, etc are always processed by the LLM.
+      web search, etc. are always processed by the LLM.
     """
 
     reset_tool_choice: bool = True
@@ -289,30 +289,3 @@ class Agent(AgentBase, Generic[TContext]):
     ) -> ResponsePromptParam | None:
         """Get the prompt for the agent."""
         return await PromptUtil.to_model_input(self.prompt, run_context, self)
-
-    async def get_mcp_tools(self, run_context: RunContextWrapper[TContext]) -> list[Tool]:
-        """Fetches the available tools from the MCP servers."""
-        convert_schemas_to_strict = self.mcp_config.get("convert_schemas_to_strict", False)
-        return await MCPUtil.get_all_function_tools(
-            self.mcp_servers, convert_schemas_to_strict, run_context, self
-        )
-
-    async def get_all_tools(self, run_context: RunContextWrapper[Any]) -> list[Tool]:
-        """All agent tools, including MCP tools and function tools."""
-        mcp_tools = await self.get_mcp_tools(run_context)
-
-        async def _check_tool_enabled(tool: Tool) -> bool:
-            if not isinstance(tool, FunctionTool):
-                return True
-
-            attr = tool.is_enabled
-            if isinstance(attr, bool):
-                return attr
-            res = attr(run_context, self)
-            if inspect.isawaitable(res):
-                return bool(await res)
-            return bool(res)
-
-        results = await asyncio.gather(*(_check_tool_enabled(t) for t in self.tools))
-        enabled: list[Tool] = [t for t, ok in zip(self.tools, results) if ok]
-        return [*mcp_tools, *enabled]

agents/agent_output.py

@@ -116,7 +116,7 @@ class AgentOutputSchema(AgentOutputSchemaBase):
                 raise UserError(
                     "Strict JSON schema is enabled, but the output type is not valid. "
                     "Either make the output type strict, "
-                    "or wrap your type with AgentOutputSchema(your_type, strict_json_schema=False)"
+                    "or wrap your type with AgentOutputSchema(YourType, strict_json_schema=False)"
                 ) from e
 
     def is_plain_text(self) -> bool:

agents/extensions/models/litellm_model.py

@@ -45,6 +45,14 @@ from ...tracing.spans import Span
 from ...usage import Usage
 
 
+class InternalChatCompletionMessage(ChatCompletionMessage):
+    """
+    An internal subclass to carry reasoning_content without modifying the original model.
+    """
+
+    reasoning_content: str
+
+
 class LitellmModel(Model):
     """This class enables using any model via LiteLLM. LiteLLM allows you to acess OpenAPI,
     Anthropic, Gemini, Mistral, and many other models.
@@ -364,13 +372,18 @@ class LitellmConverter:
             provider_specific_fields.get("refusal", None) if provider_specific_fields else None
         )
 
-        return ChatCompletionMessage(
+        reasoning_content = ""
+        if hasattr(message, "reasoning_content") and message.reasoning_content:
+            reasoning_content = message.reasoning_content
+
+        return InternalChatCompletionMessage(
             content=message.content,
             refusal=refusal,
             role="assistant",
             annotations=cls.convert_annotations_to_openai(message),
             audio=message.get("audio", None),  # litellm deletes audio if not present
             tool_calls=tool_calls,
+            reasoning_content=reasoning_content,
         )
 
     @classmethod

agents/function_schema.py

@@ -76,7 +76,7 @@ class FuncSchema:
 
 @dataclass
 class FuncDocumentation:
-    """Contains metadata about a python function, extracted from its docstring."""
+    """Contains metadata about a Python function, extracted from its docstring."""
 
     name: str
     """The name of the function, via `__name__`."""
@@ -194,7 +194,7 @@ def function_schema(
     strict_json_schema: bool = True,
 ) -> FuncSchema:
     """
-    Given a python function, extracts a `FuncSchema` from it, capturing the name, description,
+    Given a Python function, extracts a `FuncSchema` from it, capturing the name, description,
     parameter descriptions, and other metadata.
 
     Args:
@@ -208,7 +208,7 @@ def function_schema(
             descriptions.
         strict_json_schema: Whether the JSON schema is in strict mode. If True, we'll ensure that
             the schema adheres to the "strict" standard the OpenAI API expects. We **strongly**
-            recommend setting this to True, as it increases the likelihood of the LLM providing
+            recommend setting this to True, as it increases the likelihood of the LLM producing
             correct JSON input.
 
     Returns:

agents/guardrail.py

@@ -78,8 +78,9 @@ class InputGuardrail(Generic[TContext]):
     You can use the `@input_guardrail()` decorator to turn a function into an `InputGuardrail`, or
     create an `InputGuardrail` manually.
 
-    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, the agent
-    execution will immediately stop and a `InputGuardrailTripwireTriggered` exception will be raised
+    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`,
+    the agent's execution will immediately stop, and
+    an `InputGuardrailTripwireTriggered` exception will be raised
     """
 
     guardrail_function: Callable[
@@ -132,7 +133,7 @@ class OutputGuardrail(Generic[TContext]):
     You can use the `@output_guardrail()` decorator to turn a function into an `OutputGuardrail`,
     or create an `OutputGuardrail` manually.
 
-    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, a
+    Guardrails return a `GuardrailResult`. If `result.tripwire_triggered` is `True`, an
     `OutputGuardrailTripwireTriggered` exception will be raised.
     """
 
@@ -314,7 +315,11 @@ def output_guardrail(
     def decorator(
         f: _OutputGuardrailFuncSync[TContext_co] | _OutputGuardrailFuncAsync[TContext_co],
     ) -> OutputGuardrail[TContext_co]:
-        return OutputGuardrail(guardrail_function=f, name=name)
+        return OutputGuardrail(
+            guardrail_function=f,
+            # Guardrail name defaults to function's name when not specified (None).
+            name=name if name else f.__name__,
+        )
 
     if func is not None:
         # Decorator was used without parentheses

agents/items.py

@@ -5,6 +5,7 @@ import copy
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, Union
 
+import pydantic
 from openai.types.responses import (
     Response,
     ResponseComputerToolCall,
@@ -212,7 +213,7 @@ RunItem: TypeAlias = Union[
 """An item generated by an agent."""
 
 
-@dataclass
+@pydantic.dataclasses.dataclass
 class ModelResponse:
     output: list[TResponseOutputItem]
     """A list of outputs (messages, tool calls, etc) generated by the model"""

agents/model_settings.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import dataclasses
 from collections.abc import Mapping
-from dataclasses import dataclass, fields, replace
+from dataclasses import fields, replace
 from typing import Annotated, Any, Literal, Union
 
 from openai import Omit as _Omit
@@ -10,6 +10,7 @@ from openai._types import Body, Query
 from openai.types.responses import ResponseIncludable
 from openai.types.shared import Reasoning
 from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic.dataclasses import dataclass
 from pydantic_core import core_schema
 from typing_extensions import TypeAlias
 

agents/models/chatcmpl_converter.py

@@ -36,6 +36,7 @@ from openai.types.responses import (
     ResponseOutputRefusal,
     ResponseOutputText,
     ResponseReasoningItem,
+    ResponseReasoningItemParam,
 )
 from openai.types.responses.response_input_param import FunctionCallOutput, ItemReference, Message
 from openai.types.responses.response_reasoning_item import Summary
@@ -210,6 +211,12 @@ class Converter:
             return cast(ResponseOutputMessageParam, item)
         return None
 
+    @classmethod
+    def maybe_reasoning_message(cls, item: Any) -> ResponseReasoningItemParam | None:
+        if isinstance(item, dict) and item.get("type") == "reasoning":
+            return cast(ResponseReasoningItemParam, item)
+        return None
+
     @classmethod
     def extract_text_content(
         cls, content: str | Iterable[ResponseInputContentParam]
@@ -459,7 +466,11 @@ class Converter:
                     f"Encountered an item_reference, which is not supported: {item_ref}"
                 )
 
-            # 7) If we haven't recognized it => fail or ignore
+            # 7) reasoning message => not handled
+            elif cls.maybe_reasoning_message(item):
+                pass
+
+            # 8) If we haven't recognized it => fail or ignore
             else:
                 raise UserError(f"Unhandled item type or structure: {item}")
 

agents/models/chatcmpl_stream_handler.py

@@ -198,6 +198,7 @@ class ChatCmplStreamHandler:
                     is not None,  # fixed 0 -> 0 or 1
                     type="response.output_text.delta",
                     sequence_number=sequence_number.get_and_increment(),
+                    logprobs=[],
                 )
                 # Accumulate the text into the response part
                 state.text_content_index_and_output[1].text += delta.content
@@ -288,10 +289,11 @@ class ChatCmplStreamHandler:
                     function_call = state.function_calls[tc_delta.index]
 
                     # Start streaming as soon as we have function name and call_id
-                    if (not state.function_call_streaming[tc_delta.index] and
-                        function_call.name and
-                        function_call.call_id):
-
+                    if (
+                        not state.function_call_streaming[tc_delta.index]
+                        and function_call.name
+                        and function_call.call_id
+                    ):
                         # Calculate the output index for this function call
                         function_call_starting_index = 0
                         if state.reasoning_content_index_and_output:
@@ -308,9 +310,9 @@ class ChatCmplStreamHandler:
 
                         # Mark this function call as streaming and store its output index
                         state.function_call_streaming[tc_delta.index] = True
-                        state.function_call_output_idx[
-                            tc_delta.index
-                        ] = function_call_starting_index
+                        state.function_call_output_idx[tc_delta.index] = (
+                            function_call_starting_index
+                        )
 
                         # Send initial function call added event
                         yield ResponseOutputItemAddedEvent(
@@ -327,10 +329,11 @@ class ChatCmplStreamHandler:
                         )
 
                     # Stream arguments if we've started streaming this function call
-                    if (state.function_call_streaming.get(tc_delta.index, False) and
-                        tc_function and
-                        tc_function.arguments):
-
+                    if (
+                        state.function_call_streaming.get(tc_delta.index, False)
+                        and tc_function
+                        and tc_function.arguments
+                    ):
                         output_index = state.function_call_output_idx[tc_delta.index]
                         yield ResponseFunctionCallArgumentsDeltaEvent(
                             delta=tc_function.arguments,
@@ -493,9 +496,9 @@ class ChatCmplStreamHandler:
         final_response.output = outputs
         final_response.usage = (
             ResponseUsage(
-                input_tokens=usage.prompt_tokens,
-                output_tokens=usage.completion_tokens,
-                total_tokens=usage.total_tokens,
+                input_tokens=usage.prompt_tokens or 0,
+                output_tokens=usage.completion_tokens or 0,
+                total_tokens=usage.total_tokens or 0,
                 output_tokens_details=OutputTokensDetails(
                     reasoning_tokens=usage.completion_tokens_details.reasoning_tokens
                     if usage.completion_tokens_details

agents/realtime/__init__.py

@@ -47,6 +47,8 @@ from .model import (
     RealtimeModel,
     RealtimeModelConfig,
     RealtimeModelListener,
+    RealtimePlaybackState,
+    RealtimePlaybackTracker,
 )
 from .model_events import (
     RealtimeConnectionStatus,
@@ -139,6 +141,8 @@ __all__ = [
     "RealtimeModel",
     "RealtimeModelConfig",
     "RealtimeModelListener",
+    "RealtimePlaybackTracker",
+    "RealtimePlaybackState",
     # Model Events
     "RealtimeConnectionStatus",
     "RealtimeModelAudioDoneEvent",

agents/realtime/_default_tracker.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ._util import calculate_audio_length_ms
+from .config import RealtimeAudioFormat
+
+
+@dataclass
+class ModelAudioState:
+    initial_received_time: datetime
+    audio_length_ms: float
+
+
+class ModelAudioTracker:
+    def __init__(self) -> None:
+        # (item_id, item_content_index) -> ModelAudioState
+        self._states: dict[tuple[str, int], ModelAudioState] = {}
+        self._last_audio_item: tuple[str, int] | None = None
+
+    def set_audio_format(self, format: RealtimeAudioFormat) -> None:
+        """Called when the model wants to set the audio format."""
+        self._format = format
+
+    def on_audio_delta(self, item_id: str, item_content_index: int, audio_bytes: bytes) -> None:
+        """Called when an audio delta is received from the model."""
+        ms = calculate_audio_length_ms(self._format, audio_bytes)
+        new_key = (item_id, item_content_index)
+
+        self._last_audio_item = new_key
+        if new_key not in self._states:
+            self._states[new_key] = ModelAudioState(datetime.now(), ms)
+        else:
+            self._states[new_key].audio_length_ms += ms
+
+    def on_interrupted(self) -> None:
+        """Called when the audio playback has been interrupted."""
+        self._last_audio_item = None
+
+    def get_state(self, item_id: str, item_content_index: int) -> ModelAudioState | None:
+        """Called when the model wants to get the current playback state."""
+        return self._states.get((item_id, item_content_index))
+
+    def get_last_audio_item(self) -> tuple[str, int] | None:
+        """Called when the model wants to get the last audio item ID and content index."""
+        return self._last_audio_item

agents/realtime/_util.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from .config import RealtimeAudioFormat
+
+
+def calculate_audio_length_ms(format: RealtimeAudioFormat | None, audio_bytes: bytes) -> float:
+    if format and format.startswith("g711"):
+        return (len(audio_bytes) / 8000) * 1000
+    return (len(audio_bytes) / 24 / 2) * 1000

agents/realtime/events.py

@@ -115,6 +115,12 @@ class RealtimeAudioEnd:
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_end"] = "audio_end"
 
 
@@ -125,6 +131,12 @@ class RealtimeAudio:
     audio: RealtimeModelAudioEvent
     """The audio event from the model layer."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
@@ -140,6 +152,12 @@ class RealtimeAudioInterrupted:
     info: RealtimeEventInfo
     """Common info for all events, such as the context."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_interrupted"] = "audio_interrupted"
 
 

agents/realtime/model.py

@@ -6,13 +6,95 @@ from typing import Callable
 from typing_extensions import NotRequired, TypedDict
 
 from ..util._types import MaybeAwaitable
+from ._util import calculate_audio_length_ms
 from .config import (
+    RealtimeAudioFormat,
     RealtimeSessionModelSettings,
 )
 from .model_events import RealtimeModelEvent
 from .model_inputs import RealtimeModelSendEvent
 
 
+class RealtimePlaybackState(TypedDict):
+    current_item_id: str | None
+    """The item ID of the current item being played."""
+
+    current_item_content_index: int | None
+    """The index of the current item content being played."""
+
+    elapsed_ms: float | None
+    """The number of milliseconds of audio that have been played."""
+
+
+class RealtimePlaybackTracker:
+    """If you have custom playback logic or expect that audio is played with delays or at different
+    speeds, create an instance of RealtimePlaybackTracker and pass it to the session. You are
+    responsible for tracking the audio playback progress and calling `on_play_bytes` or
+    `on_play_ms` when the user has played some audio."""
+
+    def __init__(self) -> None:
+        self._format: RealtimeAudioFormat | None = None
+        # (item_id, item_content_index)
+        self._current_item: tuple[str, int] | None = None
+        self._elapsed_ms: float | None = None
+
+    def on_play_bytes(self, item_id: str, item_content_index: int, bytes: bytes) -> None:
+        """Called by you when you have played some audio.
+
+        Args:
+            item_id: The item ID of the audio being played.
+            item_content_index: The index of the audio content in `item.content`
+            bytes: The audio bytes that have been fully played.
+        """
+        ms = calculate_audio_length_ms(self._format, bytes)
+        self.on_play_ms(item_id, item_content_index, ms)
+
+    def on_play_ms(self, item_id: str, item_content_index: int, ms: float) -> None:
+        """Called by you when you have played some audio.
+
+        Args:
+            item_id: The item ID of the audio being played.
+            item_content_index: The index of the audio content in `item.content`
+            ms: The number of milliseconds of audio that have been played.
+        """
+        if self._current_item != (item_id, item_content_index):
+            self._current_item = (item_id, item_content_index)
+            self._elapsed_ms = ms
+        else:
+            assert self._elapsed_ms is not None
+            self._elapsed_ms += ms
+
+    def on_interrupted(self) -> None:
+        """Called by the model when the audio playback has been interrupted."""
+        self._current_item = None
+        self._elapsed_ms = None
+
+    def set_audio_format(self, format: RealtimeAudioFormat) -> None:
+        """Will be called by the model to set the audio format.
+
+        Args:
+            format: The audio format to use.
+        """
+        self._format = format
+
+    def get_state(self) -> RealtimePlaybackState:
+        """Will be called by the model to get the current playback state."""
+        if self._current_item is None:
+            return {
+                "current_item_id": None,
+                "current_item_content_index": None,
+                "elapsed_ms": None,
+            }
+        assert self._elapsed_ms is not None
+
+        item_id, item_content_index = self._current_item
+        return {
+            "current_item_id": item_id,
+            "current_item_content_index": item_content_index,
+            "elapsed_ms": self._elapsed_ms,
+        }
+
+
 class RealtimeModelListener(abc.ABC):
     """A listener for realtime transport events."""
 
@@ -39,6 +121,18 @@ class RealtimeModelConfig(TypedDict):
     initial_model_settings: NotRequired[RealtimeSessionModelSettings]
     """The initial model settings to use when connecting."""
 
+    playback_tracker: NotRequired[RealtimePlaybackTracker]
+    """The playback tracker to use when tracking audio playback progress. If not set, the model will
+    use a default implementation that assumes audio is played immediately, at realtime speed.
+
+    A playback tracker is useful for interruptions. The model generates audio much faster than
+    realtime playback speed. So if there's an interruption, its useful for the model to know how
+    much of the audio has been played by the user. In low-latency scenarios, it's fine to assume
+    that audio is played back immediately at realtime speed. But in scenarios like phone calls or
+    other remote interactions, you can set a playback tracker that lets the model know when audio
+    is played to the user.
+    """
+
 
 class RealtimeModel(abc.ABC):
     """Interface for connecting to a realtime model and sending/receiving events."""

agents/realtime/model_events.py

@@ -40,6 +40,12 @@ class RealtimeModelAudioEvent:
     data: bytes
     response_id: str
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio"] = "audio"
 
 
@@ -47,6 +53,12 @@ class RealtimeModelAudioEvent:
 class RealtimeModelAudioInterruptedEvent:
     """Audio interrupted."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_interrupted"] = "audio_interrupted"
 
 
@@ -54,6 +66,12 @@ class RealtimeModelAudioInterruptedEvent:
 class RealtimeModelAudioDoneEvent:
     """Audio done."""
 
+    item_id: str
+    """The ID of the item containing audio."""
+
+    content_index: int
+    """The index of the audio content in `item.content`"""
+
     type: Literal["audio_done"] = "audio_done"
 
 
@@ -138,6 +156,15 @@ class RealtimeModelExceptionEvent:
     type: Literal["exception"] = "exception"
 
 
+@dataclass
+class RealtimeModelRawServerEvent:
+    """Raw events forwarded from the server."""
+
+    data: Any
+
+    type: Literal["raw_server_event"] = "raw_server_event"
+
+
 # TODO (rm) Add usage events
 
 
@@ -156,4 +183,5 @@ RealtimeModelEvent: TypeAlias = Union[
     RealtimeModelTurnEndedEvent,
     RealtimeModelOtherEvent,
     RealtimeModelExceptionEvent,
+    RealtimeModelRawServerEvent,
 ]