lettactl

kubectl-style CLI for managing Letta AI agent fleets declaratively.

When to Use

Deploying multiple agents with shared configurations
Managing agent memory blocks, tools, and folders
Applying templates to existing agents
Running canary deployments before promoting to production
Multi-tenant agent management (B2B / B2B2C)
Bulk messaging across agent fleets
Importing/exporting agents between environments
Analyzing agent memory health (self-diagnosis)
Calibrating agents with first-message boot sequences
Programmatic fleet management via SDK

Core Workflow

Define agents in fleet.yaml
Apply with lettactl apply -f fleet.yaml
Verify with lettactl get agents and lettactl describe agent <name>

Fleet YAML Structure

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"]

See reference/fleet-config.md for full schema.

CLI Commands

Apply Configuration

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

Inspect Resources

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

Messaging

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

Import / Export

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

Fleet Reporting

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

See reference/cli-commands.md for all options.

Canary Deployments

Test changes on isolated copies before promoting to production:

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

See reference/canary-deployments.md.

Multi-Tenancy

Tag agents for B2B and B2B2C filtering:

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"

See reference/multi-tenancy.md.

Self-Diagnosis

Analyze agent memory health fleet-wide:

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

Reports fill percentages, stale data, redundancy, missing knowledge, and split recommendations. See reference/self-diagnosis.md.

Agent Calibration

Prime agents on creation with a boot message:

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

Recalibrate existing agents after updates:

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

See reference/agent-calibration.md.

Template Mode

Apply configuration to existing agents matching a pattern:

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

Uses three-way merge: preserves user-added resources while updating managed ones. See reference/template-mode.md.

SDK Usage

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' });

See reference/sdk-usage.md for full API.

letta-fleet-management