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

agents/realtime/openai_realtime.py

@@ -10,19 +10,53 @@ from typing import Any, Callable, Literal
 
 import pydantic
 import websockets
-from openai.types.beta.realtime.conversation_item import ConversationItem
+from openai.types.beta.realtime.conversation_item import (
+    ConversationItem,
+    ConversationItem as OpenAIConversationItem,
+)
+from openai.types.beta.realtime.conversation_item_content import (
+    ConversationItemContent as OpenAIConversationItemContent,
+)
+from openai.types.beta.realtime.conversation_item_create_event import (
+    ConversationItemCreateEvent as OpenAIConversationItemCreateEvent,
+)
+from openai.types.beta.realtime.conversation_item_retrieve_event import (
+    ConversationItemRetrieveEvent as OpenAIConversationItemRetrieveEvent,
+)
+from openai.types.beta.realtime.conversation_item_truncate_event import (
+    ConversationItemTruncateEvent as OpenAIConversationItemTruncateEvent,
+)
+from openai.types.beta.realtime.input_audio_buffer_append_event import (
+    InputAudioBufferAppendEvent as OpenAIInputAudioBufferAppendEvent,
+)
+from openai.types.beta.realtime.input_audio_buffer_commit_event import (
+    InputAudioBufferCommitEvent as OpenAIInputAudioBufferCommitEvent,
+)
+from openai.types.beta.realtime.realtime_client_event import (
+    RealtimeClientEvent as OpenAIRealtimeClientEvent,
+)
 from openai.types.beta.realtime.realtime_server_event import (
     RealtimeServerEvent as OpenAIRealtimeServerEvent,
 )
 from openai.types.beta.realtime.response_audio_delta_event import ResponseAudioDeltaEvent
+from openai.types.beta.realtime.response_cancel_event import (
+    ResponseCancelEvent as OpenAIResponseCancelEvent,
+)
+from openai.types.beta.realtime.response_create_event import (
+    ResponseCreateEvent as OpenAIResponseCreateEvent,
+)
 from openai.types.beta.realtime.session_update_event import (
     Session as OpenAISessionObject,
     SessionTool as OpenAISessionTool,
+    SessionTracing as OpenAISessionTracing,
+    SessionTracingTracingConfiguration as OpenAISessionTracingConfiguration,
+    SessionUpdateEvent as OpenAISessionUpdateEvent,
 )
 from pydantic import TypeAdapter
 from typing_extensions import assert_never
 from websockets.asyncio.client import ClientConnection
 
+from agents.handoffs import Handoff
 from agents.tool import FunctionTool, Tool
 from agents.util._types import MaybeAwaitable
 
@@ -135,12 +169,11 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
     ) -> None:
         """Update tracing configuration via session.update event."""
         if tracing_config is not None:
