# Conversations

> List, retrieve, rename, and rate conversation threads from the runner.

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

---

The `Runner` exposes a `conversations` resource for listing, retrieving, renaming, and providing feedback on conversations. Resources return plain `dict` objects using the server's camelCase wire keys.

> **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(...)`

Lists conversations with pagination.

```python title="list_conversations.py"
async def main():
    result = await runner.conversations.list(limit=20, offset=0)
    for conv in result["conversations"]:
        print(f"{conv['id']}: {conv['title']} (updated {conv['updatedAt']})")
```

| Field | Type | Description |
| - | - | - |
| `limit` | `int \| None` | Maximum number of conversations to return. |
| `offset` | `int \| None` | Pagination offset. |

Returns a `dict` (`ConversationListResponse`: `conversations`, `total`, `limit`, `offset`).

## `runner.conversations.retrieve(conversation_id)`

Retrieves a full conversation thread with all messages.

```python
conv = await runner.conversations.retrieve("conv-123")
for msg in conv["messages"]:
    print(f"[{msg['role']}] {msg['content']}")
```

Returns a `dict` — the summary shape plus a `messages` list.

## `runner.conversations.update(conversation_id, *, title=...)`

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

```python
await runner.conversations.update("conv-123", title="My Chat About AI")
```

Returns `None`.

## `runner.conversations.set_message_feedback(conversation_id, message_id, feedback)`

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

```python
await runner.conversations.set_message_feedback("conv-123", "msg-456", "positive")
```

| Field | Type | Description |
| - | - | - |
| `conversation_id` | `str` | The conversation containing the message. |
| `message_id` | `str` | The message to rate. |
| `feedback` | `'positive' \| 'negative'` | The feedback value. |

Returns a `dict` (e.g. `{"ok": True}`).