> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

<video autoPlay loop muted playsInline style={{width: '100%', borderRadius: '12px'}}>
  <source src="https://mintcdn.com/firebendercorp/kmwsVzudSKNt8Ope/assets/subagents-demo.webm?fit=max&auto=format&n=kmwsVzudSKNt8Ope&q=85&s=52637a82b8342736a09795183224445a" type="video/webm" data-path="assets/subagents-demo.webm" />
</video>

Subagents are specialized AI assistants that Firebender's agent can delegate tasks to. Each subagent operates in its own context window, handles specific types of work, and returns its result to the parent agent. Use subagents to break down complex tasks, do work in parallel, and preserve context in the main conversation.

<div className="subagents-card-grid">
  <CardGroup cols={2}>
    <Card title="Context isolation" icon="layer-group">
      Each subagent has its own context window. Long research or exploration tasks do not consume space in your main conversation.
    </Card>

    <Card title="Parallel execution" icon="shuffle">
      Launch multiple subagents simultaneously. Work on different parts of your codebase without waiting for sequential completion.
    </Card>

    <Card title="Specialized expertise" icon="brain">
      Configure subagents with custom prompts, tool access, and models for domain-specific tasks.
    </Card>

    <Card title="Reusability" icon="arrows-rotate">
      Define custom subagents and use them across projects.
    </Card>
  </CardGroup>
</div>

## How subagents work

When Firebender encounters a complex task, it can launch a subagent automatically. The subagent receives a prompt with the necessary context, works autonomously, and returns a final message with its results.

Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents do not have access to prior conversation history.

## Foreground vs background

Subagents run in one of two modes:

| Mode       | Behavior                                                             | Best for                                    |
| ---------- | -------------------------------------------------------------------- | ------------------------------------------- |
| Foreground | Blocks until the subagent completes. Returns the result immediately. | Sequential tasks where you need the output. |
| Background | Returns immediately. The subagent works independently.               | Long-running tasks or parallel workstreams. |

## Built-in subagents

Firebender includes built-in subagents that handle context-heavy operations automatically.

| Subagent          | Purpose                                                | Why it is a subagent                                                                                  |
| ----------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `Explore`         | Searches and analyzes codebases                        | Codebase exploration generates large intermediate output that would otherwise bloat the main context. |
| `general-purpose` | Handles complex research and multi-step delegated work | Some tasks benefit from a separate context window even when they are not pure codebase exploration.   |

## Why these subagents exist

These operations share common traits: they generate noisy intermediate output, benefit from specialized prompts and tools, and can consume significant context. Running them as subagents solves several problems:

* **Context isolation**: intermediate output stays in the subagent. The parent only sees the final summary.
* **Model flexibility**: subagents can use a different model configuration from the parent.
* **Specialized configuration**: each subagent has prompts and tool access tuned for its specific task.
* **Cost efficiency**: isolating token-heavy work in smaller or specialized agents can reduce overall cost.

You do not need to configure the built-in subagents. Firebender uses them automatically when appropriate.

## When to use subagents

| Use subagents when...                                     | Use skills when...                        |
| --------------------------------------------------------- | ----------------------------------------- |
| You need context isolation for long research tasks        | The task is single-purpose and repeatable |
| You want multiple workstreams to run in parallel          | You want a quick, reusable action         |
| The task requires specialized expertise across many steps | The task completes in one shot            |
| You want an independent verification of work              | You do not need a separate context window |

<Info>If you find yourself creating a subagent for a simple task like generating a changelog or formatting imports, consider using a [skill](/multi-agent/skills) instead.</Info>

## Quick start

Firebender automatically uses subagents when appropriate. You can also create a custom subagent by selecting the agent builder in the mode dropdown.

## Custom subagents

Define custom subagents to encode specialized knowledge, enforce team standards, or automate repetitive workflows.

## Configuration model

In Firebender, agents and subagents use the same configuration system:

* **All agent files** are registered through the `agents` array in `firebender.json`
* **Any agent with `callable: true`** can be invoked as a subagent
* **The older `subagents` array** is still supported for backwards compatibility, but new configurations should use `agents`

### Project vs user scope

| Type           | Location                        | Scope                             |
| -------------- | ------------------------------- | --------------------------------- |
| Project config | `firebender.json`               | Current project only              |
| User config    | `~/.firebender/firebender.json` | All projects for the current user |

Agent files can live anywhere as long as they are listed in the corresponding `agents` array. Relative paths resolve from the project root for project config, or from `~/.firebender/` for user config.

### Example `firebender.json`

```json theme={null}
{
  "agents": [
    "agents/verifier.md",
    "agents/debugger.md",
    "~/firebender-agents/security-reviewer.md"
  ]
}
```

## File format

Each subagent is a markdown file with YAML frontmatter followed by the prompt:

```markdown theme={null}
---
name: security-auditor
description: Security specialist. Use when implementing auth, payments, or handling sensitive data.
tools: read, edit
model: inherit
callable: true
---
You are a security expert auditing code for vulnerabilities.
When invoked:
1. Identify security-sensitive code paths
2. Check for common vulnerabilities
3. Verify secrets are not hardcoded
4. Review input validation and sanitization
Report findings by severity:
- Critical
- High
- Medium
```

## Configuration fields

