Letta Code Agents

Deploy Letta Cloud agents with git-backed MemFS, agent-owned skills, and Letta Code secrets. This is the recommended shape for agents that should execute from skills instead of registered custom tools.

Overview

lettactl can sync a Cloud agent's memory filesystem during apply. Use a small system MemFS template for routing and durable operating notes, then attach focused skill directories for executable behavior. Secrets are synced separately to Letta agent state so tokens do not need to live in git.

Fleet YAML

Set memory.mode to memfs. template_dir copies a full directory into the agent's MemFS. files entries add explicit from_file or inline value content. Prefer from_file for tracked markdown. skills entries copy directories that contain SKILL.md into skills/<name>. Use preserve_existing_paths for mutable files that should be seeded once and then preserved. Set prune_missing_skills when memory.skills is the managed skill catalog and stale skill files should be deleted on deploy. Agent secrets override globals and are redacted from output.

global-secrets:
  APP_API_BASE:
    value: https://app.example.com

agents:
  - name: code-agent
    description: "Cloud agent with MemFS skills"
    llm_config:
      model: "letta/glm"
      context_window: 32000
    system_prompt:
      value: "Use the memory filesystem and skills to complete user requests."
    include_base_tools: false
    include_base_tool_rules: false
    memory:
      mode: memfs
      bare_repo: auto
      template_dir: agents/code-agent/memfs
      preserve_existing_paths:
        - system/persona.md
        - system/state.md
      prune_missing_skills: true
      files:
        - to: system/important_variables.md
          from_file: agents/code-agent/memfs/system/important_variables.md
          template_vars:
            COMPANY_ID: company-123
      skills:
        - name: app-api
          from_dir: agents/skills/app-api
        - name: reporting
          from_dir: agents/skills/reporting
    secrets:
      APP_AGENT_TOKEN:
        from_env: APP_AGENT_TOKEN
        preserve_existing: true

Managed Skill Pruning

By default, lettactl adds and updates skill files but preserves remote skill files that are not in the current template. This protects agent-authored or manually copied skills. If memory.skills is your app-managed skill catalog, set memory.prune_missing_skills: true so apply reconciles configured skills exactly and deletes stale skills/<name> files that disappeared from the template.

agents:
  - name: code-agent
    memory:
      mode: memfs
      prune_missing_skills: true
      skills:
        - name: saved-asset-recall
          from_dir: agents/skills/saved-asset-recall
        - name: preference-learning
          from_dir: agents/skills/preference-learning

Base Tools

MemFS agents default to include_base_tools: false and include_base_tool_rules: false. This keeps Letta Code agents on an explicit server-tool allowlist while skills and the sandbox handle domain behavior. Classic block agents keep base tools enabled by default for backward compatibility. To opt a MemFS agent into server tools, set include_base_tools: true and list the tools you want, such as conversation_search.

agents:
  - name: code-agent
    include_base_tools: true
    tools:
      - conversation_search
    memory:
      mode: memfs

MemFS Layout

Keep system files short. A useful pattern is one router file under system/ that tells the agent when to open each skill. The skill descriptions are also loaded into context, so avoid duplicating detailed procedure text in both places.

agents/code-agent/memfs/
  system/
    router.md

agents/skills/app-api/
  SKILL.md
  scripts/
    get-user.sh
    create-report.sh

Skill Shape

Put the decision rules and API contract in SKILL.md. Put exact curl calls in executable shell scripts when the command is reusable. For agent efficiency, keep scripts comment-free and keep SKILL.md focused on when to use the skill, required inputs, and expected outputs.

---
name: app-api
description: Call the application API with the agent service account.
---

Use this skill when a user asks for application data or wants an application action performed.

Required secrets:
- APP_API_BASE
- APP_AGENT_TOKEN

Scripts:
- scripts/get-user.sh <user_id>
- scripts/create-report.sh <account_id>

Secret Sync

Use global-secrets for values every agent can share, such as API base URLs. Use agents[].secrets for identity or authorization values that belong to one agent. preserve_existing keeps the current remote value if the referenced environment variable is unset during deploy.

export APP_AGENT_TOKEN=service-account-token
lettactl apply -f fleet.yaml --dry-run
lettactl apply -f fleet.yaml --root .

Migration Guidance

For Letta Code agents, prefer skills over registered custom tools. Keep durable routing and memory in system MemFS files. Move task procedures, API call instructions, and small executable helpers into skills. Keep existing battle-tested prompt text intact if it already performs well; only move the wrapper knowledge needed to discover and call it.