letta-development-guide

Letta 開発ガイド

適切なアーキテクチャ、メモリ構成、モデル選択、ツール設定を用いて、効果的な Letta エージェントを設計・構築するための包括的なガイドです。

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

以下の場合にこのスキルを使用します：

• 新しい Letta エージェントプロジェクトを始めるとき
• エージェントアーキテクチャ（letta_v1_agent と memgpt_v2_agent）を選択するとき
• メモリブロックの構造とアーキテクチャを設計するとき
• 用途に適したモデルを選択するとき
• ツール構成を計画するとき
• メモリ管理とパフォーマンスを最適化するとき
• エージェント間で共有メモリを実装するとき
• メモリ関連の問題をデバッグするとき

クイックスタートガイド

最小限の動作例

from letta_client import Letta

client = Letta()
agent = client.agents.create(
    name="my-assistant",
    model="openai/gpt-4o",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant."},
        {"label": "human", "value": "The user's name and preferences."},
    ],
)

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

1. アーキテクチャの選択

letta_v1_agent を使用する場合：

• 新しいエージェントを構築するとき（推奨されるデフォルト）
• 推論モデル（GPT-4o、Claude Sonnet 4）との互換性が必要なとき
• シンプルなシステムプロンプトと直接的なメッセージ生成を求めるとき

memgpt_v2_agent を使用する場合：

• レガシーエージェントを保守するとき
• v1 ではまだサポートされていない特定のツールパターンが必要なとき

詳しい比較については、references/architectures.md を参照してください。

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

メモリは効果的なエージェントの基盤です。Letta では、次の 3 種類のメモリが提供されています。

コアメモリ（コンテキスト内）：

• エージェントのコンテキストウィンドウから常にアクセスできます
• 用途：現在の状態、アクティブなコンテキスト、頻繁に参照する情報
• 上限：コアメモリの合計をコンテキストウィンドウの 80% 未満に保ちます

アーカイブメモリ（コンテキスト外）：

• ベクターデータベースを使用したセマンティック検索
• 用途：過去の記録、大規模なナレッジベース、過去のやり取り
• アクセス：エージェントが archival_memory_search を明示的に呼び出す必要があります
• 注意：コンテキストのオーバーフローから自動的に取り込まれることはありません

会話履歴：

• 現在の会話における過去のメッセージ
• conversation_search ツールを使って取得します
• 用途：以前の議論の参照、会話の流れの追跡

詳しいガイダンスについては、references/memory-architecture.md を参照してください。

3. メモリブロックの設計

基本原則： 機能単位ごとにブロックを 1 つ作成します。

必須ブロック：

• persona：エージェントのアイデンティティ、行動指針、機能
• human：ユーザーの情報、好み、コンテキスト

用途に応じてドメイン固有のブロックを追加します：

• カスタマーサポート：company_policies、product_knowledge、customer
• コーディングアシスタント：project_context、coding_standards、current_task
• パーソナルアシスタント：schedule、preferences、contacts

メモリブロックのガイドライン：

• ブロックの焦点を絞り、目的を明確にします
• 明確で、指示として機能する説明を使用します
• サイズ制限（通常はブロックあたり 2000～5000 文字）を確認します
• エージェント間でメモリを共有する場合は、追記操作を前提に設計します

ドメイン別の例については references/memory-patterns.md を、効果的な説明文の作成については references/description-patterns.md を参照してください。

4. モデルの選択

モデルの機能をエージェントの要件に合わせます。

本番環境のエージェント向け：

• 複雑な推論には GPT-4o または Claude Sonnet 4
• コスト効率の高い一般タスクには GPT-4o-mini
• 高速で軽量な処理には Claude Haiku 3.5
• 速度と機能のバランスには Gemini 2.0 Flash

本番環境では避けるモデル：

• 小型の Ollama モデル（<7B パラメーター）：ツール呼び出しの性能が低い
• 信頼性の高い関数呼び出しに対応していないモデル

詳しいガイダンスについては、references/model-recommendations.md を参照してください。

5. ツールの設定

最小限から始めます： エージェントが実際に使用するツールのみを追加します。

一般的な開始構成：

• メモリツール（memory_insert、memory_replace、memory_rethink）：ほとんどのエージェントに不可欠です
• ファイルシステムツール：フォルダーを接続すると自動的に追加されます
• カスタムツール：ドメイン固有の操作（データベース、API など）に使用します

ツールルール： 必要に応じて、実行順序を強制するために使用します（例：「回答の前に必ず検索を呼び出す」）。

一般的な構成については、references/tool-patterns.md を参照してください。

高度なトピック

メモリサイズの管理

文字数制限に近づいている場合：

