letta-api-client

Letta API クライアントスキル

Letta API を基盤にアプリケーションを構築できます。これは、メモリと長期学習を備えた永続的なエージェントを構築するための、モデルに依存しないステートフルな API です。Letta API は Letta Code と Learning SDK を支えています。このスキルでは、エージェントの作成、メモリの管理、カスタムツールの構築、複数ユーザーのシナリオへの対応に関する基本パターンを扱います。

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

• 永続的でステートフルな AI エージェントを必要とするアプリケーションを構築するとき
• メモリを備えたチャットボット、アシスタント、自律型エージェントを作成するとき
• 既存のウェブ／モバイルアプリケーションに Letta を統合するとき
• 各ユーザーが専用のエージェントを持つ複数ユーザー向けアプリケーションを構築するとき
• Letta Code と Learning SDK の基盤となる API レイヤーを理解するとき

クイックスタート

初回セットアップと一般的なオンボーディングの問題については、getting-started.md を参照してください。

テスト済みの SDK バージョン

例は以下のバージョンで最終テストされています。

• Python SDK：letta-client==1.7.1
• TypeScript SDK：@letta-ai/[email protected]

基本概念

1. クライアントのセットアップ

初期化パターンについては、client-setup.md を参照してください。

• Letta Cloud 接続とセルフホスト接続
• 環境変数の管理
• ウェブフレームワーク向けのシングルトンパターン

2. メモリアーキテクチャ

メモリのパターンについては、memory-architecture.md を参照してください。

• コアメモリブロック：常にコンテキスト内に保持されます（ペルソナ、人間、カスタムブロック）
• アーカイブメモリ：セマンティック検索が可能な大規模コーパス
• 会話履歴：検索可能なメッセージ履歴
• 共有ブロック：複数のエージェント間の連携

3. カスタムツール

ツールの作成については、custom-tools.md を参照してください。

• スキーマを自動生成するシンプルな関数ツール
• 環境変数のシークレットを使うツール
• 複雑なスキーマ向けの BaseTool クラス
• サンドボックス実行の要件

4. クライアント側ツール

ローカルでのツール実行については、client-side-tools.md を参照してください。

• エージェントを Letta API 上で実行しながら、ツールを自分のマシンで実行する
• Letta Code が Bash/Read/Write をローカルで実行する仕組み
• type: "tool" レスポンスを使用する承認ベースのフロー
• ローカルファイル、データベース、プライベート API へのアクセス

5. クライアントの注入とシークレット

サーバー側ツールのパターンについては、client-injection.md を参照してください。

• Letta Cloud で事前に注入される client 変数
• エージェントの状態を変更するカスタムメモリツールの構築
• os.getenv() によるエージェントのシークレット
• 自己参照型ツール向けの LETTA_AGENT_ID

6. 複数ユーザー向けのパターン

スケーリングについては、multi-user.md を参照してください。

• ユーザーごとに 1 つのエージェント（パーソナライズ）
• Conversations API を使う共有エージェント
• ユーザーコンテキスト用の ID システム

7. ストリーミング

リアルタイム応答については、streaming.md を参照してください。

• 基本的な SSE ストリーミング
• include_pings による長時間実行オペレーション
• バックグラウンド実行と再開可能なストリーム

8. 会話

会話を使うと、共有メモリを使用する並列セッションを実行できます。

• スレッドセーフな並行メッセージング（agents.messages.create はスレッドセーフではありません）
• すべての会話で共有されるメモリブロック
• 会話ごとに分かれたコンテキストウィンドウ
• 用途：同じユーザーが複数のタスクを並行して実行する場合、マルチスレッドアプリケーション

9. スリープタイムエージェント

バックグラウンドでのメモリ処理については、sleeptime.md を参照してください。

• enable_sleeptime=True で有効化
• バックグラウンドエージェントが会話の合間にメモリを改善します
• 時間の経過とともに学習するエージェントに適しています

