# Conversations

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

Source: https://maincode.com/docs/agent-sdk-conversations
Section: Agent SDK · Matilda documentation

---

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.

```ts
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>`:

```ts
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.

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

Returns `Promise<ConversationRecord>`:

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

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

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

```ts
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.

```ts
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 }>`.