YAML Schema

root_path: ./my-fleet
shared_blocks:
  - name: company_guidelines
    description: "Shared operational guidelines"
    limit: 5000
    from_file: "guidelines.md"

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

mcp_servers:
  - name: firecrawl
    type: sse
    server_url: "https://sse.firecrawl.dev"

agents:
  - name: my-agent
    # ... (see AgentConfig below)

llm_config:
  model: "google_ai/gemini-2.5-pro"
  context_window: 128000

# Inline
system_prompt:
  value: "You are a helpful assistant."

# From file
system_prompt:
  from_file: "prompts/system.md"

# From cloud storage
system_prompt:
  from_bucket:
    provider: supabase
    bucket: my-bucket
    path: "prompts/system.md"

# Skip Letta base instructions
system_prompt:
  from_file: "prompts/custom.md"
  disable_base_prompt: true

memory_blocks:
  # Agent can modify this block — YAML won't overwrite
  - 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 visual identity"
    limit: 3000
    from_file: "brand/guidelines.md"
    agent_owned: false
    version: "2.1.0"

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

tools:
  # Built-in tool 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/*"

mcp_servers:
  # SSE server
  - 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"]

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

mcp_tools:
  # Specific tools only
  - server: firecrawl
    tools: ["scrape", "crawl"]

  # All tools from this server (default)
  - server: filesystem

folders:
  - name: documentation
    files:
      # Local file
      - "docs/guide.md"

      # Glob pattern
      - "docs/*.txt"

      # Recursive glob
      - "knowledge/**/*.md"

      # Cloud storage
      - from_bucket:
          provider: supabase
          bucket: my-bucket
          path: "docs/important.pdf"

      # Cloud storage with glob
      - from_bucket:
          provider: supabase
          bucket: my-bucket
          path: "*.txt"

# Define at root level
shared_blocks:
  - name: company_policies
    description: "Company-wide policies all agents must follow"
    limit: 5000
    from_file: "policies.md"

  - name: safety_guidelines
    description: "Safety and compliance rules"
    limit: 3000
    value: "Never generate fake testimonials..."

agents:
  - name: agent-a
    # ... config ...
    shared_blocks:
      - company_policies
      - safety_guidelines

  - name: agent-b
    # ... config ...
    shared_blocks:
      - company_policies

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

agents:
  - name: agent-a
    shared_folders:
      - brand_assets

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

# Filter by tag
lettactl get agents --tags "tenant:acme-corp"
lettactl get agents --tags "role:support,env:production"

root_path: ./fleet

# ── Shared Resources ──────────────────────────

shared_blocks:
  - name: company_policies
    description: "Company-wide operational policies"
    limit: 5000
    from_file: "policies/company.md"
    version: "2.0.0"

  - name: safety_guidelines
    description: "AI safety and compliance rules"
    limit: 3000
    value: |
      Never generate fake testimonials.
      Never impersonate real people.
      Always disclose AI-generated content.

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

# ── MCP Servers ───────────────────────────────

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

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

# ── Agents ────────────────────────────────────

agents:
  - name: brand-researcher
    description: "Researches brands and builds customer profiles"
    tags:
      - "tenant:agency-123"
      - "role:research"

    llm_config:
      model: "google_ai/gemini-2.5-pro"
      context_window: 128000

    embedding: "openai/text-embedding-3-small"
    reasoning: true

    system_prompt:
      from_file: "prompts/researcher.md"
      disable_base_prompt: false

    first_message: "Initialize and confirm readiness."

    memory_blocks:
      - name: current_research
        description: "Active research findings"
        limit: 10000
        value: "No active research."
        agent_owned: true

      - name: research_methodology
        description: "How to conduct brand research"
        limit: 3000
        from_file: "docs/methodology.md"
        agent_owned: false
        version: "1.2.0"

    archives:
      - name: research_history
        description: "Past research findings"
        embedding: "openai/text-embedding-3-small"

    folders:
      - name: reference_docs
        files:
          - "reference/*.md"
          - "reference/**/*.txt"

    shared_blocks:
      - company_policies
      - safety_guidelines

    shared_folders:
      - brand_intelligence

    tools:
      - archival_memory_insert
      - archival_memory_search
      - "tools/*"

    mcp_tools:
      - server: firecrawl
        tools: ["scrape", "crawl"]

  - name: creative-director
    description: "Generates creative concepts and ad directions"
    tags:
      - "tenant:agency-123"
      - "role:creative"

    llm_config:
      model: "openai/gpt-4o"
      context_window: 128000

    system_prompt:
      from_file: "prompts/creative.md"

    memory_blocks:
      - name: brand_context
        description: "Current brand context and guidelines"
        limit: 8000
        value: "Awaiting brand assignment."
        agent_owned: true

      - name: creative_principles
        description: "Creative direction principles"
        limit: 2000
        from_file: "docs/creative-principles.md"
        agent_owned: false

    shared_blocks:
      - company_policies

    tools:
      - archival_memory_insert
      - archival_memory_search

# Always preview before applying
lettactl apply -f fleet.yaml --dry-run