Subagents

Subagents are specialized agents that your main agent can spawn to handle complex tasks autonomously. By delegating work to focused subagents, your main agent can keep its context window clean and make use of parallelism to divide and conquer tasks.

Letta Code includes seven built-in subagent types optimized for common workflows, and you can create custom subagents for specialized tasks.

How it works

Your main agent can launch subagents using a specialized subagent (“Task”) tool. When the subagent tool is called, a new (sub)agent is created via a subprocess of Letta Code.

The subagent runs autonomously with its own system prompt, tools, and model. The final message from the subagent is returned to the main agent, which keeps the main agent’s context clean.

For example, if the main agent wants to understand where a certain function is located in the codebase, it can launch an explore subagent. The explore subagent may use hundreds of thousands of tokens to read hundreds of files, but the main agent will only see the final answer - saving the main agent from unnecessary context “pollution” from tool calls and returns.

Background subagents

By default, when your main agent launches a subagent, the subagent tool does not return until the subagent is finished working. However, your main agent can also choose to launch subagents in the background.

If a subagent is launched in the background, the subagent tool returns immediately (letting the main agent know the subagent was successfully launched), and the main agent gets automatically notified / triggered once the subagent has completed execution.

Launching stateful agents as subagents

By default, the built-in subagents are not reused - they are created fresh on each invocation.

It is also possible to deploy an arbitrary Letta Code agent as a subagent by specifying its agent_id. This lets your main agent “teleport” other agents that carry their own rich memories, personalities, and skillsets into your Letta Code instance and read/write/edit code.

To deploy an existing agent as a subagent, your main agent simply needs to know its agent ID (both agents must exist in the same Letta API org/project):

> I have another agent that's an expert at web design. Can you ask them to review your changes? Their agent ID is ...

If you don’t remember their agent ID, your main agent can also use the built-in “finding agents” skill to find them:

> Can you ask my other agent "Dora Designer" to review this PR as a subagent? I forgot their agent ID though.

Built-in subagents

Each subagent has a recommended model, but Letta Code now resolves built-in subagents to auto or auto-fast by default when available. You can still override the model with prompting (for example, Spawn an explore agent with Opus).

Subagent	Purpose	Recommended model	Access
explore	Fast codebase search - find files, search patterns, explore structure	auto-fast	Read-only
general-purpose	Full implementation - research, plan, and make changes	auto	Read/write
history-analyzer	Migrate conversation history from Claude Code or Codex into memory	auto	Read/write
memory	Clean up and reorganize memory blocks - remove redundancy, add structure	auto	Read/write
init	Fast initialization of agent memory from the current project	auto-fast	Read/write
recall	Search conversation history for past discussions and decisions	auto-fast	Read-only
reflection	Background “sleep-time” memory consolidation from recent conversations	auto	Read/write

Creating custom subagents

Create custom subagents by adding Markdown files with YAML frontmatter to the .letta/agents/ directory.

File structure

.letta/
└── agents/
    └── my-subagent.md

You can also create global subagents at ~/.letta/agents/ that are available across all projects.

Subagent file format

Custom subagent .md files can use Unix or Windows line endings. UTF-8 BOM-prefixed frontmatter is also supported.

.letta/agents/security-reviewer.md

---
name: security-reviewer
description: Reviews code for security vulnerabilities and suggests fixes
tools: Glob, Grep, Read
model: sonnet
memoryBlocks: human, persona
---

You are a security code reviewer.

## Instructions

- Search for common vulnerability patterns (SQL injection, XSS, etc.)
- Check authentication and authorization code
- Review input validation
- Identify hardcoded secrets or credentials

## Output Format

1. List of findings with severity (critical/high/medium/low)
2. File paths and line numbers for each issue
3. Recommended fixes

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier (lowercase, hyphens allowed). Must start with a letter.
description	Yes	When to use this subagent (shown in Task tool and /subagents)
tools	No	Comma-separated list of allowed tools, or all. Defaults to all.
model	No	Model to use (e.g., haiku, sonnet, opus). Defaults to inheriting from main agent.
memoryBlocks	No	Which memory blocks the subagent can access: specific list, all, or none. Defaults to all.
skills	No	Comma-separated list of skills to auto-load

Model and toolset behavior

For the main interactive agent, switching models with /model can automatically switch toolsets when toolset mode is auto (see Models and Toolsets).

For subagents, model and tools are configured independently:

• model selects which model the subagent runs on.
• tools defines which tools the subagent is allowed to use.
• Deployment access level (subagent_type such as explore or general-purpose) also constrains tool access.

Changing a subagent’s model does not automatically change its configured tools.

System prompt

The body of the Markdown file (after the frontmatter) becomes the subagent’s system prompt. Write clear instructions for what the subagent should do and how it should format its output.

Override priority

Custom subagents override built-ins with the same name. Project-level subagents (.letta/agents/) override global ones (~/.letta/agents/).

Access levels

Use subagent_type to control what tools the deployed agent can access:

Access Level	Tools	Use Case
explore	Read, Glob, Grep	Safer for exploration—agent can search but not modify
general-purpose	Bash, Edit, Write, Read, etc.	Full access for implementation tasks

If subagent_type is omitted, it defaults to general-purpose.