[6/n] RealtimeSession + events

pyproject.toml

@@ -37,6 +37,7 @@ Repository = "https://github.com/openai/openai-agents-python"
 voice = ["numpy>=2.2.0, <3; python_version>='3.10'", "websockets>=15.0, <16"]
 viz = ["graphviz>=0.17"]
 litellm = ["litellm>=1.67.4.post1, <2"]
+realtime = ["websockets>=15.0, <16"]
 
 [dependency-groups]
 dev = [

src/agents/realtime/README.md

@@ -0,0 +1,3 @@
+# Realtime
+
+Realtime agents are in beta: expect some breaking changes over the next few weeks as we find issues and fix them.

src/agents/realtime/__init__.py

@@ -0,0 +1,51 @@
+from .agent import RealtimeAgent, RealtimeAgentHooks, RealtimeRunHooks
+from .config import APIKeyOrKeyFunc
+from .events import (
+    RealtimeAgentEndEvent,
+    RealtimeAgentStartEvent,
+    RealtimeAudio,
+    RealtimeAudioEnd,
+    RealtimeAudioInterrupted,
+    RealtimeError,
+    RealtimeHandoffEvent,
+    RealtimeHistoryAdded,
+    RealtimeHistoryUpdated,
+    RealtimeRawTransportEvent,
+    RealtimeSessionEvent,
+    RealtimeToolEnd,
+    RealtimeToolStart,
+)
+from .session import RealtimeSession
+from .transport import (
+    RealtimeModelName,
+    RealtimeSessionTransport,
+    RealtimeTransportConnectionOptions,
+    RealtimeTransportListener,
+)
+
+__all__ = [
+    "RealtimeAgent",
+    "RealtimeAgentHooks",
+    "RealtimeRunHooks",
+    "RealtimeSession",
+    "RealtimeSessionListener",
+    "RealtimeSessionListenerFunc",
+    "APIKeyOrKeyFunc",
+    "RealtimeModelName",
+    "RealtimeSessionTransport",
+    "RealtimeTransportListener",
+    "RealtimeTransportConnectionOptions",
+    "RealtimeSessionEvent",
+    "RealtimeAgentStartEvent",
+    "RealtimeAgentEndEvent",
+    "RealtimeHandoffEvent",
+    "RealtimeToolStart",
+    "RealtimeToolEnd",
+    "RealtimeRawTransportEvent",
+    "RealtimeAudioEnd",
+    "RealtimeAudio",
+    "RealtimeAudioInterrupted",
+    "RealtimeError",
+    "RealtimeHistoryUpdated",
+    "RealtimeHistoryAdded",
+]

src/agents/realtime/events.py

@@ -0,0 +1,198 @@
+from dataclasses import dataclass
+from typing import Any, Literal, Union
+
+from typing_extensions import TypeAlias
+
+from ..run_context import RunContextWrapper
+from ..tool import Tool
+from .agent import RealtimeAgent
+from .items import RealtimeItem
+from .transport_events import RealtimeTransportAudioEvent, RealtimeTransportEvent
+
+
+@dataclass
+class RealtimeEventInfo:
+    context: RunContextWrapper
+    """The context for the event."""
+
+
+@dataclass
+class RealtimeAgentStartEvent:
+    """A new agent has started."""
+
+    agent: RealtimeAgent
+    """The new agent."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["agent_start"] = "agent_start"
+
+
+@dataclass
+class RealtimeAgentEndEvent:
+    """An agent has ended."""
+
+    agent: RealtimeAgent
+    """The agent that ended."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["agent_end"] = "agent_end"
+
+
+@dataclass
+class RealtimeHandoffEvent:
+    """An agent has handed off to another agent."""
+
+    from_agent: RealtimeAgent
+    """The agent that handed off."""
+
+    to_agent: RealtimeAgent
+    """The agent that was handed off to."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["handoff"] = "handoff"
+
+
+@dataclass
+class RealtimeToolStart:
+    """An agent is starting a tool call."""
+
+    agent: RealtimeAgent
+    """The agent that updated."""
+
+    tool: Tool
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["tool_start"] = "tool_start"
+
+
+@dataclass
+class RealtimeToolEnd:
+    """An agent has ended a tool call."""
+
+    agent: RealtimeAgent
+    """The agent that ended the tool call."""
+
+    tool: Tool
+    """The tool that was called."""
+
+    output: Any
+    """The output of the tool call."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["tool_end"] = "tool_end"
+
+
+@dataclass
+class RealtimeRawTransportEvent:
+    """Forwards raw events from the transport layer."""
+
+    data: RealtimeTransportEvent
+    """The raw data from the transport layer."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["raw_transport_event"] = "raw_transport_event"
+
+
+@dataclass
+class RealtimeAudioEnd:
+    """Triggered when the agent stops generating audio."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio_end"] = "audio_end"
+
+
+@dataclass
+class RealtimeAudio:
+    """Triggered when the agent generates new audio to be played."""
+
+    audio: RealtimeTransportAudioEvent
+    """The audio event from the transport layer."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio"] = "audio"
+
+
+@dataclass
+class RealtimeAudioInterrupted:
+    """Triggered when the agent is interrupted. Can be listened to by the user to stop audio
+    playback or give visual indicators to the user.
+    """
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["audio_interrupted"] = "audio_interrupted"
+
+
+@dataclass
+class RealtimeError:
+    """An error has occurred."""
+
+    error: Any
+    """The error that occurred."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["error"] = "error"
+
+
+@dataclass
+class RealtimeHistoryUpdated:
+    """The history has been updated. Contains the full history of the session."""
+
+    history: list[RealtimeItem]
+    """The full history of the session."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["history_updated"] = "history_updated"
+
+
+@dataclass
+class RealtimeHistoryAdded:
+    """A new item has been added to the history."""
+
+    item: RealtimeItem
+    """The new item that was added to the history."""
+
+    info: RealtimeEventInfo
+    """Common info for all events, such as the context."""
+
+    type: Literal["history_added"] = "history_added"
+
+
+# TODO (rm) Add guardrails
+
+RealtimeSessionEvent: TypeAlias = Union[
+    RealtimeAgentStartEvent,
+    RealtimeAgentEndEvent,
+    RealtimeHandoffEvent,
+    RealtimeToolStart,
+    RealtimeToolEnd,
+    RealtimeRawTransportEvent,
+    RealtimeAudioEnd,
+    RealtimeAudio,
+    RealtimeAudioInterrupted,
+    RealtimeError,
+    RealtimeHistoryUpdated,
+    RealtimeHistoryAdded,
+]
+"""An event emitted by the realtime session."""

src/agents/realtime/items.py

@@ -92,7 +92,7 @@ class RealtimeToolCallItem(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-RealtimeItem = RealtimeMessageItem | RealtimeToolCallItem
+RealtimeItem = Union[RealtimeMessageItem, RealtimeToolCallItem]
 
 
 class RealtimeResponse(BaseModel):