Agent SDK · State and data

Conversations.

Read, rename, and rate conversation threads from the runner.

The Runner exposes a conversations resource for listing, retrieving, renaming, and providing feedback on conversations.

Note

Note: Agent runs send persist: false by default, so they do not appear in the Matilda web app's chat history. The conversations resource accesses conversations created by other clients (e.g. the web app). If you need agent runs to appear in chat history, you would need to override the persist flag — but this is not exposed as a public option in the agent SDK.

`runner.conversations.list(options?)`

Lists conversations with pagination.

TypeScript

const result = await runner.conversations.list({ limit: 20, offset: 0 });
for (const conv of result.conversations) {
  console.log(`${conv.id}: ${conv.title} (updated ${conv.updatedAt})`);
}

Field	type	description
limit	number	Maximum number of conversations to return.
offset	number	Pagination offset.

Returns Promise<ConversationListResponse>:

TypeScript

interface ConversationListResponse {
  conversations: ConversationSummary[];
  total: number;
  limit: number;
  offset: number;
}

interface ConversationSummary {
  id: string;
  userId: string;
  title: string;
  createdAt: string;
  updatedAt: string;
}

`runner.conversations.retrieve(conversationId, options?)`

Retrieves a full conversation thread with all messages.

TypeScript

const conv = await runner.conversations.retrieve('conv-123');
for (const msg of conv.messages) {
  console.log(`[${msg.role}] ${msg.content}`);
}

Returns Promise<ConversationRecord>:

TypeScript

interface ConversationRecord extends ConversationSummary {
  messages: ConversationMessage[];
}

`runner.conversations.update(conversationId, patch, options?)`

Updates a conversation's metadata (currently only title).

TypeScript

await runner.conversations.update('conv-123', { title: 'My Chat About AI' });

Returns Promise<void>.

`runner.conversations.setMessageFeedback(conversationId, messageId, feedback, options?)`

Sets thumbs-up or thumbs-down feedback on a specific message.

TypeScript

await runner.conversations.setMessageFeedback('conv-123', 'msg-456', 'positive');

Field	type	description
conversationId	string	The conversation containing the message.
messageId	string	The message to rate.
feedback	'positive' \| 'negative'	The feedback value.

Returns Promise<{ ok: boolean }>.