2474 Fleet Config Ee28fcec

Fleet Configuration Reference

Complete YAML schema for lettactl fleet configuration.

Top-Level Structure

root_path: ./my-fleet     # Optional: base dir for relative paths
shared_blocks: []          # Optional: blocks shared across agents
shared_folders: []         # Optional: folders shared across agents
mcp_servers: []            # Optional: MCP server configs
agents: []                 # Required: agent definitions

Agent Definition

agents:
  - name: agent-name                    # Required: unique name ([a-zA-Z0-9_-]+)
    description: Agent description      # Required

    system_prompt:                      # Required
      value: "Inline prompt"            # Option 1
      from_file: ./prompt.md            # Option 2
      from_bucket:                      # Option 3
        provider: supabase
        bucket: prompts
        path: agent/system.md
      disable_base_prompt: false        # Skip Letta base instructions

    llm_config:                         # Required
      model: google_ai/gemini-2.5-pro   # provider/model-name format
      context_window: 128000            # 1,000 - 200,000
      max_tokens: 4096                  # Optional: max output tokens

    embedding: openai/text-embedding-3-small  # Optional (default)
    embedding_config: {}                      # Optional: additional settings
    reasoning: true                           # Optional: chain-of-thought (default: true)
    first_message: "Boot message"             # Optional: sent on first creation only

    tags: []                            # Optional: key:value strings for filtering
    memory_blocks: []                   # Optional: agent-specific blocks
    archives: []                        # Optional: vector-searchable memory (max 1)
    shared_blocks: []                   # Optional: references to shared_blocks
    shared_folders: []                  # Optional: references to shared_folders
    folders: []                         # Optional: file folders for RAG
    tools: []                           # Optional: tool names, objects, or globs
    mcp_tools: []                       # Optional: tools from MCP servers

Memory Blocks

Agent-specific memory blocks with ownership semantics:

memory_blocks:
  # Agent can modify this block — YAML won't overwrite on apply
  - name: user_preferences
    description: "What I know about the user"
    limit: 5000
    value: "No preferences yet."
    agent_owned: true

  # YAML controls this block — syncs on every apply
  - name: brand_guidelines
    description: "Brand voice and identity"
    limit: 3000
    from_file: "brand/guidelines.md"
    agent_owned: false
    version: "2.1.0"

Shared Blocks

shared_blocks:
  - name: company-knowledge
    description: Company policies and procedures
    limit: 10000
    from_file: ./context/company.md
    version: "2.0.0"

Define at root level, attach by name in agents via shared_blocks: [name].

Shared Folders

shared_folders:
  - name: brand_assets
    files:
      - "brand/*.md"
      - from_bucket:
          provider: supabase
          bucket: assets
          path: "brand/*.pdf"

Define at root level, attach by name in agents via shared_folders: [name].

Archives

Vector-searchable long-term memory. Max one per agent.

archives:
  - name: knowledge_base
    description: "Long-term knowledge storage"
    embedding: "openai/text-embedding-3-small"

Tools

Reference built-in tools by name, custom tools by path, or auto-discover from a directory:

tools:
  # Built-in by name
  - archival_memory_insert
  - archival_memory_search

  # Custom tool from cloud storage
  - name: "web_search"
    from_bucket:
      provider: supabase
      bucket: tools
      path: "web_search.py"

  # Auto-discover all .py files in tools/ directory
  - "tools/*"

Inline Tool Definition

tools:
  - name: search_docs
    description: Search documentation
    source_code: |
      def search_docs(query: str) -> str:
          """Search the documentation."""
          return f"Results for: {query}"

MCP Servers

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

  # Stdio server
  - name: filesystem
    type: stdio
    command: npx
    args: ["-y", "@anthropic/mcp-server-filesystem", "/tmp"]
    env:
      NODE_ENV: production

  # Streamable HTTP
  - name: custom-api
    type: streamable_http
    server_url: "https://api.example.com/mcp"
    custom_headers:
      X-Api-Version: "2"

Types: sse, stdio, streamable_http. Auth fields: auth_header, auth_token, custom_headers.

MCP Tool Selection

Select which tools from an MCP server an agent can use:

mcp_tools:
  - server: firecrawl
    tools: ["scrape", "crawl"]    # Specific tools only
  - server: filesystem             # All tools (default)

Tags

Tags enable multi-tenancy and filtering. Format: key:value.

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

lettactl get agents --tags "tenant:acme-corp"
lettactl send --tags "role:support,env:production" "Update"

Tags use AND logic — all specified tags must match.

Folders

File collections for RAG. Supports local files, globs, and cloud storage:

folders:
  - name: documentation
    files:
      - "docs/guide.md"
      - "docs/*.txt"
      - "knowledge/**/*.md"
      - from_bucket:
          provider: supabase
          bucket: my-bucket
          path: "docs/*.pdf"

FromBucket (Cloud Storage)

from_bucket:
  provider: supabase       # Currently only supabase
  bucket: bucket-name
  path: file/path.md       # Supports glob patterns

Used by: system prompts, memory blocks, shared blocks, folders, tools.

File Source Priority

When multiple sources specified: from_bucket > from_file > value.

Variable Interpolation

Environment variables are expanded:

agents:
  - name: ${AGENT_NAME:-default-agent}
    llm_config:
      model: ${MODEL_NAME}

Defaults

Validation Rules

• Unique agent names ([a-zA-Z0-9_-]+)
• Reserved names: agents, blocks, archives, tools, folders, files, mcp-servers, archival
• Unique block names within an agent
• Max 1 archive per agent
• Single content source per prompt/block (value, from_file, or from_bucket)
• Context window: 1,000–200,000
• Tags: no commas, non-empty strings
• Strict validation — unknown fields rejected