Subagents

Subagents are specialized agents that the Agent can spawn during execution to handle specific tasks. When you create a subagent, the main Agent can delegate work to it—like having a team of specialists the Agent can call on when needed.

Subagents

How Subagents Work

Unlike modes that you select before sending a message, subagents are called automatically by the Agent when it determines a task would benefit from specialized handling.

You send a message
        ↓
Main Agent analyzes the task
        ↓
Agent decides to delegate → Spawns subagent
        ↓
Subagent executes with its own tools and prompt
        ↓
Results return to main Agent
        ↓
Agent continues with combined knowledge

Subagents are typically called automatically by the Agent. You can also trigger them manually by mentioning the subagent name in your prompt.

Creating a Subagent

Open Subagent Manager

Click the Subagents icon in the access via Settings → Agents → Subagents.

Click Create Subagent

Click the New Subagent button to open the creation form.

Configure Your Subagent

Field	Description
Title	Name the Agent uses to identify this subagent
Description	Explains when this subagent should be used
System Prompt	Instructions defining the subagent's behavior
Tools	Capabilities available during execution
Scope	Global (all projects) or Project (current only)
Tags	Categories for organization
Color	Visual identifier in the UI

Save and Enable

Click Save. The subagent is now available for the Agent to call when appropriate.

The Description Matters

The description field is crucial—it tells the main Agent when to use your subagent. Write it from the Agent's perspective:

"Use this agent when the user asks for security analysis
or vulnerability scanning of code"

"Delegate to this agent for generating unit tests
following the project's testing patterns"

"Call this agent when the user needs database schema
analysis or migration planning"

"Security stuff" → Too vague, Agent won't know when to use it

"My helper agent" → Doesn't describe the capability

"Use this for everything" → Defeats the purpose of specialization

Writing Subagent Prompts

Subagent prompts should be task-focused since they handle delegated work, not conversations.

Prompt Structure

You are a specialized [role] that handles [specific task type].

## Your Task
When called, you will receive a specific task. Your job is to:
- [Primary responsibility]
- [Secondary responsibility]
- [Output expectations]

## Approach
1. [First step in your process]
2. [Analysis or investigation step]
3. [Output generation step]

## Output Format
[Describe exactly how results should be formatted]

Example Prompts

You are a security auditor that analyzes code for vulnerabilities.

## Your Task
When called, analyze the specified code or files for security issues:
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication/authorization flaws
- Sensitive data exposure
- Insecure dependencies

## Approach
1. Read the target files using available tools
2. Analyze patterns that could indicate vulnerabilities
3. Check for common security anti-patterns
4. Review dependency usage for known issues

## Output Format
For each finding:
- Severity: Critical / High / Medium / Low
- Location: File path and line number
- Issue: Description of the vulnerability
- Risk: What could happen if exploited
- Fix: Recommended remediation

You are a test generation specialist.

## Your Task
Generate comprehensive tests for the specified code:
- Unit tests for individual functions
- Edge case coverage
- Error handling tests
- Integration tests where appropriate

## Approach
1. Read the target code to understand its behavior
2. Identify all code paths and edge cases
3. Check existing test patterns in the project
4. Generate tests following project conventions

## Output Format
- Use the project's existing test framework
- Group tests logically by function/feature
- Include descriptive test names
- Add comments explaining non-obvious test cases

You are a technical documentation specialist.

## Your Task
Generate documentation for the specified code:
- API documentation with examples
- Function/method documentation
- Usage guides for complex features

## Approach
1. Read the code to understand its purpose and behavior
2. Identify public APIs and their parameters
3. Find usage examples in the codebase
4. Generate clear, example-rich documentation

## Output Format
- Use JSDoc/TSDoc format for inline docs
- Include parameter descriptions and types
- Provide at least one usage example per function
- Note any edge cases or limitations

Available Tools

Select tools based on what your subagent needs to accomplish:

Read & Search (Safe for analysis tasks)

Tool	Use Case
Read Files	Analyze file contents
Scan Folder	List directory contents
File Tree	Understand project structure
Search Files	Find files by name/pattern
Grep Files	Search content with regex

Write & Execute (For generative tasks)

Tool	Use Case
Write File	Create new files
Edit File	Modify existing files
Terminal	Run commands, tests, builds

External

Tool	Use Case
MCP	Use Model Context Protocol servers
Save Memory	Persist learnings for future use

Give subagents only the tools they need. A security auditor shouldn't have write access. A test generator needs both read and write.

Scope: Global vs Project

Scope	Availability	Best For
Global	All projects	General-purpose subagents (security, testing)
Project	Current project only	Project-specific conventions or patterns

Project-scoped subagents can reference project-specific:

Coding standards
Testing frameworks
File naming conventions
Architecture patterns

Managing Subagents

Editing

Open the Subagent Manager
Find your subagent in the list
Click to edit
Modify settings and save

Activating/Deactivating

Toggle the Active status to control whether the Agent can use a subagent without deleting it.

Filtering

Search by title or description
Filter by scope (Global / Project)
Filter by tags for organization

Example Subagent Configurations

Code Reviewer

Scope: Global Tools: Read Files, Grep Files, Search Files

Description: "Use when the user asks for code review, feedback on implementation quality, or suggestions for improvements."

Analyzes code for best practices, potential bugs, and improvement opportunities without making changes.

Migration Planner

Scope: Project Tools: Read Files, File Tree, Search Files

Description: "Delegate to this agent when planning database migrations, API version upgrades, or dependency updates."

Analyzes current state and creates migration plans with step-by-step instructions.

Refactoring Agent

Scope: Global Tools: Read Files, Edit File, Search Files, Terminal

Description: "Use when the user requests refactoring, code reorganization, or architectural improvements."

Performs safe refactoring with the ability to run tests after changes.

API Documenter

Scope: Global Tools: Read Files, Write File, File Tree

Description: "Call this agent when generating API documentation, OpenAPI specs, or endpoint references."

Generates comprehensive API documentation from code analysis.

Best Practices

Prompt Design

Be specific about the task type — Generic prompts lead to generic results
Define output format — Subagents work better with clear structure expectations
Include domain knowledge — Reference specific patterns, frameworks, or standards

Tool Selection

Minimum viable toolset — Only include necessary tools
Match tools to task — Analysis tasks shouldn't need write access
Consider side effects — Terminal access can modify system state

Organization

Use descriptive titles — "Security Auditor" not "Agent 1"
Write clear descriptions — The Agent uses these to decide when to delegate
Apply tags — Group related subagents for easier management
Choose appropriate scope — Global for universal tasks, Project for specific conventions

When to Create Subagents

Create a subagent when you frequently need:

Specialized analysis that requires domain expertise
Repeated tasks with consistent output format
Isolated execution with limited tool access
Complex workflows that benefit from focused attention

Subagents shine for tasks that are well-defined and repeatable. For one-off requests, the main Agent is usually sufficient.

Subagents vs Other Features

Feature	Purpose	When Used
Subagents	Delegated task execution	Agent decides during execution
Custom Agents	Alternative conversation modes	You select before messaging
Skills	Knowledge injection	Referenced with @ mentions
MCP Servers	External tool integration	Called as tools by any agent

Code Reviewer

Migration Planner

Refactoring Agent

API Documenter

On this page