10. エージェントのファイルとフォルダー

移植性とファイルアクセスについては、agent-files.md を参照してください。

• .af ファイルを使ったエージェントのエクスポート／インポート
• フォルダーを添付してエージェントがドキュメントにアクセスできるようにする
• エージェントを移行する際のチェックリスト

11. ツールルール

ツールの実行を制約する方法については、tool-rules.md を参照してください。

• InitToolRule - 最初に実行するツールを指定します
• ChildToolRule - 後続で使用できるツールを制御します
• TerminalToolRule - ツールの実行後にエージェントのターンを終了します
• 順次実行のパイプラインと承認ワークフロー

クイックリファレンス

Python SDK

pip install letta-client

from letta_client import Letta

# Cloud
client = Letta(api_key="LETTA_API_KEY")

# Self-hosted
client = Letta(base_url="http://localhost:8283")

TypeScript SDK

npm install @letta-ai/letta-client

import { Letta } from "@letta-ai/letta-client";

// Cloud
const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

// Self-hosted
const client = new Letta({ baseUrl: "http://localhost:8283" });

使用例

実行可能なコードについては、examples/ ディレクトリを参照してください。

Python：

• 01_basic_client.py - クライアントの初期化
• 02_create_agent.py - メモリブロックを使用したエージェントの作成
• 03_custom_tool_simple.py - 基本的なカスタムツール
• 04_custom_tool_secrets.py - 環境変数を使用するツール
• 05_send_message.py - 基本的なメッセージ送信
• 06_send_message_stream.py - ストリーミング応答
• 07_multi_user.py - マルチユーザーのパターン
• 08_archival_memory.py - アーカイブメモリの操作
• 09_shared_blocks.py - 複数エージェント間で共有するメモリ
• 10_conversations.py - 会話を使用した並列セッション
• 11_client_injection.py - クライアントを注入して使用するカスタムメモリツール
• 12_tool_rules.py - ツールの実行順序の制約
• 13_client_side_tools.py - ツールをローカルで実行（Letta Code のように）

TypeScript：

• 01_basic_client.ts - クライアントの初期化
• 02_create_agent.ts - エージェントの作成
• 03_send_message.ts - 基本的なメッセージ送信
• 04_send_message_stream.ts - ストリーミング
• 05_nextjs_singleton.ts - Next.js のパターン
• 06_multi_user.ts - マルチユーザーのパターン
• 07_conversations.ts - 並列セッション
• 08_custom_tool.ts - シークレットを使用するカスタムツール
• 09_archival_memory.ts - 長期ストレージ
• 10_shared_blocks.ts - 複数エージェント間で共有するメモリ
• 11_client_injection.ts - カスタムメモリツール
• 12_tool_rules.ts - ツールの実行順序
• 13_client_side_tools.ts - ツールをローカルで実行（Letta Code のように）

トラブルシューティング

エラー	原因	解決方法
401 Unauthorized	API キーが無効、または設定されていない	LETTA_API_KEY 環境変数を確認してください
422 Validation Error	必須フィールドが不足している	model、embedding、または memory_blocks を追加してください
ツールが見つからない	ツールがエージェントにアタッチされていない	client.agents.tools.attach(agent_id, tool_id)
os.getenv() が None を返す	シークレットが設定されていない	secrets パラメーターを使用してエージェントに追加してください
524 Timeout	ping を送信せずに長時間の操作を行っている	ストリーミングに include_pings=True を追加してください
エージェントが応答しない	モデルの問題、または応答が空	応答に assistant_message タイプが含まれているか確認してください
メモリブロックが更新されない	間違ったエージェントを確認している	agent_id が一致しているか確認してください
ツールでのインポートエラー	トップレベルでインポートしている	インポートを関数本体の中に移動してください

注意点

