Agent SDK · State and data

Conversations.

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

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

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