Lifecycle

Create, update, and delete agents and resources.

create conversation

Create a new conversation for an agent. Conversations provide isolated message histories while sharing the agent's archival memory, blocks, and tools. For declarative workflows, you can also declare conversations in your fleet YAML — they are created automatically on `lettactl apply` and matched by summary on re-apply.

lettactl create conversation <agent>

Examples

lettactl create conversation my-agent

# In fleet.yaml:
# conversations:
#   - summary: "Ticket #101"
#   - summary: "Ticket #102"
lettactl apply -f fleet.yaml

Notes

Conversations can also be declared in YAML under agents[].conversations with a required `summary` field.

YAML conversations are idempotent — re-applying won't create duplicates (matched by summary).

Use `isolated_blocks` to create per-conversation copies of named memory blocks.

create agent

Create a new agent directly from CLI flags without a YAML file.

lettactl create agent <name> [options]

Options

Flag	Type	Description
--description	string	Agent description
--model	string	LLM model identifier
--system	string	System prompt text
--context-window	number	Context window size in tokens
--embedding	string	Embedding model
--timezone	string	Agent timezone
--tags	string	Comma-separated tags
--tools	string	Comma-separated tool names
--memory-blocks	string	Memory block definitions

Examples

lettactl create agent my-agent \
  --description 'Test agent' \
  --model 'openai/gpt-4o' \
  --system 'You are a helpful assistant.'

update agent

Modify an existing agent's configuration.

lettactl update agent <name> [options]

Options

Flag	Type	Description
--name	string	New name
--description	string	New description
--model	string	New LLM model
--system	string	New system prompt
--context-window	number	New context window size
--add-tool	string	Add a tool
--remove-tool	string	Remove a tool
--tags	string	Replace tags

Examples

lettactl update agent my-agent --model 'openai/gpt-4o-mini'

lettactl update agent my-agent --add-tool archival_memory_search

delete

Delete a specific resource by name.

lettactl delete <resource> <name> [options]

Options

Flag	Type	Description
--force	boolean	Skip confirmation prompt

Examples

lettactl delete agent my-agent

lettactl delete agent my-agent --force

Notes

Deleting an agent cascades to all its conversations.

delete-all

Bulk delete resources matching a pattern. Preserves shared resources used by other agents.

lettactl delete-all <resource> [options]

Options

Flag	Type	Description
--pattern	string	Regex pattern to match resource names
--force	boolean	Actually delete (required to confirm)

Examples

lettactl delete-all agents --pattern 'test-.*'

lettactl delete-all agents --pattern 'test-.*' --force

cleanup

Remove orphaned resources (blocks, folders, archives) not attached to any agent. Dry-run by default.

lettactl cleanup <resource> [options]

Options

Flag	Type	Description
--force	boolean	Actually delete orphans (default is dry-run)

Examples

lettactl cleanup all

lettactl cleanup blocks --force

Notes

Resources: blocks, folders, archives, all