1. トピックごとに分割する： customer_profile → customer_business、customer_preferences
2. 時間ごとに分割する： interaction_history → recent_interactions。古いデータはアーカイブメモリに移動します
3. 過去のデータをアーカイブする： 古い情報をアーカイブメモリに移動します
4. memory_rethink で統合する： 要約してブロックを書き換えます

戦略については、references/size-management.md を参照してください。

並行処理のパターン

複数のエージェントがメモリブロックを共有する場合や、エージェントが並行リクエストを処理する場合：

最も安全な操作：

• memory_insert：追記のみのため、競合状態が最小限です
• データベースでは PostgreSQL の行レベルロックを使用します

競合状態のリスク：

• memory_replace：書き込み前に対象の文字列が変更される可能性があります
• memory_rethink：後から書き込んだ内容が優先され、マージされません

ベストプラクティス：

• 可能な限り、追記操作を前提に設計します
• 並行書き込みには memory_insert を使用します
• memory_rethink は、単一エージェントが排他的にアクセスできる場合に使用します

詳細なパターンについては、references/concurrency.md を参照してください。

検証チェックリスト

エージェント設計を確定する前に、次の点を確認してください。

アーキテクチャ：

• アーキテクチャはモデルの能力に合っていますか？
• モデルは、想定されるワークロードとレイテンシ要件に適していますか？

メモリ：

• コアメモリの合計はコンテキストウィンドウの 80% 未満ですか？
• 各ブロックは、1 つの機能領域に焦点を当てていますか？
• 説明には、いつ読み取り／書き込みを行うかが明確に記載されていますか？
• サイズの増加と容量超過への対策を計画していますか？
• マルチエージェントの場合、並行処理のパターンを考慮していますか？

ツール：

• ツールは必要で、適切に設定されていますか？
• 効果的な更新ができるよう、メモリブロックは十分に細分化されていますか？

よくあるアンチパターン

メモリブロックが少なすぎる：

# Bad: Everything in one block
agent_memory: "Agent is helpful. User is John..."

代わりに、用途ごとにブロックを分割してください。

メモリブロックが多すぎる： 3～4 個で十分な場合に、10 個以上のブロックを作成します。最小限から始め、必要に応じて拡張してください。

説明が不十分：

# Bad
data: "Contains data"

代わりに、具体的な指針を示してください。references/description-patterns.md を参照してください。

サイズ制限を無視する： ブロックを制限に達するまで無制限に増大させます。事前に監視し、管理してください。

実装手順

1. 設計フェーズ

• 要件に基づいてアーキテクチャを選択します
• メモリブロックの構造を設計します
• 適切なモデルを選択します
• ツールの設定を計画します

2. 作成フェーズ（SDK）

Python：

from letta_client import Letta

client = Letta()  # Uses LETTA_API_KEY env var

# Create agent with custom memory blocks
agent = client.agents.create(
    name="my-agent",
    model="openai/gpt-4o",  # or "anthropic/claude-sonnet-4-20250514"
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant..."},
        {"label": "human", "value": "User preferences and context..."},
        {"label": "project", "value": "Current project details..."},
    ],
    description="Agent for helping with X",
)
print(f"Created agent: {agent.id}")

TypeScript：

import Letta from "letta-client";

const client = new Letta();

const agent = await client.agents.create({
  name: "my-agent",
  model: "openai/gpt-4o",
  embedding: "openai/text-embedding-3-small",
  memoryBlocks: [
    { label: "persona", value: "You are a helpful assistant..." },
    { label: "human", value: "User preferences and context..." },
    { label: "project", value: "Current project details..." },
  ],
  description: "Agent for helping with X",
});
console.log(`Created agent: ${agent.id}`);

注： Letta Code CLI（letta コマンド）を使用すると、対話形式でエージェントを作成できます。letta --new-agent で新規作成を開始し、次に /rename と /description で設定します。

3. テストフェーズ

• 代表的なクエリでテストします
• メモリツールの使用パターンを監視します
• ツール呼び出しの動作を検証します

4. 反復フェーズ

• 実際の使用状況に基づいてメモリブロックの構造を改善します
• システム指示を最適化します
• ツールの設定を調整します

参考資料

各トピックの詳細については、参考資料を参照してください。

• references/architectures.md - アーキテクチャの比較と選択
• references/memory-architecture.md - メモリの種類と使い分け
• references/memory-patterns.md - ドメイン固有のメモリブロックの例
• references/description-patterns.md - 効果的なブロックの説明の書き方
• references/size-management.md - メモリブロックのサイズ制限の管理
• references/concurrency.md - マルチエージェントでのメモリ共有パターン
• references/model-recommendations.md - モデル選択の指針
• references/tool-patterns.md - よく使われるツール設定