Subagents

Fresh

Source: Letta Code Subagents

Overview

Subagents are specialized agents that a primary agent can spawn to handle complex tasks independently. By delegating work to focused subagents, the main agent maintains a clean context window and leverages parallelism.

How Subagents Work

1. The main agent launches subagents through the Task tool
2. The Task tool creates a new subagent via a Letta Code subprocess
3. The subagent operates autonomously with its own system prompt, tools, and model
4. Only the final message returns to the main agent -- preventing context pollution

Key Benefit

An explore subagent might consume hundreds of thousands of tokens reading numerous codebase files, yet the main agent receives only the final answer.

Execution Modes

Blocking (Default)

The subagent tool blocks until the task completes. The main agent waits for the result.

Background

Main agents can launch subagents in the background:

• The tool returns immediately
• The main agent receives automatic notification upon completion

Stateful Subagents

Built-in subagents typically are not reused between invocations. However, existing Letta Code agents can be deployed as subagents by specifying their agent_id, allowing them to leverage rich memories, personalities, and skillsets.

Built-in Subagents

Subagent	Purpose	Model	Access
explore	Codebase search and structure navigation	auto-fast	Read-only
fork	Inherit parent conversation with full context	inherit	Read/write
general-purpose	Complete implementation tasks	auto	Read/write
history-analyzer	Migrate conversation history to memory	auto	Read/write
memory	Reorganize memory blocks efficiently	auto	Read/write
init	Fast agent memory initialization	auto-fast	Read/write
recall	Search historical discussions	auto-fast	Read-only
reflection	Background memory consolidation	auto	Read/write

Creating Custom Subagents

Custom subagents are defined as Markdown files with YAML frontmatter.

File Structure

.letta/
  agents/
    my-subagent.md

Global subagents can be placed at ~/.letta/agents/ for cross-project availability.

Example: Security Reviewer

---
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 lowercase identifier starting with a letter
description	Yes	Usage guidance shown in Task tool
tools	No	Comma-separated tools or all (default: all)
model	No	haiku, sonnet, opus, etc. (default: inherit)
memoryBlocks	No	all, none, or specific list (default: all)
skills	No	Comma-separated auto-load skills

Access Levels

• explore: Read, Glob, Grep (search-only, no modifications)
• general-purpose: Bash, Edit, Write, Read, etc. (full implementation access)
• Omitting subagent_type defaults to general-purpose access

Override Rules

• Custom subagents override built-ins with identical names
• Project-level subagents override global ones
• Model and toolset are independent settings

Verification Checklist

• [ ] Subagent markdown file created with correct frontmatter
• [ ] File placed in .letta/agents/ (project) or ~/.letta/agents/ (global)
• [ ] Main agent can discover and invoke the subagent
• [ ] Subagent returns results to main agent
• [ ] Memory access level is appropriate for the task

See Also

• Agents - Agent creation and lifecycle
• Skills - Skill loading in subagents
• Headless Mode - Automated subagent invocation