Agent Conversations

Get a voice agent conversation item

GET /agents/{agent_name}/endpoint/protocols/voice/conversations/{conversation_id}/items/{item_id}

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).

Header parameters

Foundry-Features enum required

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

VoiceAgents=V1Preview

Path parameters

agent_name string required

The name of the agent.

conversation_id string required

The id of the conversation that contains the item.

item_id string required

The id of the conversation item to retrieve.

Query parameters

api-version string required

The API version to use for this operation.

Responses

The request has succeeded.

Body

Content-Type: application/json

One of the following:

message system | user | assistant

One of the following:

system OpenAI.RealtimeConversationItemMessageSystem

A system message in a Realtime conversation can be used to provide additional context or instructions to the model. This is similar but distinct from the instruction prompt provided at the start of a conversation, as system messages can be added at any point in the conversation. For major changes to the conversation's behavior, use instructions, but for smaller updates (e.g. "the user is now asking about a different topic"), use system messages.

id string

The unique ID of the item. This may be provided by the client or generated by the server.

object enum

Identifier for the API object being returned - always realtime.item. Optional when creating a new item.

realtime.item

type enum required

The type of the item. Always message.

message

status enum

The status of the item. Has no effect on the conversation.

completedincompletein_progress

role enum required

The role of the message sender. Always system.

system

content OpenAI.RealtimeConversationItemMessageSystemContent[] required

The content of the message.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

user OpenAI.RealtimeConversationItemMessageUser

A user message item in a Realtime conversation.

id string

The unique ID of the item. This may be provided by the client or generated by the server.

object enum

Identifier for the API object being returned - always realtime.item. Optional when creating a new item.

realtime.item

type enum required

The type of the item. Always message.

message

status enum

The status of the item. Has no effect on the conversation.

completedincompletein_progress

role enum required

The role of the message sender. Always user.

user

content OpenAI.RealtimeConversationItemMessageUserContent[] required

The content of the message.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

assistant OpenAI.RealtimeConversationItemMessageAssistant

An assistant message item in a Realtime conversation.

id string

The unique ID of the item. This may be provided by the client or generated by the server.

object enum

Identifier for the API object being returned - always realtime.item. Optional when creating a new item.

realtime.item

type enum required

The type of the item. Always message.

message

status enum

The status of the item. Has no effect on the conversation.

completedincompletein_progress

role enum required

The role of the message sender. Always assistant.

assistant

content OpenAI.RealtimeConversationItemMessageAssistantContent[] required

The content of the message.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

function_call OpenAI.RealtimeConversationItemFunctionCall

A function call item in a Realtime conversation.

id string

The unique ID of the item. This may be provided by the client or generated by the server.

object enum

Identifier for the API object being returned - always realtime.item. Optional when creating a new item.

realtime.item

type enum required

The type of the item. Always function_call.

function_call

status enum

The status of the item. Has no effect on the conversation.

completedincompletein_progress

call_id string

The ID of the function call.

name string required

The name of the function being called.

arguments string required

The arguments of the function call. This is a JSON-encoded string representing the arguments passed to the function, for example {"arg1": "value1", "arg2": 42}.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

function_call_output OpenAI.RealtimeConversationItemFunctionCallOutput

A function call output item in a Realtime conversation.

id string

The unique ID of the item. This may be provided by the client or generated by the server.

object enum

Identifier for the API object being returned - always realtime.item. Optional when creating a new item.

realtime.item

type enum required

The type of the item. Always function_call_output.

function_call_output

status enum

The status of the item. Has no effect on the conversation.

completedincompletein_progress

call_id string required

The ID of the function call this output is for.

output string required

The output of the function call, this is free text and can contain any information or simply be empty.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

name string

The name of the function that was called. A Foundry extension: OpenAI's function_call_output does not carry the function name, only call_id.

mcp_approval_response OpenAI.RealtimeMCPApprovalResponse

A Realtime item responding to an MCP approval request.

type enum required

The type of the item. Always mcp_approval_response.

mcp_approval_response

id string required

The unique ID of the approval response.

approval_request_id string required

The ID of the approval request being answered.

approve boolean required

Whether the request was approved.

reason string | null

created_at integer

response_id string

The id of the response that produced this item, when applicable.

mcp_list_tools OpenAI.RealtimeMCPListTools

A Realtime item listing tools available on an MCP server.

type enum required

The type of the item. Always mcp_list_tools.

mcp_list_tools

id string

The unique ID of the list.

server_label string required

The label of the MCP server.

tools OpenAI.MCPListToolsTool[] required

The tools available on the server.

created_at integer

response_id string

The id of the response that produced this item, when applicable.

mcp_call OpenAI.RealtimeMCPToolCall

A Realtime item representing an invocation of a tool on an MCP server.

type enum required

The type of the item. Always mcp_call.

mcp_call

id string required

The unique ID of the tool call.

server_label string required

The label of the MCP server running the tool.

name string required

The name of the tool that was run.

arguments string required

A JSON string of the arguments passed to the tool.

approval_request_id string | null

output string | null

error protocol_error | tool_execution_error | http_error

One of the following:

protocol_error OpenAI.RealtimeMCPProtocolError

type enum required

protocol_error

code integer required

message string required

tool_execution_error OpenAI.RealtimeMCPToolExecutionError

type enum required

tool_execution_error

message string required

http_error OpenAI.RealtimeMCPHTTPError

type enum required

http_error

code integer required

message string required

created_at integer

response_id string

The id of the response that produced this item, when applicable.

mcp_approval_request OpenAI.RealtimeMCPApprovalRequest

A Realtime item requesting human approval of a tool invocation.

type enum required

The type of the item. Always mcp_approval_request.

mcp_approval_request

id string required

The unique ID of the approval request.

server_label string required

The label of the MCP server making the request.

name string required

The name of the tool to run.

arguments string required

A JSON string of arguments for the tool.

created_at integer

response_id string

The id of the response that produced this item, when applicable.