Skill

Letta Conversations API

Name: Letta Conversations API
Author: Letta

manage isolated agent conversation threads

Published by Letta Updated Jul 13

Covers Sessions Agents API Development

Description

Guide for using the Letta Conversations API to manage isolated message threads on agents. Use when building multi-user chat applications, session management, or any scenario requiring separate conversation contexts on a single agent.

SKILL.md

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

More skills from the skills repository

View all 45 skills

SkillTagsUpdated

More from Letta

View publisher

SkillTagsUpdated