Letta Conversations API

Letta Conversations API

Conversations API を使用すると、1 つのエージェント上で複数の独立したメッセージスレッドを利用できます。各会話はそれぞれ独自のメッセージ履歴を保持しながら、エージェントのメモリブロックとツールを共有します。

このスキルを使用する場面

• マルチユーザーのチャットアプリケーションを構築する場合（各ユーザーに専用の会話を割り当てます）
• 個別のコンテキストを使ったセッション管理を実装する場合
• 独立した会話間でエージェントの応答を A/B テストする場合
• 1 つのエージェントで複数の独立したチャットスレッドが必要なあらゆる場面

主な概念

概念	説明
会話	エージェント上の独立したメッセージスレッド（conv-xxx ID）
分離	各会話はそれぞれ個別のメッセージ履歴を持ちます
共有状態	メモリブロックとツールは会話間で共有されます
コンテキスト内メッセージ	現在、会話のコンテキストウィンドウに含まれているメッセージ

Python SDK の使用方法

セットアップ

from letta_client import Letta

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

会話を作成する

conversation = client.conversations.create(agent_id="agent-xxx")
# conversation.id -> "conv-xxx"

メッセージを送信する（ストリーミング）

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)

会話内のメッセージを一覧表示する

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
)

エージェントのすべての会話を一覧表示する

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

特定の会話を取得する

conv = client.conversations.retrieve(conversation_id="conv-xxx")
# conv.in_context_message_ids -> list of message IDs in context window

REST API エンドポイント

メソッド	エンドポイント	説明
POST	/v1/conversations?agent_id=xxx	会話を作成します
GET	/v1/conversations?agent_id=xxx	会話を一覧表示します
GET	/v1/conversations/{conversation_id}	会話を取得します
GET	/v1/conversations/{conversation_id}/messages	メッセージを一覧表示します
POST	/v1/conversations/{conversation_id}/messages	メッセージを送信します（応答をストリーミングします）
POST	/v1/conversations/{conversation_id}/stream	バックグラウンドストリームを再開します

REST の例：会話を作成してメッセージを送信する

# 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!"}]}'

会話スキーマ

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

よくあるパターン

マルチユーザーのチャットアプリケーション

# 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}],
    )

メッセージ履歴のページネーション

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

重要な注意事項

1. デフォルトではストリーミング：messages.create エンドポイントは常に応答をストリーミングします
2. メモリの共有：ある会話で行われたメモリブロックの更新は、そのエージェントのすべての会話に反映されます
3. メッセージの分離：会話のメッセージ履歴は、会話間で完全に分離されています
4. ページネーション：効率的なページネーションには、オフセットではなく after／before カーソルを使用してください

スクリプトの例

このスキルには、scripts/ ディレクトリに 2 つのスクリプト例が含まれています。

1. conversations_demo.py - すべての API 機能を紹介する包括的なデモ

   • 基本的な会話の流れ
   • 会話の分離テスト
   • 会話の一覧表示と取得
   • ページネーションの例
   • メモリ共有の実演

2. conversations_cli.py - 会話を管理する対話型 TUI

   • 会話の作成／切り替え
   • ストリーミング応答でメッセージを送信
   • メッセージ履歴の表示
   • エージェントの切り替え

例を実行する

# 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 使用時の注意点

• ページネーションされた応答では、リストへのアクセスに .items を使用します：client.agents.list().items
• 認証パラメーターは token ではなく api_key です：Letta(base_url=..., api_key=...)
• リクエストを完了するには、メッセージストリームを消費する必要があります（反復処理するか list() を使用します）