Model Events

RealtimeModelErrorEvent dataclass

Represents a transport‑layer error.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelErrorEvent:
    """Represents a transport‑layer error."""

    error: Any

    type: Literal["error"] = "error"

RealtimeModelToolCallEvent dataclass

Model attempted a tool/function call.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelToolCallEvent:
    """Model attempted a tool/function call."""

    name: str
    call_id: str
    arguments: str

    id: str | None = None
    previous_item_id: str | None = None

    type: Literal["function_call"] = "function_call"

RealtimeModelAudioEvent dataclass

Raw audio bytes emitted by the model.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelAudioEvent:
    """Raw audio bytes emitted by the model."""

    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"

item_id instance-attribute

item_id: str

The ID of the item containing audio.

content_index instance-attribute

content_index: int

The index of the audio content in item.content

RealtimeModelAudioInterruptedEvent dataclass

Audio interrupted.

Source code in src/agents/realtime/model_events.py

@dataclass
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"

item_id instance-attribute

item_id: str

The ID of the item containing audio.

content_index instance-attribute

content_index: int

The index of the audio content in item.content

RealtimeModelAudioDoneEvent dataclass

Audio done.

Source code in src/agents/realtime/model_events.py

@dataclass
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"

item_id instance-attribute

item_id: str

The ID of the item containing audio.

content_index instance-attribute

content_index: int

The index of the audio content in item.content

RealtimeModelInputAudioTranscriptionCompletedEvent dataclass

Input audio transcription completed.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelInputAudioTranscriptionCompletedEvent:
    """Input audio transcription completed."""

    item_id: str
    transcript: str

    type: Literal["input_audio_transcription_completed"] = "input_audio_transcription_completed"

RealtimeModelInputAudioTimeoutTriggeredEvent dataclass

Input audio timeout triggered.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelInputAudioTimeoutTriggeredEvent:
    """Input audio timeout triggered."""

    item_id: str
    audio_start_ms: int
    audio_end_ms: int

    type: Literal["input_audio_timeout_triggered"] = "input_audio_timeout_triggered"

RealtimeModelTranscriptDeltaEvent dataclass

Partial transcript update.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelTranscriptDeltaEvent:
    """Partial transcript update."""

    item_id: str
    delta: str
    response_id: str

    type: Literal["transcript_delta"] = "transcript_delta"

RealtimeModelItemUpdatedEvent dataclass

Item added to the history or updated.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelItemUpdatedEvent:
    """Item added to the history or updated."""

    item: RealtimeItem

    type: Literal["item_updated"] = "item_updated"

RealtimeModelItemDeletedEvent dataclass

Item deleted from the history.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelItemDeletedEvent:
    """Item deleted from the history."""

    item_id: str

    type: Literal["item_deleted"] = "item_deleted"

RealtimeModelConnectionStatusEvent dataclass

Connection status changed.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelConnectionStatusEvent:
    """Connection status changed."""

    status: RealtimeConnectionStatus

    type: Literal["connection_status"] = "connection_status"

RealtimeModelTurnStartedEvent dataclass

Triggered when the model starts generating a response for a turn.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelTurnStartedEvent:
    """Triggered when the model starts generating a response for a turn."""

    type: Literal["turn_started"] = "turn_started"

RealtimeModelCachedTokensDetails dataclass

Modality breakdown for cached Realtime input tokens.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelCachedTokensDetails:
    """Modality breakdown for cached Realtime input tokens."""

    text_tokens: int | None = None
    audio_tokens: int | None = None
    image_tokens: int | None = None

RealtimeModelInputTokensDetails dataclass

Modality breakdown for Realtime input tokens.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelInputTokensDetails:
    """Modality breakdown for Realtime input tokens."""

    text_tokens: int | None = None
    audio_tokens: int | None = None
    image_tokens: int | None = None
    cached_tokens: int | None = None
    cached_tokens_details: RealtimeModelCachedTokensDetails | None = None

RealtimeModelOutputTokensDetails dataclass

Modality breakdown for Realtime output tokens.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelOutputTokensDetails:
    """Modality breakdown for Realtime output tokens."""

    text_tokens: int | None = None
    audio_tokens: int | None = None

RealtimeModelUsageEvent dataclass

Token usage reported for a completed Realtime model response.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelUsageEvent:
    """Token usage reported for a completed Realtime model response."""

    usage: Usage
    """Aggregate usage compatible with the shared SDK usage accounting."""

    input_tokens_details: RealtimeModelInputTokensDetails | None = None
    """Optional input-token modality details reported by the model provider."""

    output_tokens_details: RealtimeModelOutputTokensDetails | None = None
    """Optional output-token modality details reported by the model provider."""

    type: Literal["usage"] = "usage"

usage instance-attribute

usage: Usage

Aggregate usage compatible with the shared SDK usage accounting.

input_tokens_details class-attribute instance-attribute

input_tokens_details: (
    RealtimeModelInputTokensDetails | None
) = None

Optional input-token modality details reported by the model provider.

output_tokens_details class-attribute instance-attribute

output_tokens_details: (
    RealtimeModelOutputTokensDetails | None
) = None

Optional output-token modality details reported by the model provider.

RealtimeModelTurnEndedEvent dataclass

Triggered when the model finishes generating a response for a turn.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelTurnEndedEvent:
    """Triggered when the model finishes generating a response for a turn."""

    type: Literal["turn_ended"] = "turn_ended"

RealtimeModelOtherEvent dataclass

Used as a catchall for vendor-specific events.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelOtherEvent:
    """Used as a catchall for vendor-specific events."""

    data: Any

    type: Literal["other"] = "other"

RealtimeModelExceptionEvent dataclass

Exception occurred during model operation.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelExceptionEvent:
    """Exception occurred during model operation."""

    exception: Exception
    context: str | None = None

    type: Literal["exception"] = "exception"

RealtimeModelRawServerEvent dataclass

Raw events forwarded from the server.

Source code in src/agents/realtime/model_events.py

@dataclass
class RealtimeModelRawServerEvent:
    """Raw events forwarded from the server."""

    data: Any

    type: Literal["raw_server_event"] = "raw_server_event"