BetaRealtimeConnection Class

An open realtime WebSocket connection to a voice agent.

Iterate over the connection to receive strongly-typed server events, and use the sub-namespaces to send strongly-typed client events:

   with client.beta.voice_agents.realtime.connect(agent_name="my-agent") as conn:
       for event in conn:
           if event.type == RealtimeServerEventType.RESPONSE_DONE:
               break

Constructor

BetaRealtimeConnection(connection: ClientConnection)

Parameters

Name	Description
connection Required

Methods

close	Close the connection.
recv	Receive and parse the next server event. Known event types are returned as their strongly-typed VoiceAgentServerEventXxx model. Event types not (yet) represented by a generated model are returned as a plain dict for forward compatibility.
send	Send a client event over the connection.

close

Close the connection.

close(*, code: int = 1000, reason: str = '') -> None

Keyword-Only Parameters

Name	Description
code	int The WebSocket close code. Default value: 1000
reason	str The close reason.

recv

Receive and parse the next server event.

Known event types are returned as their strongly-typed VoiceAgentServerEventXxx model. Event types not (yet) represented by a generated model are returned as a plain dict for forward compatibility.

recv(*, timeout: float | None = None) -> RealtimeServerEventError | RealtimeServerEventResponseContentPartAdded | RealtimeServerEventConversationItemAdded | RealtimeServerEventConversationItemCreated | RealtimeServerEventConversationItemDeleted | RealtimeServerEventConversationItemDone | RealtimeServerEventConversationItemInputAudioTranscriptionCompleted | RealtimeServerEventConversationItemInputAudioTranscriptionDelta | RealtimeServerEventConversationItemInputAudioTranscriptionFailed | RealtimeServerEventConversationItemInputAudioTranscriptionSegment | RealtimeServerEventConversationItemRetrieved | RealtimeServerEventConversationItemTruncated | RealtimeServerEventInputAudioBufferCleared | RealtimeServerEventInputAudioBufferCommitted | RealtimeServerEventInputAudioBufferSpeechStarted | RealtimeServerEventInputAudioBufferSpeechStopped | RealtimeServerEventInputAudioBufferTimeoutTriggered | RealtimeServerEventMCPListToolsCompleted | RealtimeServerEventMCPListToolsFailed | RealtimeServerEventMCPListToolsInProgress | RealtimeServerEventOutputAudioBufferCleared | RealtimeServerEventRateLimitsUpdated | VoiceAgentServerEventResponseAnimationBlendshapesDelta | VoiceAgentServerEventResponseAnimationBlendshapesDone | VoiceAgentServerEventResponseAnimationVisemeDelta | VoiceAgentServerEventResponseAnimationVisemeDone | RealtimeServerEventResponseAudioDelta | RealtimeServerEventResponseAudioDone | VoiceAgentServerEventResponseAudioTimestampDelta | VoiceAgentServerEventResponseAudioTimestampDone | RealtimeServerEventResponseAudioTranscriptDelta | RealtimeServerEventResponseAudioTranscriptDone | RealtimeServerEventResponseContentPartDone | RealtimeServerEventResponseCreated | RealtimeServerEventResponseDone | RealtimeServerEventResponseFunctionCallArgumentsDelta | RealtimeServerEventResponseFunctionCallArgumentsDone | RealtimeServerEventResponseMCPCallArgumentsDelta | RealtimeServerEventResponseMCPCallArgumentsDone | RealtimeServerEventResponseMCPCallCompleted | RealtimeServerEventResponseMCPCallFailed | RealtimeServerEventResponseMCPCallInProgress | RealtimeServerEventResponseOutputItemAdded | RealtimeServerEventResponseOutputItemDone | RealtimeServerEventResponseTextDelta | RealtimeServerEventResponseTextDone | VoiceAgentServerEventResponseVideoDelta | VoiceAgentServerEventRtcCallError | VoiceAgentServerEventRtcCallSdpCreated | VoiceAgentServerEventSessionAvatarConnecting | VoiceAgentServerEventSessionAvatarSwitchToIdle | VoiceAgentServerEventSessionAvatarSwitchToSpeaking | RealtimeServerEventSessionCreated | VoiceAgentServerEventSessionSubagentAborted | VoiceAgentServerEventSessionSubagentCompleted | VoiceAgentServerEventSessionSubagentStarted | RealtimeServerEventSessionUpdated | VoiceAgentServerEventWarning | Mapping[str, Any]

Keyword-Only Parameters

Name	Description
timeout	float or None Maximum time in seconds to wait for the next event. If None (the default), block until an event is received. If no event arrives within timeout seconds, raise TimeoutError. Default value: None

Returns

Type	Description
<xref:azure.ai.projects.ServerEvent>	The parsed server event.

Exceptions

Type	Description
ConnectionResetError	If the connection was closed by the server, gracefully or otherwise. Iterating over the connection ( for event in conn:
TimeoutError	If timeout elapses before an event is received.

send

Send a client event over the connection.

send(event: RealtimeClientEventConversationItemCreate | RealtimeClientEventConversationItemDelete | RealtimeClientEventConversationItemRetrieve | RealtimeClientEventConversationItemTruncate | RealtimeClientEventInputAudioBufferAppend | RealtimeClientEventInputAudioBufferClear | RealtimeClientEventInputAudioBufferCommit | RealtimeClientEventOutputAudioBufferClear | RealtimeClientEventResponseCancel | RealtimeClientEventResponseCreate | VoiceAgentClientEventRtcCallSdpCreate | VoiceAgentClientEventSessionAvatarConnect | VoiceAgentClientEventSessionUpdate | str | Mapping[str, Any]) -> None

Parameters

Name	Description
event Required	<xref:azure.ai.projects.ClientEvent> or str A strongly-typed client event, a ready-made mapping, or a raw JSON string.

Exceptions

Type	Description
ValueError	If event is a str that is not valid JSON.

Attributes

closed

Whether the underlying WebSocket connection has been closed.

Returns

Type	Description
bool