Letta Conversations API

The Conversations API allows multiple isolated message threads on a single agent. Each conversation maintains its own message history while sharing the agent's memory blocks and tools.

When to Use This Skill

• Building multi-user chat applications (each user gets their own conversation)

• Implementing session management with separate contexts

• A/B testing agent responses across isolated conversations

• Any scenario where you need multiple independent chat threads with one agent

Key Concepts

Concept Description

Conversation An isolated message thread on an agent (conv-xxx ID)

Isolation Each conversation has separate message history

Shared State Memory blocks and tools are shared across conversations

In-Context Messages Messages currently in the conversation's context window

Python SDK Usage

Setup

from letta_client import Letta

client = Letta(base_url="https://api.letta.com", api_key="your-key")

Create a Conversation

conversation = client.conversations.create(agent_id="agent-xxx")

conversation.id -> "conv-xxx"

Send Messages (Streaming)

stream = client.conversations.messages.create( conversation_id=conversation.id, messages=[{"role": "user", "content": "Hello!"}], )

for msg in stream: if hasattr(msg, "message_type") and msg.message_type == "assistant_message": print(msg.content)

List Messages in a Conversation

messages = client.conversations.messages.list( conversation_id=conversation.id, limit=50, # Optional: default 100 after="message-xxx", # Optional: cursor for pagination before="message-yyy", # Optional: cursor for pagination )

List All Conversations for an Agent

conversations = client.conversations.list( agent_id="agent-xxx", limit=50, # Optional after="conv-xxx", # Optional: cursor for pagination )

Retrieve a Specific Conversation

conv = client.conversations.retrieve(conversation_id="conv-xxx")

conv.in_context_message_ids -> list of message IDs in context window

REST API Endpoints

Method Endpoint Description

POST

/v1/conversations?agent_id=xxx

Create a conversation

GET

/v1/conversations?agent_id=xxx

List conversations

GET

/v1/conversations/{conversation_id}

Get a conversation

GET

/v1/conversations/{conversation_id}/messages

List messages

POST

/v1/conversations/{conversation_id}/messages

Send message (streams response)

POST

/v1/conversations/{conversation_id}/stream

Resume a background stream

REST Example: Create and Send Message

Create conversation

curl -X POST "https://api.letta.com/v1/conversations?agent_id=agent-xxx"
-H "Authorization: Bearer $LETTA_API_KEY"
-H "Content-Type: application/json"

Send message (streaming response)

curl -X POST "https://api.letta.com/v1/conversations/conv-xxx/messages"
-H "Authorization: Bearer $LETTA_API_KEY"
-H "Content-Type: application/json"
-H "Accept: text/event-stream"
-d '{"messages": [{"role": "user", "content": "Hello!"}]}'

Conversation Schema

class Conversation: id: str # "conv-xxx" agent_id: str # Associated agent ID created_at: datetime # Creation timestamp summary: Optional[str] # Optional conversation summary in_context_message_ids: List[str] # Message IDs in context window

Common Patterns

Multi-User Chat Application

Each user gets their own conversation

user_conversations = {}

def get_or_create_conversation(user_id: str, agent_id: str) -> str: if user_id not in user_conversations: conv = client.conversations.create(agent_id=agent_id) user_conversations[user_id] = conv.id return user_conversations[user_id]

def send_user_message(user_id: str, agent_id: str, message: str): conv_id = get_or_create_conversation(user_id, agent_id) return client.conversations.messages.create( conversation_id=conv_id, messages=[{"role": "user", "content": message}], )

Paginating Through Message History

def get_all_messages(conversation_id: str): all_messages = [] after = None

while True:
    batch = client.conversations.messages.list(
        conversation_id=conversation_id,
        limit=100,
        after=after,
    )
    if not batch:
        break
    all_messages.extend(batch)
    after = batch[-1].id

return all_messages

Important Notes

• Streaming by default: The messages.create endpoint always streams responses

• Shared memory: Memory block updates in one conversation are visible in all conversations for that agent

• Message isolation: Conversation message history is completely isolated between conversations

• Pagination: Use after /before cursors for efficient pagination, not offsets

Example Scripts

This skill includes two example scripts in the scripts/ directory:

conversations_demo.py

• Comprehensive demo showing all API features

• Basic conversation flow

• Conversation isolation testing

• Listing and retrieving conversations

• Pagination examples

• Shared memory demonstration

conversations_cli.py

• Interactive TUI for managing conversations

• Create/switch between conversations

• Send messages with streaming responses

• View message history

• Switch between agents

Running the Examples

Run the demo script

LETTA_API_KEY=your-key uv run letta/conversations/scripts/conversations_demo.py

Run the interactive CLI

LETTA_API_KEY=your-key uv run letta/conversations/scripts/conversations_cli.py

CLI with specific agent

LETTA_API_KEY=your-key uv run letta/conversations/scripts/conversations_cli.py --agent agent-xxx

SDK Gotchas

• Paginated responses use .items to access the list: client.agents.list().items

• Auth parameter is api_key , not token : Letta(base_url=..., api_key=...)

• Message streams must be consumed (iterate or list() ) to complete the request