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 five subagent types:

explore — Fast codebase search (read-only)
general-purpose — Full implementation (can edit files)
memory — Clean up and reorganize memory blocks
plan — Break down complex tasks (read-only)
recall — Search conversation history (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 five 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

memory

A memory management agent that cleans up and reorganizes your agent’s memory blocks. It removes redundancy, adds structure, resolves contradictions, and improves scannability. Works with the defragmenting-memory skill for backup/restore workflows.

Uses a high-reasoning model (Opus) since memory reorganization requires careful judgment about what to keep, merge, or remove. Runs with elevated permissions to edit memory files directly.

Example prompts:

> Use a memory agent to clean up and reorganize my memory blocks
> Spawn a memory subagent to remove redundancy from the project block
> Have a memory agent restructure and consolidate my persona block

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

recall

A search agent for finding information in conversation history. It uses the searching-messages skill to locate past discussions, decisions, and context that may have fallen out of the main agent’s context window.

Uses a high-reasoning model (Opus) for thorough analysis of conversation history. Your agent will spawn recall subagents when it needs to remember what was discussed earlier.

Example prompts:

> Use a recall agent to find what we discussed about the database schema
> Have a recall subagent search for any decisions made about authentication
> Spawn a recall agent to find when we last talked about deployment

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

Refreshing the subagent list

If you or the agent modify custom subagents in .letta/agents/ during a session, the agent can refresh its subagent list:

> Refresh your subagents list

This re-discovers all subagents from both built-in types and custom definitions in .letta/agents/ directories. Restarting Letta Code will also refresh the subagent list.

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

Deploying existing agents

Instead of spawning a fresh subagent from a template, you can deploy an existing agent to work in your local codebase. This lets you leverage agents that have specialized memory, knowledge, or training.

How it works

Use the agent_id parameter to deploy an existing agent:

Task(
  agent_id="agent-abc123",
  subagent_type="explore",
  description="Find auth code",
  prompt="Find all authentication-related code in this codebase"
)

The deployed agent:

Keeps its own system prompt and memory blocks
Gets access to your local codebase via the tools you specify
Runs in a new conversation (or continues an existing one)

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.

Continuing conversations

Use conversation_id to resume from an existing conversation:

Task(
  conversation_id="conversation-xyz789",
  description="Continue implementation",
  prompt="Now implement the fix we discussed"
)

This is useful for:

Continuing context from a prior Task invocation
Following up on a conversation started via the messaging-agents skill

Deployed agents vs messaging

Deploy as subagent (Task tool with agent_id): The agent gets access to your local environment—it can read and write files, run commands, and make changes.

Message an agent (messaging-agents skill): The agent runs in its own environment. It can use its own tools and memory, but cannot access your local codebase.

Use deployment when you need the agent to work with your code. Use messaging when you just need information or answers from the agent.

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 recall when you need to find something from earlier in the conversation history
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