| Field         | Required | Description                                                                                                 |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `name`        | No       | Unique display name. Defaults to the filename if omitted.                                                   |
| `description` | No       | Explains when the subagent should be used. Firebender reads this to decide delegation.                      |
| `tools`       | No       | Comma-separated list of tool groups or MCP tools the subagent can use. If omitted, all tools are available. |
| `model`       | No       | Model to use: `small`, `medium`, `large`, `inherit`, `default`, or a specific model ID.                     |
| `color`       | No       | Optional color used when the agent appears as a custom mode.                                                |
| `icon`        | No       | Optional absolute or resolved icon path.                                                                    |
| `callable`    | No       | If `true`, the agent can be invoked as a subagent. Defaults to `false`.                                     |

### Important configuration note

Fields like `readonly` and `background` are not part of the agent file schema in Firebender. Instead:

* **Subagent availability** is controlled by `callable: true`
* **Tool restrictions** are controlled by `tools`
* **Background execution** is chosen at invocation time by the parent agent

## Using subagents

### Automatic delegation

Firebender proactively delegates tasks based on:

* The task complexity and scope
* Custom subagent descriptions in your configuration
* Current context and available tools

Include phrases like "use proactively" or "always use for" in your description field to encourage delegation for specific situations.

### Explicit invocation

You can also ask Firebender to use a specific subagent by name in natural language:

* Use the `verifier` subagent to confirm the auth flow is complete
* Have the `debugger` subagent investigate this error
* Run the `security-auditor` subagent on the payment module

### Parallel execution

Launch multiple subagents concurrently for maximum throughput:

* Review the API changes and update the documentation in parallel

Firebender can issue multiple subagent launches in a single step so those workstreams run simultaneously.

### Resuming subagents

Subagents can be resumed to continue previous work. Background subagents preserve state while they run, and the parent agent can continue a prior subagent conversation when needed.

## Common patterns

### Verification agent

A verification agent independently validates whether claimed work was actually completed. This helps catch cases where an implementation is partially done or unverified.

```markdown theme={null}
---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
tools: read, execution
model: small
callable: true
---
You are a skeptical validator. Your job is to verify that work claimed as complete actually works.
When invoked:
1. Identify what was claimed to be completed
2. Check that the implementation exists and is functional
3. Run relevant verification steps
4. Look for edge cases that may have been missed
Report:
- What was verified and passed
- What was claimed but incomplete or broken
- Specific issues that still need work
```

This pattern is useful for:

* Validating that features work end-to-end before marking work complete
* Catching partially implemented functionality
* Ensuring tests really pass, not just that test files exist

### Orchestrator pattern

For complex workflows, a parent agent can coordinate multiple specialist subagents in sequence:

* Planner analyzes requirements and creates a technical plan
* Implementer builds the feature based on the plan
* Verifier confirms the implementation matches requirements

Each handoff should include structured output so the next agent has clear context.

## Example subagents

### Debugger

```markdown theme={null}
---
name: debugger
description: Debugging specialist for errors and test failures. Use when encountering issues.
tools: read, edit, execution
callable: true
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture the error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement a minimal fix
5. Verify the solution works
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
Focus on fixing the underlying issue, not symptoms.
```

### Test runner

```markdown theme={null}
---
name: test-runner
description: Test automation expert. Use proactively to run tests and fix failures.
tools: read, edit, execution
callable: true
---
You are a test automation expert.
When you see code changes, proactively run appropriate tests.
If tests fail:
1. Analyze the failure output
2. Identify the root cause
3. Fix the issue while preserving test intent
4. Re-run to verify
Report test results with:
- Number of tests passed or failed
- Summary of any failures
- Changes made to fix issues
```

## Best practices

* **Write focused subagents**: each subagent should have a single, clear responsibility. Avoid generic helper agents.
* **Invest in descriptions**: the `description` field determines when Firebender delegates to your subagent.
* **Keep prompts concise**: long prompts dilute focus. Be specific and direct.
* **Add subagents to version control**: commit your subagent files so the team benefits.
* **Start with Firebender-generated agents**: let Firebender draft the initial version, then customize it.

## Anti-patterns to avoid

Do not create dozens of generic subagents. A large set of vague agents is hard to maintain and gives Firebender poor delegation signals.

* **Vague descriptions**: "Use for general tasks" gives no useful signal. Be specific.
* **Overly long prompts**: a giant prompt usually makes the subagent slower and harder to maintain.
* **Duplicating commands**: if a task is single-purpose and does not need context isolation, use a command or skill instead.
* **Too many subagents**: start with two or three focused subagents and add more only when you have a clear use case.

## Managing subagents

### Creating subagents

The easiest way to create a subagent is to ask Firebender to create one for you:

Create an agent file at `agents/security-reviewer.md`, add it to the `agents` array in `firebender.json`, and make it `callable: true`. The `security-reviewer` subagent should check code for common vulnerabilities like injection, XSS, and hardcoded secrets.

You can also create subagents manually by adding markdown files and registering them in project or user config.

### Viewing subagents

Callable agents appear in the `Sub-agents` submenu, and non-callable agents appear as custom modes in the mode picker.

## Performance and cost

Subagents have trade-offs. Understanding them helps you decide when to use them.

| Benefit            | Trade-off                                                      |
| ------------------ | -------------------------------------------------------------- |
| Context isolation  | Startup overhead because each subagent gathers its own context |
| Parallel execution | Higher token usage when multiple contexts run at once          |
| Specialized focus  | Extra latency for simple tasks                                 |

### Token and cost considerations

* **Each subagent consumes tokens independently**: running several in parallel increases total usage
* **Evaluate the overhead**: for quick, simple tasks, the main agent is often faster
* **Subagents can be slower**: the benefit is context isolation and specialization, not raw speed

## Related documentation

* [Agents API reference](/api-reference/agents)
* [Commands](/input/commands)
* [Parallel agents](/multi-agent/worktrees)