BetaVoiceAgentsConversationsOperations Class

Delete a voice agent conversation.

Deletes a conversation and all of its stored data — responses, items, and any audio (cascade). This is the customer's explicit data-deletion control for voice conversations.

delete(agent_name: str, conversation_id: str, **kwargs: Any) -> None

Parameters

Returns

Exceptions

Stream a voice agent conversation's merged recording.

Streams the whole-call merged stereo recording as a WAV (audio/wav) byte stream through the service (no SAS URL). This route serves Foundry-managed storage only. For bring-your-own-storage (BYOS) recordings the bytes are not proxied — the caller must download directly from customer storage using the blob_uri returned by the metadata route — so this route returns 409 Conflict for BYOS recordings. While the conversation is in_progress, this route returns retriable 409 Conflict with error.code = recording_not_ready and a Retry-After header when retry guidance is available. When the conversation is failed, it returns terminal 409 Conflict with error.code = recording_unavailable. For a completed conversation, content is available subject to the existing BYOS behavior. A conversation without persisted audio (store = false) returns 404.

download_audio(agent_name: str, conversation_id: str, **kwargs: Any) -> Iterator[bytes]

Parameters

Returns

Exceptions

Stream a voice agent conversation item's audio.

Streams a single conversation item's audio as a WAV (audio/wav) byte stream through the service (no SAS URL). This route serves Foundry-managed storage only. For bring-your-own-storage (BYOS) recordings the bytes are not proxied — the caller must download directly from customer storage using the blob_uri returned by the item's /audio metadata route — so this route returns 409 Conflict for BYOS recordings. Returns 404 when the conversation, item, or its audio was not persisted (store = false).

download_audio_item(agent_name: str, conversation_id: str, item_id: str, **kwargs: Any) -> Iterator[bytes]

Parameters

Returns

Exceptions

Stream a voice agent conversation item's generated audio.

Streams a conversation item's generated audio as a WAV (audio/wav) byte stream through the service. This subordinate artifact exists only when playback was interrupted and the service rendered more audio than the listener heard, including when the response ends as cancelled. This route serves Foundry-managed storage only. For bring-your-own-storage (BYOS) recordings the bytes are not proxied, so this route returns 409 Conflict. Returns 404 when the conversation or item was not persisted, or when no generated audio exists beyond the heard segment.

download_generated_audio_item(agent_name: str, conversation_id: str, item_id: str, **kwargs: Any) -> Iterator[bytes]

Parameters

Returns

Exceptions

Get a voice agent conversation.

Retrieves a single conversation recorded for the specified voice agent endpoint by its id. Returns 404 when the conversation was not persisted (store = false) or does not exist.

get(agent_name: str, conversation_id: str, **kwargs: Any) -> VoiceConversation

Parameters

Returns

Exceptions

Get a voice agent conversation's merged recording metadata.

Returns metadata for the whole-call merged stereo recording (user audio on the left channel, agent audio on the right). The common metadata (format, sample rate, channels, channel layout, duration) is returned for both Foundry-managed and bring-your-own-storage (BYOS) recordings; for BYOS the response additionally includes blob_uri, the URI of the recording in the customer's own storage (no SAS) that the customer downloads with their own credentials. The recording is built once from the per-turn segments after persistence finalization succeeds. While the conversation is in_progress, this route returns retriable 409 Conflict with error.code = recording_not_ready and a Retry-After header when retry guidance is available. When the conversation is failed, it returns terminal 409 Conflict with error.code = recording_unavailable. For a completed conversation, metadata is available subject to the existing BYOS behavior. Requires the conversation to have persisted audio (store = true); otherwise returns 404.

get_audio(agent_name: str, conversation_id: str, **kwargs: Any) -> VoiceRecording

Parameters

Returns

Exceptions

Get a voice agent conversation item's audio metadata.

Returns metadata for a single conversation item's audio segment, including the common playback facts (role, format/codec, sample rate, channels, offset, duration) for both Foundry-managed and bring-your-own-storage (BYOS) recordings; for BYOS the response additionally includes blob_uri, the URI of the recording in the customer's own storage (no SAS) that the customer downloads with their own credentials. Requires the conversation to have persisted audio (store = true); returns 404 when the conversation, item, or its audio was not persisted.

get_audio_item(agent_name: str, conversation_id: str, item_id: str, **kwargs: Any) -> VoiceAudioItem

Parameters

Returns

Exceptions

Get a voice agent conversation item's generated audio metadata.

Returns metadata for a conversation item's generated audio. This subordinate artifact is separate from the canonical heard-audio segment and exists only when playback was interrupted and the service rendered more audio than the listener heard, including when the response ends as cancelled. Returns 404 when the conversation or item was not persisted, or when no generated audio exists beyond the heard segment.

get_generated_audio_item(agent_name: str, conversation_id: str, item_id: str, **kwargs: Any) -> VoiceGeneratedAudioItem

Parameters

Returns

Exceptions

Get a voice agent conversation item.

Retrieves a single item from the specified conversation by its id, including its transcript. An input_audio/output_audio content part indicates that audio is available for the item; the canonical per-item audio metadata is the /items/{item_id}/audio resource, and the bytes are streamed by /items/{item_id}/audio/content. Returns 404 when the conversation or item was not persisted (store = false).

get_item(agent_name: str, conversation_id: str, item_id: str, **kwargs: Any) -> RealtimeConversationItem

Parameters

Returns

Exceptions

Get a voice agent conversation response.

Retrieves a single response from the specified conversation by its id, including its output items, usage, and status. Returns 404 when the conversation or response was not persisted (store = false).

get_response(agent_name: str, conversation_id: str, response_id: str, **kwargs: Any) -> VoiceResponse

Parameters

Returns

Exceptions

List voice agent conversations.

Returns the conversations persisted for the specified voice agent endpoint. Conversations are present when the session's effective store setting is true, whether inherited from the agent definition or enabled by the WebSocket session override.

list(agent_name: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[VoiceConversation]

Parameters

Keyword-Only Parameters

Returns

Exceptions

List items in a voice agent conversation.

Returns a paged collection of items — the complete ordered conversation history, including user input, assistant output, and client-created tool outputs (transcripts + tool events). Returns 404 when the conversation was not persisted (store = false).

list_items(agent_name: str, conversation_id: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[RealtimeConversationItem]

Parameters

Keyword-Only Parameters

Returns

Exceptions

List items produced by a voice agent conversation response.

Returns a paged collection of the output items produced by a specific response (the response's output projection). For the complete ordered conversation history — including user input and client-created tool outputs — use the conversation items route instead. Returns 404 when the conversation or response was not persisted (store = false).

list_response_items(agent_name: str, conversation_id: str, response_id: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[RealtimeConversationItem]

Parameters

Keyword-Only Parameters

Returns

Exceptions

List responses in a voice agent conversation.

Returns a paged collection of the responses (model inference turns) recorded for the specified conversation. The per-response output projection may be omitted here; use the response-items route for the canonical paged output. Returns 404 when the conversation was not persisted (store = false).

list_responses(agent_name: str, conversation_id: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[VoiceResponse]

Parameters

Keyword-Only Parameters

Returns

Exceptions