letta-fleet-management

lettactl

Letta AI エージェント群を宣言的に管理する、kubectl スタイルの CLI です。

使用する場面

• 共通の構成で複数のエージェントをデプロイする
• エージェントのメモリブロック、ツール、フォルダーを管理する
• 既存のエージェントにテンプレートを適用する
• 本番環境へ昇格する前にカナリアデプロイを実行する
• マルチテナントのエージェント管理（B2B／B2B2C）
• エージェント群全体に一括でメッセージを送信する
• 環境間でエージェントをインポート／エクスポートする
• エージェントのメモリの健全性を分析する（自己診断）
• 初回メッセージのブートシーケンスでエージェントを調整する
• SDK によるプログラムからのエージェント群管理

基本的なワークフロー

1. fleet.yaml でエージェントを定義します
2. lettactl apply -f fleet.yaml で適用します
3. lettactl get agents と lettactl describe agent <name> で確認します

Fleet YAML の構造

shared_blocks:
  - name: company-context
    description: Shared company knowledge
    limit: 5000
    from_file: ./context/company.md

shared_folders:
  - name: brand_docs
    files:
      - "docs/*.md"

mcp_servers:
  - name: firecrawl
    type: sse
    server_url: "https://sse.firecrawl.dev"
    auth_header: "Authorization"
    auth_token: "Bearer ${FIRECRAWL_API_KEY}"

agents:
  - name: support-agent
    description: Customer support assistant
    tags:
      - "tenant:acme-corp"
      - "role:support"
    system_prompt:
      from_file: ./prompts/support.md
    llm_config:
      model: google_ai/gemini-2.5-pro
      context_window: 128000
    reasoning: true
    first_message: "Initialize and confirm readiness."
    memory_blocks:
      - name: persona
        description: Agent personality
        limit: 2000
        value: "You are a helpful support agent."
        agent_owned: true
    archives:
      - name: knowledge_base
        description: Long-term knowledge storage
    shared_blocks:
      - company-context
    shared_folders:
      - brand_docs
    tools:
      - send_email
      - search_docs
      - "tools/*"
    mcp_tools:
      - server: firecrawl
        tools: ["scrape", "crawl"]

完全なスキーマについては、reference/fleet-config.md を参照してください。

CLI コマンド

構成の適用

lettactl apply -f fleet.yaml                    # Create/update agents
lettactl apply -f fleet.yaml --dry-run          # Preview changes
lettactl apply -f fleet.yaml --match "*-prod"   # Template mode
lettactl apply -f fleet.yaml --canary           # Deploy canary copies
lettactl apply -f fleet.yaml --promote          # Promote canary to production
lettactl apply -f fleet.yaml --recalibrate      # Re-send calibration messages

リソースの確認

lettactl get agents                        # List all agents
lettactl get agents -o wide                # With details
lettactl get agents --tags "tenant:acme"   # Filter by tags
lettactl get blocks --shared               # Shared blocks only
lettactl get tools --orphaned              # Unused tools
lettactl describe agent <name>             # Full agent details

メッセージング

lettactl send <agent> "Hello"              # Send message
lettactl send <agent> "Hi" --stream        # Stream response
lettactl send --all "support-*" "Update"   # Bulk send by pattern
lettactl send --tags "role:support" "Hi"   # Bulk send by tags
lettactl messages list <agent>             # View history
lettactl messages reset <agent>            # Clear history
lettactl messages compact <agent>          # Summarize history

インポート／エクスポート

lettactl export agent <name> -f yaml       # Export single agent
lettactl export agents --all               # Export entire fleet
lettactl import agent-export.yaml          # Import agent

エージェント群のレポート

lettactl report memory                     # Memory usage report
lettactl report memory --analyze           # LLM-powered deep analysis

すべてのオプションについては、reference/cli-commands.md を参照してください。

カナリアデプロイ

本番環境へ昇格する前に、分離したコピーで変更をテストします。

lettactl apply -f fleet.yaml --canary           # Create CANARY-* copies
lettactl send CANARY-support-agent "test msg"   # Test the canary
lettactl apply -f fleet.yaml --promote          # Promote to production
lettactl apply -f fleet.yaml --cleanup          # Remove canary agents

reference/canary-deployments.md を参照してください。

マルチテナント

B2B および B2B2C のフィルタリング用に、エージェントにタグを付けます。

agents:
  - name: acme-support
    tags:
      - "tenant:acme-corp"
      - "role:support"
      - "env:production"

lettactl get agents --tags "tenant:acme-corp"
lettactl send --tags "tenant:acme-corp,role:support" "Policy update"

reference/multi-tenancy.md を参照してください。

自己診断

エージェント群全体のメモリの健全性を分析します。

lettactl report memory                  # Usage stats for all agents
lettactl report memory --analyze        # LLM-powered analysis per agent

使用率、古いデータ、重複、欠落している知識、分割に関する推奨事項をレポートします。詳しくは、reference/self-diagnosis.md を参照してください。

エージェントの調整

作成時にブートメッセージを使ってエージェントを初期化します。

agents:
  - name: support-agent
    first_message: "Review your persona and confirm you understand your role."

更新後に既存のエージェントを再調整します。

lettactl apply -f fleet.yaml --recalibrate
lettactl apply -f fleet.yaml --recalibrate --recalibrate-tags "role:support"

reference/agent-calibration.md を参照してください。

テンプレートモード

パターンに一致する既存のエージェントに構成を適用します。

lettactl apply -f template.yaml --match "*-draper"

3 ウェイマージを使用し、ユーザーが追加したリソースを保持しながら、管理対象のリソースを更新します。詳しくは、reference/template-mode.md を参照してください。

SDK の使用方法

import { LettaCtl } from 'lettactl';

const ctl = new LettaCtl({ lettaBaseUrl: 'http://localhost:8283' });

// Deploy from YAML
await ctl.deployFromYaml('./fleet.yaml');

// Programmatic fleet config
const config = ctl.createFleetConfig()
  .addSharedBlock({ name: 'kb', description: 'Knowledge', limit: 5000, from_file: 'kb.md' })
  .addAgent({
    name: 'support-agent',
    description: 'Support AI',
    system_prompt: { from_file: 'prompts/support.md' },
    llm_config: { model: 'google_ai/gemini-2.5-pro', context_window: 32000 },
    shared_blocks: ['kb'],
    tags: ['team:support'],
  })
  .build();

await ctl.deployFleet(config);

// Send message with callbacks
await ctl.sendMessage('agent-id', 'Hello', {
  onComplete: (run) => console.log('Done:', run.id),
});

// Template mode
await ctl.deployFromYaml('./template.yaml', { match: '*-prod' });

API の全容については、reference/sdk-usage.md を参照してください。