Building Your App › Custom Agent Building
Sub-Agents on Emergent
Sub-agents are specialised helpers that work alongside the main agent. They take on focused tasks that benefit from narrow expertise. This guide explains how sub-agents work and how to create them.
Overview
A sub-agent is like an expert colleague who handles one specific type of work very well. The main agent stays in charge, but hands off certain tasks to sub-agents when needed.
Examples of sub-agent roles:
- Code reviewer
- Testing specialist
- Integration checker
- Image processor
- Data analyzer
Each sub-agent has one job and does it with precision.
How Sub-Agents Work with Main Agents
The interaction is simple and predictable.
- You give the main agent a task
- The main agent identifies a part of the work that needs specialty
- It assigns that specific task to the sub-agent
- The sub-agent completes the work
- The main agent receives the result and continues
Sub-agents help keep tasks organized and efficient.
How to Create an Effective Sub-Agent
Step 1: Give the Sub-Agent a Hyper Focused Persona
A sub-agent should have one very specific area of expertise.
Example: You are an expert code reviewer specializing in identifying bugs, security issues, and optimization opportunities.
Step 2: Write Two Descriptions
Every sub-agent description needs to be understood by two 'users' - the main agent and the sub-agent itself..
A. Definition for the Main Agent
This explains when the sub-agent should be called and what it specializes in.
B. Task Description for the Sub-Agent
This explains what the sub-agent should do when assigned work.
Step 3: Create a Focused Workflow
Describe how the sub-agent should handle tasks step by step.
General structure:
- Understand the request
- Apply specialized knowledge
- Present analysis
- Provide recommendations
Step 4: Set Communication Rules
Sub-agents should follow clear standards.
Guidelines may include:
- Format responses with sections
- Stay within the area of expertise
- Highlight critical issues
- Provide actionable suggestions
- Explain limitations when needed
System Constraints
Sub-agents include a read only section called System Constraints. This ensures the agent:
- Has correct tool access
- Communicates correctly
- Follows security standards
- Operates consistently
You do not need to edit this section.
Important Rule
Sub-agents cannot call other sub-agents. All handoffs must happen through the main agent.
Best Practices
DO:
- Keep each sub-agent focused
- Clearly state when they should be used
- Test interactions with the main agent
- Allow clean handovers between agents
DO NOT:
- Overload sub-agents with too many responsibilities
- Create too many sub-agents too early
Sub-agents help create clean, modular, and reliable agent systems.
