OpenAI Responses API Conversations

The OpenAI Responses API Conversations surface provides methods to create, retrieve, delete, and inspect thread-backed conversations in Mastra.

This API follows up on the OpenAI Responses API. Stored Responses calls return conversation_id, and in Mastra that value is the raw memory threadId. Use client.conversations when you want to work with that thread directly.

This API is currently experimental.

Relationship to OpenAI Responses

Use the OpenAI Responses API for generation and continuation:

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Start a support thread',
  store: true,
})

console.log(response.conversation_id)

Use the Conversations API when you want to inspect or manage that stored thread:

const conversation = await client.conversations.retrieve(response.conversation_id!)
const items = await client.conversations.items.list(response.conversation_id!)

Usage example

import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const conversation = await client.conversations.create({
  agent_id: 'support-agent',
})

console.log(conversation.id)

Methods

Lifecycle

create(params)

Creates a new conversation thread for the selected agent.

const conversation = await client.conversations.create({
  agent_id: 'support-agent',
  title: 'Billing support',
})

Returns: Promise<Conversation>.

retrieve(conversationId, requestContext?)

Retrieves a conversation by its thread ID.

const conversation = await client.conversations.retrieve('thread_123')

console.log(conversation.thread)

Returns: Promise<Conversation>.

delete(conversationId, requestContext?)

Deletes a conversation by its thread ID.

const deleted = await client.conversations.delete('thread_123')

console.log(deleted.deleted)

Returns: Promise<ConversationDeleted>.

Items

items.list(conversationId, requestContext?)

Lists the stored items for a conversation.

const items = await client.conversations.items.list('thread_123')

console.log(items.data)

Returns: Promise<ConversationItemsPage>.

Response shape

create() and retrieve() return a conversation object with:

• id: The raw thread ID
• object: Always 'conversation'
• thread: The stored thread record

delete() returns:

• id: The raw thread ID
• object: Always 'conversation.deleted'
• deleted: Always true

items.list() returns:

• object: Always 'list'
• data: Conversation items such as message, function_call, and function_call_output
• first_id: The first item ID in the page
• last_id: The last item ID in the page
• has_more: Whether more items exist beyond the current page

Parameters

agent_id:

string

Required. The registered Mastra agent that owns the conversation memory.

conversation_id?:

string

Optional conversation ID to use as the raw thread ID.

resource_id?:

string

Optional resource ID to associate with the conversation thread.

title?:

string

Optional thread title stored with the conversation.

metadata?:

Record<string, unknown>

Optional thread metadata stored with the conversation.

requestContext?:

RequestContext | Record<string, any>

Optional request context forwarded to the Mastra server.