Client SDK · State and data

Multi-turn conversations.

Carry context across turns with conversation_id.

The client SDK does not have a Session class. Multi-turn conversations are managed by passing a conversation_id to each chat call. The server reconstructs the full conversation history server-side from the session store.

Pattern

Generate a conversation ID (any unique string, e.g. a UUID).
Pass it to every chat.create() or chat.stream() call.
The server maintains the conversation history — you only send the latest message.

Caution

Important: Omitting conversation_id auto-creates a new conversation per call, and the response never returns that auto-created ID. Mint your own ID (e.g. uuid.uuid4()) and thread it through — it's the only way to continue a conversation.

Python

import asyncio
from uuid import uuid4

from matilda_client import MatildaClient


async def main():
    async with MatildaClient() as client:
        # Authenticate with device flow — token refresh is handled automatically
        if not await client.auth.get_tokens():
            await client.auth.login_with_device_flow(client_id="matilda-code")

        conversation_id = str(uuid4())

        # Turn 1
        r1 = await client.chat.create(
            input="What is the capital of France?", conversation_id=conversation_id
        )
        print(r1.output_text)  # "Paris"

        # Turn 2 — server remembers the previous turn
        r2 = await client.chat.create(
            input="What about Germany?", conversation_id=conversation_id
        )
        print(r2.output_text)  # "Berlin"

        # Turn 3
        r3 = await client.chat.create(
            input="And Italy?", conversation_id=conversation_id
        )
        print(r3.output_text)  # "Rome"


asyncio.run(main())

Contrasting with the agent SDK

The Matilda agent SDK provides a Session class that wraps an Agent with auto-managed conversation_id, a turns list, and session-level defaults. If you need client-side tool execution, approval loops, or session state management, consider the agent SDK. For simple chatbot integrations, the client SDK's conversation_id pattern is sufficient.

Retrieving conversation history

Python

# List all conversations
result = await client.conversations.list(limit=50)

# Retrieve a specific conversation with full message history
conv = await client.conversations.retrieve(conversation_id)
for msg in conv["messages"]:
    print(f"[{msg['role']}] {msg['content']}")