lettactl
Manage Letta AI agent fleets declaratively with kubectl-style CLI. Use when creating, updating, or managing multiple Letta agents with shared configurations, memory blocks, tools, and folders.
When & Why to Use This Skill
lettactl is a powerful, kubectl-style CLI and SDK designed for the declarative management of Letta AI agent fleets. It enables developers to define, deploy, and scale multiple AI agents using YAML configurations, ensuring consistency across shared memory blocks, tools, and system prompts. By treating AI agents as managed infrastructure, it simplifies complex workflows such as bulk updates, template application, and programmatic fleet orchestration, making it an essential tool for building production-grade agentic systems.
Use Cases
- Declarative Fleet Deployment: Define your entire AI agent infrastructure in a single fleet.yaml file and deploy it with a single command to ensure reproducible environments.
- Bulk Configuration Management: Update system prompts, LLM settings, or tool access across multiple agents simultaneously using pattern-matching templates and three-way merge logic.
- Automated Memory Orchestration: Programmatically manage and attach shared memory blocks to multiple agents to provide a unified context or company-wide knowledge base.
- CI/CD for AI Agents: Integrate the lettactl CLI or TypeScript SDK into DevOps pipelines to automate the lifecycle of AI agents from development to production.
- Fleet Observability: Use the CLI to monitor agent health, inspect context window usage, and manage message history across large-scale deployments.
| name | lettactl |
|---|---|
| description | Manage Letta AI agent fleets declaratively with kubectl-style CLI. Use when creating, updating, or managing multiple Letta agents with shared configurations, memory blocks, tools, and folders. |
| license | MIT |
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
- Programmatic fleet management via SDK
Core Workflow
- Define agents in
fleet.yaml - Apply with
lettactl apply -f fleet.yaml - Verify with
lettactl get agentsandlettactl describe agent <name>
Fleet YAML Structure
shared_blocks:
- name: company-context
description: Shared company knowledge
limit: 5000
from_file: ./context/company.md
agents:
- name: support-agent
description: Customer support assistant
system_prompt:
from_file: ./prompts/support.md
llm_config:
model: gpt-4o
context_window: 128000
memory_blocks:
- name: persona
description: Agent personality
limit: 2000
value: "You are a helpful support agent."
shared_blocks:
- company-context
tools:
- send_email
- search_docs
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 "*-draper" # Template mode
Inspect Resources
lettactl get agents # List all agents
lettactl get agents -o wide # With details
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 messages list <agent> # View history
lettactl messages reset <agent> # Clear history
Observability
lettactl health # Server connectivity
lettactl files <agent> # Attached files
lettactl context <agent> # Context window usage
See reference/cli-commands.md for all options.
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' });
await ctl.deployFromYaml('./fleet.yaml');
await ctl.deployFromYaml('./template.yaml', { match: '*-prod' });
See reference/sdk-usage.md for full API and reference/cli-commands.md for environment variables.