Subagents

Features

Stateless agents for task decomposition and parallel execution

Subagents are specialized, stateless agents that your main agent can spawn to handle complex tasks autonomously. Instead of doing everything in a single conversation, your agent can delegate work to focused subagents that run independently and return results.

Letta Code supports three subagent types:

explore — Fast codebase search (read-only)
general-purpose — Full implementation (can edit files)
plan — Break down complex tasks (read-only)

How it works

When your main agent encounters a complex task, it can use the Task tool to launch a subagent:

Task(
  subagent_type="explore",
  description="Find auth code",
  prompt="Search for all authentication-related files in src/. List paths and summarize the approach."
)

The subagent runs autonomously with its own system prompt, tools, and model. It returns a single final report when complete. Your main agent receives the results and continues.

Key characteristics:

Stateless: Each invocation is independent—no memory persists between calls
Autonomous: Subagents cannot ask questions mid-execution; all context must be provided upfront
Context-aware: Subagents see the full conversation history, so they understand what came before
Parallel: Launch multiple subagents concurrently for independent tasks

Built-in subagents

Letta Code includes three built-in subagents optimized for common workflows.

explore

A fast, lightweight agent for searching and understanding codebases. It can find files, search for patterns, and explore project structure—but it can’t make changes.

Uses a fast model (Haiku) to keep searches quick and cheap. Your agent will often spawn explore subagents when it needs to locate code before working on it.

Example prompts:

> Use an explore agent to find all database models
> Spawn an explore subagent to locate error handling code
> Have an explore agent map out the authentication flow

general-purpose

A full-capability agent that can research, plan, and implement. It has access to all tools including file editing, so it can actually make changes to your codebase.

Uses a balanced model (Sonnet) for good reasoning at reasonable cost. Your agent delegates here when it needs to implement something substantial.

Example prompts:

> Use a general-purpose agent to implement the password reset feature
> Spawn a general-purpose subagent to refactor the logging system
> Have a general-purpose agent add tests for the user module

plan

A planning agent that breaks down complex tasks into actionable steps. It explores the codebase and creates detailed implementation roadmaps—but doesn’t make changes itself.

Uses a high-reasoning model (Opus) to think through complex problems thoroughly. Expect detailed, structured output with step-by-step guidance.

Example prompts:

> Use a plan agent to design the user authentication system
> Have a plan subagent break down the migration to TypeScript
> Spawn a plan agent to architect the new notification system

Using subagents

Your agent automatically has access to subagents through the Task tool. You don’t need to configure anything—just describe your task and your agent will decide when to delegate.

You can also explicitly request subagent usage through prompting:

> Use the explore subagent to find all database connection code

Overriding the model

Each subagent type has a default model, but you can request a different one:

> Use a plan agent with Sonnet to design the migration
> Spawn an explore agent with Opus for a thorough codebase analysis
> Use a general-purpose agent with Haiku for this quick fix

Parallel execution

You can request multiple subagents to work simultaneously:

> Spawn two explore agents: one to search the frontend for React components,
  and another to find all API routes in the backend

Viewing available subagents

Use the /subagents command to see all available subagents (built-in and custom):

> /subagents

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

---
name: security-reviewer
description: Reviews code for security vulnerabilities and suggests fixes
tools: Glob, Grep, Read
model: sonnet-4.5
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-4.5`, `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

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/).

Using custom subagents

Once defined, request your custom subagent in natural language:

> Use the security-reviewer agent to review the authentication module
> Run security-reviewer on the entire src/api directory

When to use subagents

Good use cases:

Large codebase searches: “Find all places where we handle user authentication”
Planning before implementation: “Design an approach for migrating to a new database”
Parallel investigations: “Check both the frontend and backend for API endpoints”
Independent implementations: “Add logging to the payment processing module”

When NOT to use subagents:

Clarification needed: If you’re unsure what you want, work with the main agent interactively first
Simple, quick tasks: “Read the config file” doesn’t need a subagent
Step-by-step guidance needed: If you want to review each change, keep the main agent in control

Tips

Be specific upfront: Subagents can’t ask follow-up questions. Instead of “explore the auth code,” try “find all authentication-related files and summarize the auth flow”
Request specific outputs: Tell the subagent what you want back. “List all API endpoints with their HTTP methods and paths” is clearer than “find the API endpoints”
Create custom subagents for your workflow: If you frequently do security reviews, migrations, or other specialized tasks, create a custom subagent

For agents

Guidelines for AI agents using the Task tool:

When to use subagents vs direct tools:

Use explore when you need to search before you know what files to read
Use direct tools (Read, Grep, Glob) when you already know the target
Use plan for complex tasks where you need a roadmap before implementing
Use general-purpose for substantial implementation work you want to delegate

Writing effective prompts:

Front-load context—subagents can’t ask clarifying questions
Be specific about what output format you need (list, table, prose)
For explore tasks, ask for file paths and line numbers so you can follow up
Include relevant conversation context if the subagent needs it

Parallel execution:

Safe: Multiple explore/plan subagents (read-only)
Safe: Multiple subagents editing different files
Risky: Multiple subagents editing the same file—avoid this
Launch parallel tasks in a single response when work is independent