[8/n] Make realtime more like the rest of agents sdk

Key changes:
1. Transport -> model.
2. Extract any model settings into `RealtimeSessionModelSettings`.
3. RealtimeRunConfig, similar to the RunConfig in `run.py`.

Next PR I'll update session to be better.

Author: rm-openai

src/agents/realtime/__init__.py

@@ -1,5 +1,16 @@
 from .agent import RealtimeAgent, RealtimeAgentHooks, RealtimeRunHooks
-from .config import APIKeyOrKeyFunc
+from .config import (
+    RealtimeAudioFormat,
+    RealtimeClientMessage,
+    RealtimeInputAudioTranscriptionConfig,
+    RealtimeModelName,
+    RealtimeRunConfig,
+    RealtimeSessionModelSettings,
+    RealtimeTurnDetectionConfig,
+    RealtimeUserInput,
+    RealtimeUserInputMessage,
+    RealtimeUserInputText,
+)
 from .events import (
     RealtimeAgentEndEvent,
     RealtimeAgentStartEvent,
@@ -15,13 +26,12 @@
     RealtimeToolEnd,
     RealtimeToolStart,
 )
-from .session import RealtimeSession
-from .transport import (
-    RealtimeModelName,
-    RealtimeSessionTransport,
-    RealtimeTransportConnectionOptions,
-    RealtimeTransportListener,
+from .model import (
+    RealtimeModel,
+    RealtimeModelConfig,
+    RealtimeModelListener,
 )
+from .session import RealtimeSession
 
 __all__ = [
     "RealtimeAgent",
@@ -30,11 +40,19 @@
     "RealtimeSession",
     "RealtimeSessionListener",
     "RealtimeSessionListenerFunc",
-    "APIKeyOrKeyFunc",
+    "RealtimeRunConfig",
+    "RealtimeSessionModelSettings",
+    "RealtimeInputAudioTranscriptionConfig",
+    "RealtimeTurnDetectionConfig",
+    "RealtimeAudioFormat",
+    "RealtimeClientMessage",
+    "RealtimeUserInput",
+    "RealtimeUserInputMessage",
+    "RealtimeUserInputText",
     "RealtimeModelName",
-    "RealtimeSessionTransport",
-    "RealtimeTransportListener",
-    "RealtimeTransportConnectionOptions",
+    "RealtimeModel",
+    "RealtimeModelListener",
+    "RealtimeModelConfig",
     "RealtimeSessionEvent",
     "RealtimeAgentStartEvent",
     "RealtimeAgentEndEvent",

src/agents/realtime/config.py

@@ -1,34 +1,44 @@
 from __future__ import annotations
 
-import inspect
 from typing import (
     Any,
-    Callable,
     Literal,
     Union,
 )
 
 from typing_extensions import NotRequired, TypeAlias, TypedDict
 
 from ..model_settings import ToolChoice
-from ..tool import FunctionTool
-from ..util._types import MaybeAwaitable
+from ..tool import Tool
+
+RealtimeModelName: TypeAlias = Union[
+    Literal[
+        "gpt-4o-realtime-preview",
+        "gpt-4o-mini-realtime-preview",
+        "gpt-4o-realtime-preview-2025-06-03",
+        "gpt-4o-realtime-preview-2024-12-17",
+        "gpt-4o-realtime-preview-2024-10-01",
+        "gpt-4o-mini-realtime-preview-2024-12-17",
+    ],
+    str,
+]
+"""The name of a realtime model."""
 
 
 class RealtimeClientMessage(TypedDict):
     type: str  # explicitly required
     other_data: NotRequired[dict[str, Any]]
 
 
-class UserInputText(TypedDict):
+class RealtimeUserInputText(TypedDict):
     type: Literal["input_text"]
     text: str
 
 
 class RealtimeUserInputMessage(TypedDict):
     type: Literal["message"]
     role: Literal["user"]
-    content: list[UserInputText]
+    content: list[RealtimeUserInputText]
 
 
 RealtimeUserInput: TypeAlias = Union[str, RealtimeUserInputMessage]
@@ -55,9 +65,11 @@ class RealtimeTurnDetectionConfig(TypedDict):
     threshold: NotRequired[float]
 
 
-class RealtimeSessionConfig(TypedDict):
-    api_key: NotRequired[APIKeyOrKeyFunc]
-    model: NotRequired[str]
+class RealtimeSessionModelSettings(TypedDict):
+    """Model settings for a realtime model session."""
+
+    model_name: NotRequired[RealtimeModelName]
+
     instructions: NotRequired[str]
     modalities: NotRequired[list[Literal["text", "audio"]]]
     voice: NotRequired[str]
@@ -68,24 +80,13 @@ class RealtimeSessionConfig(TypedDict):
     turn_detection: NotRequired[RealtimeTurnDetectionConfig]
 
     tool_choice: NotRequired[ToolChoice]
-    tools: NotRequired[list[FunctionTool]]
-
-
-APIKeyOrKeyFunc = str | Callable[[], MaybeAwaitable[str]]
-"""Either an API key or a function that returns an API key."""
-
+    tools: NotRequired[list[Tool]]
 
-async def get_api_key(key: APIKeyOrKeyFunc | None) -> str | None:
-    """Get the API key from the key or key function."""
-    if key is None:
-        return None
-    elif isinstance(key, str):
-        return key
 
-    result = key()
-    if inspect.isawaitable(result):
-        return await result
-    return result
+class RealtimeRunConfig(TypedDict):
+    model_settings: NotRequired[RealtimeSessionModelSettings]
 
     # TODO (rm) Add tracing support
     # tracing: NotRequired[RealtimeTracingConfig | None]
+    # TODO (rm) Add guardrail support
+    # TODO (rm) Add history audio storage config

src/agents/realtime/events.py

@@ -7,7 +7,7 @@
 from ..tool import Tool
 from .agent import RealtimeAgent
 from .items import RealtimeItem
-from .transport_events import RealtimeTransportAudioEvent, RealtimeTransportEvent
+from .model_events import RealtimeModelAudioEvent, RealtimeModelEvent
 
 
 @dataclass
@@ -96,7 +96,7 @@ class RealtimeToolEnd:
 class RealtimeRawTransportEvent:
     """Forwards raw events from the transport layer."""
 
-    data: RealtimeTransportEvent
+    data: RealtimeModelEvent
     """The raw data from the transport layer."""
 
     info: RealtimeEventInfo
@@ -119,7 +119,7 @@ class RealtimeAudioEnd:
 class RealtimeAudio:
     """Triggered when the agent generates new audio to be played."""
 
-    audio: RealtimeTransportAudioEvent
+    audio: RealtimeModelAudioEvent
     """The audio event from the transport layer."""
 
     info: RealtimeEventInfo

src/agents/realtime/model.py

@@ -0,0 +1,97 @@
+import abc
+from typing import Any, Callable
+
+from typing_extensions import NotRequired, TypedDict
+
+from ..util._types import MaybeAwaitable
+from .config import (
+    RealtimeClientMessage,
+    RealtimeSessionModelSettings,
+    RealtimeUserInput,
+)
+from .model_events import RealtimeModelEvent, RealtimeModelToolCallEvent
+
+
+class RealtimeModelListener(abc.ABC):
+    """A listener for realtime transport events."""
+
+    @abc.abstractmethod
+    async def on_event(self, event: RealtimeModelEvent) -> None:
+        """Called when an event is emitted by the realtime transport."""
+        pass
+
+
+class RealtimeModelConfig(TypedDict):
+    """Options for connecting to a realtime model."""
+
+    api_key: NotRequired[str | Callable[[], MaybeAwaitable[str]]]
+    """The API key (or function that returns a key) to use when connecting. If unset, the model will
+    try to use a sane default. For example, the OpenAI Realtime model will try to use the
+    `OPENAI_API_KEY`  environment variable.
+    """
+
+    url: NotRequired[str]
+    """The URL to use when connecting. If unset, the model will use a sane default. For example,
+    the OpenAI Realtime model will use the default OpenAI WebSocket URL.
+    """
+
+    initial_model_settings: NotRequired[RealtimeSessionModelSettings]
+
+
+class RealtimeModel(abc.ABC):
+    """Interface for connecting to a realtime model and sending/receiving events."""
+
+    @abc.abstractmethod
+    async def connect(self, options: RealtimeModelConfig) -> None:
+        """Establish a connection to the model and keep it alive."""
+        pass
+
+    @abc.abstractmethod
+    def add_listener(self, listener: RealtimeModelListener) -> None:
+        """Add a listener to the model."""
+        pass
+
+    @abc.abstractmethod
+    async def remove_listener(self, listener: RealtimeModelListener) -> None:
+        """Remove a listener from the model."""
+        pass
+
+    @abc.abstractmethod
+    async def send_event(self, event: RealtimeClientMessage) -> None:
+        """Send an event to the model."""
+        pass
+
+    @abc.abstractmethod
+    async def send_message(
+        self, message: RealtimeUserInput, other_event_data: dict[str, Any] | None = None
+    ) -> None:
+        """Send a message to the model."""
+        pass
+
+    @abc.abstractmethod
+    async def send_audio(self, audio: bytes, *, commit: bool = False) -> None:
+        """Send a raw audio chunk to the model.
+
+        Args:
+            audio: The audio data to send.
+            commit: Whether to commit the audio buffer to the model.  If the model does not do turn
+            detection, this can be used to indicate the turn is completed.
+        """
+        pass
+
+    @abc.abstractmethod
+    async def send_tool_output(
+        self, tool_call: RealtimeModelToolCallEvent, output: str, start_response: bool
+    ) -> None:
+        """Send tool output to the model."""
+        pass
+
+    @abc.abstractmethod
+    async def interrupt(self) -> None:
+        """Interrupt the model. For example, could be triggered by a guardrail."""
+        pass
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        """Close the session."""
+        pass