+            converted_tracing_config = _ConversionHelper.convert_tracing_config(tracing_config)
             await self._send_raw_message(
-                RealtimeModelSendRawMessage(
-                    message={
-                        "type": "session.update",
-                        "other_data": {"session": {"tracing": tracing_config}},
-                    }
+                OpenAISessionUpdateEvent(
+                    session=OpenAISessionObject(tracing=converted_tracing_config),
+                    type="session.update",
                 )
             )
 
@@ -199,7 +232,11 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
     async def send_event(self, event: RealtimeModelSendEvent) -> None:
         """Send an event to the model."""
         if isinstance(event, RealtimeModelSendRawMessage):
-            await self._send_raw_message(event)
+            converted = _ConversionHelper.try_convert_raw_message(event)
+            if converted is not None:
+                await self._send_raw_message(converted)
+            else:
+                logger.error(f"Failed to convert raw message: {event}")
         elif isinstance(event, RealtimeModelSendUserInput):
             await self._send_user_input(event)
         elif isinstance(event, RealtimeModelSendAudio):
@@ -214,77 +251,33 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             assert_never(event)
             raise ValueError(f"Unknown event type: {type(event)}")
 
-    async def _send_raw_message(self, event: RealtimeModelSendRawMessage) -> None:
+    async def _send_raw_message(self, event: OpenAIRealtimeClientEvent) -> None:
         """Send a raw message to the model."""
         assert self._websocket is not None, "Not connected"
 
-        converted_event = {
-            "type": event.message["type"],
-        }
-
-        converted_event.update(event.message.get("other_data", {}))
-
-        await self._websocket.send(json.dumps(converted_event))
+        await self._websocket.send(event.model_dump_json(exclude_none=True, exclude_unset=True))
 
     async def _send_user_input(self, event: RealtimeModelSendUserInput) -> None:
-        message = (
-            event.user_input
-            if isinstance(event.user_input, dict)
-            else {
-                "type": "message",
-                "role": "user",
-                "content": [{"type": "input_text", "text": event.user_input}],
-            }
-        )
-        other_data = {
-            "item": message,
-        }
-
-        await self._send_raw_message(
-            RealtimeModelSendRawMessage(
-                message={"type": "conversation.item.create", "other_data": other_data}
-            )
-        )
-        await self._send_raw_message(
-            RealtimeModelSendRawMessage(message={"type": "response.create"})
-        )
+        converted = _ConversionHelper.convert_user_input_to_item_create(event)
+        await self._send_raw_message(converted)
+        await self._send_raw_message(OpenAIResponseCreateEvent(type="response.create"))
 
     async def _send_audio(self, event: RealtimeModelSendAudio) -> None:
-        base64_audio = base64.b64encode(event.audio).decode("utf-8")
-        await self._send_raw_message(
-            RealtimeModelSendRawMessage(
-                message={
-                    "type": "input_audio_buffer.append",
-                    "other_data": {
-                        "audio": base64_audio,
-                    },
-                }
-            )
-        )
+        converted = _ConversionHelper.convert_audio_to_input_audio_buffer_append(event)
+        await self._send_raw_message(converted)
         if event.commit:
             await self._send_raw_message(
-                RealtimeModelSendRawMessage(message={"type": "input_audio_buffer.commit"})
+                OpenAIInputAudioBufferCommitEvent(type="input_audio_buffer.commit")
             )
 
     async def _send_tool_output(self, event: RealtimeModelSendToolOutput) -> None:
-        await self._send_raw_message(
-            RealtimeModelSendRawMessage(
-                message={
-                    "type": "conversation.item.create",
-                    "other_data": {
-                        "item": {
-                            "type": "function_call_output",
-                            "output": event.output,
-                            "call_id": event.tool_call.id,
-                        },
-                    },
-                }
-            )
-        )
+        converted = _ConversionHelper.convert_tool_output(event)
+        await self._send_raw_message(converted)
 
         tool_item = RealtimeToolCallItem(
             item_id=event.tool_call.id or "",
             previous_item_id=event.tool_call.previous_item_id,
+            call_id=event.tool_call.call_id,
             type="function_call",
             status="completed",
             arguments=event.tool_call.arguments,
@@ -294,9 +287,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         await self._emit_event(RealtimeModelItemUpdatedEvent(item=tool_item))
 
         if event.start_response:
-            await self._send_raw_message(
-                RealtimeModelSendRawMessage(message={"type": "response.create"})
-            )
+            await self._send_raw_message(OpenAIResponseCreateEvent(type="response.create"))
 
     async def _send_interrupt(self, event: RealtimeModelSendInterrupt) -> None:
         if not self._current_item_id or not self._audio_start_time:
@@ -307,18 +298,12 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
         elapsed_time_ms = (datetime.now() - self._audio_start_time).total_seconds() * 1000
         if elapsed_time_ms > 0 and elapsed_time_ms < self._audio_length_ms:
             await self._emit_event(RealtimeModelAudioInterruptedEvent())
-            await self._send_raw_message(
-                RealtimeModelSendRawMessage(
-                    message={
-                        "type": "conversation.item.truncate",
-                        "other_data": {
-                            "item_id": self._current_item_id,
-                            "content_index": self._current_audio_content_index,
-                            "audio_end_ms": elapsed_time_ms,
-                        },
-                    }
-                )
+            converted = _ConversionHelper.convert_interrupt(
+                self._current_item_id,
+                self._current_audio_content_index or 0,
+                int(elapsed_time_ms),
             )
+            await self._send_raw_message(converted)
 
         self._current_item_id = None
         self._audio_start_time = None
@@ -354,6 +339,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             tool_call = RealtimeToolCallItem(
                 item_id=item.id or "",
                 previous_item_id=None,
+                call_id=item.call_id,
                 type="function_call",
                 # We use the same item for tool call and output, so it will be completed by the
                 # output being added
@@ -365,7 +351,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             await self._emit_event(RealtimeModelItemUpdatedEvent(item=tool_call))
             await self._emit_event(
                 RealtimeModelToolCallEvent(
-                    call_id=item.id or "",
+                    call_id=item.call_id or "",
                     name=item.name or "",
                     arguments=item.arguments or "",
                     id=item.id or "",
@@ -378,7 +364,9 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                     "item_id": item.id or "",
                     "type": item.type,
                     "role": item.role,
-                    "content": item.content,
+                    "content": (
+                        [content.model_dump() for content in item.content] if item.content else []
+                    ),
                     "status": "in_progress",
                 }
             )
@@ -404,9 +392,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
 
     async def _cancel_response(self) -> None:
         if self._ongoing_response:
-            await self._send_raw_message(
-                RealtimeModelSendRawMessage(message={"type": "response.cancel"})
-            )
+            await self._send_raw_message(OpenAIResponseCancelEvent(type="response.cancel"))
             self._ongoing_response = False
 
     async def _handle_ws_event(self, event: dict[str, Any]):
@@ -466,16 +452,13 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
             parsed.type == "conversation.item.input_audio_transcription.completed"
             or parsed.type == "conversation.item.truncated"
         ):
-            await self._send_raw_message(
-                RealtimeModelSendRawMessage(
-                    message={
-                        "type": "conversation.item.retrieve",
-                        "other_data": {
-                            "item_id": self._current_item_id,
-                        },
-                    }
+            if self._current_item_id:
+                await self._send_raw_message(
+                    OpenAIConversationItemRetrieveEvent(
+                        type="conversation.item.retrieve",
+                        item_id=self._current_item_id,
+                    )
                 )
-            )
             if parsed.type == "conversation.item.input_audio_transcription.completed":
                 await self._emit_event(
                     RealtimeModelInputAudioTranscriptionCompletedEvent(
@@ -504,14 +487,7 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
     async def _update_session_config(self, model_settings: RealtimeSessionModelSettings) -> None:
         session_config = self._get_session_config(model_settings)
         await self._send_raw_message(
-            RealtimeModelSendRawMessage(
-                message={
-                    "type": "session.update",
-                    "other_data": {
-                        "session": session_config.model_dump(exclude_unset=True, exclude_none=True)
-                    },
-                }
-            )
+            OpenAISessionUpdateEvent(session=session_config, type="session.update")
         )
 
     def _get_session_config(
@@ -546,10 +522,14 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                 "tool_choice",
                 DEFAULT_MODEL_SETTINGS.get("tool_choice"),  # type: ignore
             ),
-            tools=self._tools_to_session_tools(model_settings.get("tools", [])),
+            tools=self._tools_to_session_tools(
+                tools=model_settings.get("tools", []), handoffs=model_settings.get("handoffs", [])
+            ),
         )
 
-    def _tools_to_session_tools(self, tools: list[Tool]) -> list[OpenAISessionTool]:
+    def _tools_to_session_tools(
+        self, tools: list[Tool], handoffs: list[Handoff]
+    ) -> list[OpenAISessionTool]:
         converted_tools: list[OpenAISessionTool] = []
         for tool in tools:
             if not isinstance(tool, FunctionTool):
@@ -562,6 +542,17 @@ class OpenAIRealtimeWebSocketModel(RealtimeModel):
                     type="function",
                 )
             )
+
+        for handoff in handoffs:
+            converted_tools.append(
+                OpenAISessionTool(
+                    name=handoff.tool_name,
+                    description=handoff.tool_description,
+                    parameters=handoff.input_json_schema,
+                    type="function",
+                )
+            )
+
         return converted_tools
 
 
@@ -582,3 +573,98 @@ class _ConversionHelper:
                 "status": "in_progress",
             },
         )
+
+    @classmethod
+    def try_convert_raw_message(
+        cls, message: RealtimeModelSendRawMessage
+    ) -> OpenAIRealtimeClientEvent | None:
+        try:
+            data = {}
+            data["type"] = message.message["type"]
+            data.update(message.message.get("other_data", {}))
+            return TypeAdapter(OpenAIRealtimeClientEvent).validate_python(data)
+        except Exception:
+            return None
+
+    @classmethod
+    def convert_tracing_config(
+        cls, tracing_config: RealtimeModelTracingConfig | Literal["auto"] | None
+    ) -> OpenAISessionTracing | None:
+        if tracing_config is None:
+            return None
+        elif tracing_config == "auto":
+            return "auto"
+        return OpenAISessionTracingConfiguration(
+            group_id=tracing_config.get("group_id"),
+            metadata=tracing_config.get("metadata"),
+            workflow_name=tracing_config.get("workflow_name"),
+        )
+
+    @classmethod
+    def convert_user_input_to_conversation_item(
+        cls, event: RealtimeModelSendUserInput
+    ) -> OpenAIConversationItem:
+        user_input = event.user_input
+
+        if isinstance(user_input, dict):
+            return OpenAIConversationItem(
+                type="message",
+                role="user",
+                content=[
+                    OpenAIConversationItemContent(
+                        type="input_text",
+                        text=item.get("text"),
+                    )
+                    for item in user_input.get("content", [])
+                ],
+            )
+        else:
+            return OpenAIConversationItem(
+                type="message",
+                role="user",
+                content=[OpenAIConversationItemContent(type="input_text", text=user_input)],
+            )
+
+    @classmethod
+    def convert_user_input_to_item_create(
+        cls, event: RealtimeModelSendUserInput
+    ) -> OpenAIRealtimeClientEvent:
+        return OpenAIConversationItemCreateEvent(
+            type="conversation.item.create",
+            item=cls.convert_user_input_to_conversation_item(event),
+        )
+
+    @classmethod
+    def convert_audio_to_input_audio_buffer_append(
+        cls, event: RealtimeModelSendAudio
+    ) -> OpenAIRealtimeClientEvent:
+        base64_audio = base64.b64encode(event.audio).decode("utf-8")
+        return OpenAIInputAudioBufferAppendEvent(
+            type="input_audio_buffer.append",
+            audio=base64_audio,
+        )
+
+    @classmethod
+    def convert_tool_output(cls, event: RealtimeModelSendToolOutput) -> OpenAIRealtimeClientEvent:
+        return OpenAIConversationItemCreateEvent(
+            type="conversation.item.create",
+            item=OpenAIConversationItem(
+                type="function_call_output",
+                output=event.output,
+                call_id=event.tool_call.call_id,
+            ),
+        )
+
+    @classmethod
+    def convert_interrupt(
+        cls,
+        current_item_id: str,
+        current_audio_content_index: int,
+        elapsed_time_ms: int,
+    ) -> OpenAIRealtimeClientEvent:
+        return OpenAIConversationItemTruncateEvent(
+            type="conversation.item.truncate",
+            item_id=current_item_id,
+            content_index=current_audio_content_index,
+            audio_end_ms=elapsed_time_ms,
+        )

agents/realtime/runner.py

@@ -2,13 +2,10 @@
 
 from __future__ import annotations
 
-import asyncio
-
-from ..run_context import RunContextWrapper, TContext
+from ..run_context import TContext
 from .agent import RealtimeAgent
 from .config import (
     RealtimeRunConfig,
-    RealtimeSessionModelSettings,
 )
 from .model import (
     RealtimeModel,
@@ -67,16 +64,6 @@ class RealtimeRunner:
                     print(event)
             ```
         """
-        model_settings = await self._get_model_settings(
-            agent=self._starting_agent,
-            disable_tracing=self._config.get("tracing_disabled", False) if self._config else False,
-            initial_settings=model_config.get("initial_model_settings") if model_config else None,
-            overrides=self._config.get("model_settings") if self._config else None,
-        )
-
-        model_config = model_config.copy() if model_config else {}
-        model_config["initial_model_settings"] = model_settings
-
         # Create and return the connection
         session = RealtimeSession(
             model=self._model,
@@ -87,32 +74,3 @@ class RealtimeRunner:
         )
 
         return session
-
-    async def _get_model_settings(
-        self,
-        agent: RealtimeAgent,
-        disable_tracing: bool,
-        context: TContext | None = None,
-        initial_settings: RealtimeSessionModelSettings | None = None,
-        overrides: RealtimeSessionModelSettings | None = None,
-    ) -> RealtimeSessionModelSettings:
-        context_wrapper = RunContextWrapper(context)
-        model_settings = initial_settings.copy() if initial_settings else {}
-
-        instructions, tools = await asyncio.gather(
-            agent.get_system_prompt(context_wrapper),
-            agent.get_all_tools(context_wrapper),
-        )
-
-        if instructions is not None:
-            model_settings["instructions"] = instructions
-        if tools is not None:
-            model_settings["tools"] = tools
-
-        if overrides:
-            model_settings.update(overrides)
-
-        if disable_tracing:
-            model_settings["tracing"] = None
-
-        return model_settings

agents/realtime/session.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 from collections.abc import AsyncIterator
 from typing import Any, cast
 
@@ -31,6 +32,7 @@ from .events import (
     RealtimeToolEnd,
     RealtimeToolStart,
 )
+from .handoffs import realtime_handoff
 from .items import InputAudio, InputText, RealtimeItem
 from .model import RealtimeModel, RealtimeModelConfig, RealtimeModelListener
 from .model_events import (
@@ -112,8 +114,13 @@ class RealtimeSession(RealtimeModelListener):
         # Add ourselves as a listener
         self._model.add_listener(self)
 
+        model_config = self._model_config.copy()
+        model_config["initial_model_settings"] = await self._get_updated_model_settings_from_agent(
+            self._current_agent
+        )
+
         # Connect to the model
-        await self._model.connect(self._model_config)
+        await self._model.connect(model_config)
 
         # Emit initial history update
         await self._put_event(
@@ -255,9 +262,12 @@ class RealtimeSession(RealtimeModelListener):
 
     async def _handle_tool_call(self, event: RealtimeModelToolCallEvent) -> None:
         """Handle a tool call event."""
-        all_tools = await self._current_agent.get_all_tools(self._context_wrapper)
-        function_map = {tool.name: tool for tool in all_tools if isinstance(tool, FunctionTool)}
-        handoff_map = {tool.name: tool for tool in all_tools if isinstance(tool, Handoff)}
+        tools, handoffs = await asyncio.gather(
+            self._current_agent.get_all_tools(self._context_wrapper),
+            self._get_handoffs(self._current_agent, self._context_wrapper),
+        )
+        function_map = {tool.name: tool for tool in tools if isinstance(tool, FunctionTool)}
+        handoff_map = {handoff.tool_name: handoff for handoff in handoffs}
 
         if event.name in function_map:
             await self._put_event(
@@ -303,7 +313,9 @@ class RealtimeSession(RealtimeModelListener):
             # Execute the handoff to get the new agent
             result = await handoff.on_invoke_handoff(self._context_wrapper, event.arguments)
             if not isinstance(result, RealtimeAgent):
-                raise UserError(f"Handoff {handoff.name} returned invalid result: {type(result)}")
+                raise UserError(
+                    f"Handoff {handoff.tool_name} returned invalid result: {type(result)}"
+                )
 
             # Store previous agent for event
             previous_agent = self._current_agent
@@ -312,7 +324,9 @@ class RealtimeSession(RealtimeModelListener):
             self._current_agent = result
 
             # Get updated model settings from new agent
-            updated_settings = await self._get__updated_model_settings(self._current_agent)
+            updated_settings = await self._get_updated_model_settings_from_agent(
+                self._current_agent
+            )
 
             # Send handoff event
             await self._put_event(
@@ -488,15 +502,50 @@ class RealtimeSession(RealtimeModelListener):
         # Mark as closed
         self._closed = True
 
-    async def _get__updated_model_settings(
-        self, new_agent: RealtimeAgent
+    async def _get_updated_model_settings_from_agent(
+        self,
+        agent: RealtimeAgent,
     ) -> RealtimeSessionModelSettings:
         updated_settings: RealtimeSessionModelSettings = {}
-        instructions, tools = await asyncio.gather(
-            new_agent.get_system_prompt(self._context_wrapper),
-            new_agent.get_all_tools(self._context_wrapper),
+        instructions, tools, handoffs = await asyncio.gather(
+            agent.get_system_prompt(self._context_wrapper),
+            agent.get_all_tools(self._context_wrapper),
+            self._get_handoffs(agent, self._context_wrapper),
         )
         updated_settings["instructions"] = instructions or ""
         updated_settings["tools"] = tools or []
+        updated_settings["handoffs"] = handoffs or []
+
+        # Override with initial settings
+        initial_settings = self._model_config.get("initial_model_settings", {})
+        updated_settings.update(initial_settings)
+
+        disable_tracing = self._run_config.get("tracing_disabled", False)
+        if disable_tracing:
+            updated_settings["tracing"] = None
 
         return updated_settings
+
+    @classmethod
+    async def _get_handoffs(
+        cls, agent: RealtimeAgent[Any], context_wrapper: RunContextWrapper[Any]
+    ) -> list[Handoff[Any, RealtimeAgent[Any]]]:
+        handoffs: list[Handoff[Any, RealtimeAgent[Any]]] = []
+        for handoff_item in agent.handoffs:
+            if isinstance(handoff_item, Handoff):
+                handoffs.append(handoff_item)
+            elif isinstance(handoff_item, RealtimeAgent):
+                handoffs.append(realtime_handoff(handoff_item))
+
+        async def _check_handoff_enabled(handoff_obj: Handoff[Any, RealtimeAgent[Any]]) -> bool:
+            attr = handoff_obj.is_enabled
+            if isinstance(attr, bool):
+                return attr
+            res = attr(context_wrapper, agent)
+            if inspect.isawaitable(res):
+                return await res
+            return res
+
+        results = await asyncio.gather(*(_check_handoff_enabled(h) for h in handoffs))
+        enabled = [h for h, ok in zip(handoffs, results) if ok]
+        return enabled

{openai_agents-0.2.0.dist-info → openai_agents-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-agents
-Version: 0.2.0
+Version: 0.2.2
 Summary: OpenAI Agents SDK
 Project-URL: Homepage, https://openai.github.io/openai-agents-python/
 Project-URL: Repository, https://github.com/openai/openai-agents-python
@@ -20,8 +20,8 @@ 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.9.4; python_version >= '3.10'
-Requires-Dist: openai<2,>=1.93.1
+Requires-Dist: mcp<2,>=1.11.0; python_version >= '3.10'
+Requires-Dist: openai<2,>=1.96.1
 Requires-Dist: pydantic<3,>=2.10
 Requires-Dist: requests<3,>=2.0
 Requires-Dist: types-requests<3,>=2.0