1. ツールでのインポートは関数内に記述してください - ツールはトップレベルのインポートにアクセスできないサンドボックス内で実行されます
2. シークレットには os.getenv() を使用してください - 機密データを関数の引数として渡さないでください
3. Cloud では注入された client を使用してください - ツール内で Letta() をインスタンス化せず、あらかじめ注入されたクライアントを使用してください
4. メモリブロックには文字数制限があります - 大量のデータにはアーカイブメモリを使用してください
5. 長時間の操作でストリーミングを使用する場合は include_pings=True が必要です - Cloud でのタイムアウトを防ぎます
6. SDK 1.0 では .modify() ではなく .update() を使用します - メソッド名が変更されました
7. LETTA_AGENT_ID は常に利用できます - 現在のエージェントを参照するため、ツール内で使用してください
8. アーカイブ用ツールには include_base_tools=True が必要です - デフォルトではアタッチされません
9. 共有ブロックには memory_insert を使用してください - 同時書き込みに対して最も安全です（追記のみ）
10. ツールの docstring には Args セクションが必要です - パラメーターの説明がないと、スキーマ生成に失敗します

TypeScript SDK の注意事項

// Client initialization uses baseURL (not baseUrl)
const client = new Letta({ apiKey: "...", baseURL: "http://localhost:8283" });

// Block API: positional args changed
client.agents.blocks.attach(blockId, { agent_id });      // blockId is first
client.agents.blocks.retrieve(blockLabel, { agent_id }); // label is first

// Passages.create returns array
const passages = await client.agents.passages.create(agentId, { text: "..." });
const passage = passages[0];

// Content can be string | array - use type guard
const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content);

// Conversations API returns streams by default
const stream = await client.conversations.messages.create(convId, { messages: [...] });
for await (const chunk of stream) { ... }

// Tool rule types
{ type: "run_first", tool_name: "..." }           // InitToolRule
{ type: "constrain_child_tools", tool_name: "...", children: [...] } // ChildToolRule  
{ type: "exit_loop", tool_name: "..." }           // TerminalToolRule

クイックリファレンス

# Client
client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Create agent
agent = client.agents.create(
    model="anthropic/claude-sonnet-4-5-20250929",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[{"label": "persona", "value": "..."}],
    include_base_tools=True,  # archival memory tools
    enable_sleeptime=True,    # background memory processing
)

# Send message
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello"}]
)

# Stream response
stream = client.agents.messages.stream(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello"}],
    stream_tokens=True,
    include_pings=True,  # prevent timeout
)

# Create tool
tool = client.tools.create(source_code="def my_tool(x: str) -> str: ...")
client.agents.tools.attach(agent_id=agent.id, tool_id=tool.id)

# Memory blocks
client.agents.blocks.retrieve(agent_id=agent.id, block_label="persona")
client.agents.blocks.update(agent_id=agent.id, block_label="persona", value="...")

# Folders
folder = client.folders.create(name="docs")
client.folders.files.upload(file=f, folder_id=folder.id)
client.agents.folders.attach(agent_id=agent.id, folder_id=folder.id)

# Conversations (parallel sessions)
conv = client.conversations.create(agent_id=agent.id)
stream = client.conversations.messages.create(conv.id, messages=[...])

# Agent secrets (for tools)
client.agents.update(agent_id=agent.id, secrets={"API_KEY": "..."})

リソース

プラットフォーム：

• Letta Cloud（ADE） - エージェント開発環境
• API キー - API キーを取得

ドキュメント：

• Letta ドキュメント - ドキュメント一式
• エージェントガイド - エージェントの概念
• メモリブロック - メモリアーキテクチャ
• カスタムツール - ツールの作成
• ストリーミング - リアルタイム応答
• マルチユーザー - スケーリングパターン

SDK：

• Python SDK - pip install letta-client
• TypeScript SDK - npm install @letta-ai/letta-client

サンプル：

• チャットボットのサンプル - アプリ全体のサンプル