Sub-Agents

Sub-agents allow you to use other agents as tools within an agent, enabling complex multi-step workflows and specialized task delegation. Instead of building one agent that tries to do everything, you can create focused specialists and have a coordinator agent call on them as needed.

What are Sub-Agents?

Sub-agents are agents configured as tools that can be called by a parent agent. This creates hierarchical AI workflows where a parent agent orchestrates the overall conversation, sub-agents handle specialized tasks when called upon, and results flow back to the parent to continue the interaction.

This architecture offers several advantages. Specialization lets each agent focus on what it does best—you might have a research agent for gathering information, a writing agent for creating content, and an analysis agent for processing data. Modularity means you can build complex systems from simple, well-tested parts, reusing agents across different workflows and updating them independently. Delegation enables parent agents to hand off complex sub-tasks, specialized processing, or multi-step operations to purpose-built specialists.

Configuring Sub-Agents

To use sub-agents, first enable the Agent tool on your parent agent. Open your parent agent, navigate to the Tools section, and enable the Agent tool. Then configure which agents can be called as sub-agents, select them from your available agents, and set any access permissions.

You can configure several options: Allowed Agents specifies which agents the parent can call, Max Instances limits how many sub-agent calls can run concurrently, and Permissions controls what sub-agents can access.

How Sub-Agents Work

When the parent agent determines it needs specialized help, it calls a sub-agent with relevant instructions and context. The sub-agent processes the request, then returns its results to the parent, which continues the conversation with the user using that information.

The data flow looks like this: user input reaches the parent agent, which may call a sub-agent when needed. The sub-agent processes its task and returns results to the parent, which then responds to the user.

Sub-agents receive instructions from the parent, relevant context about what's needed, and any parameters passed along. They return processed results, status information, and any artifacts they created.

Use Cases

Sub-agents shine when you need different expertise for different parts of a workflow.

Research workflows might have a coordinator agent that manages the overall process, calling on a web search agent to find information, a document agent to read files, and a summary agent to synthesize findings.

Content pipelines often separate concerns: a research agent gathers facts, a writing agent drafts content, and a review agent edits and refines the output. The coordinator manages the flow between them.

Customer support can benefit from specialized agents: a knowledge agent searches documentation, a ticket agent creates support tickets, and an escalation agent handles complex cases that need human attention.

Data processing workflows might use separate agents for extraction, processing, and reporting, with a coordinator managing the pipeline.

Best Practices

Good sub-agent design starts with clear responsibilities. Each agent should have a specific, well-defined purpose with minimal overlap. Document what each agent does so you and your team understand when to use each one.

Keep hierarchies shallow when possible. While the system supports nesting, simpler structures are easier to debug and maintain. Balance the benefits of specialization against the complexity it adds.

Design for failure. Sub-agents can fail or return unexpected results, so parent agents should handle these situations gracefully with fallback behaviors. Log issues for debugging so you can identify and fix problems.

Your parent agent's instructions should explain when to use each sub-agent. Something like "Use the Research Agent for finding information and the Writing Agent for creating content" helps the AI make good delegation decisions.

Sub-agents themselves should be designed to work well when called. They should focus on the specific request, return concise and relevant results, and not try to do more than asked.

Finally, consider performance. Each sub-agent call adds latency to the response. Use sub-agents when specialization genuinely helps, but consider handling simple tasks directly in the parent agent.

Limitations

Current Constraints

• Sub-agents cannot call the parent agent (no circular calls)
• Limited nesting depth
• Shared resource limits across hierarchy

When Not to Use

Sub-agents may not be ideal when:

• Task is simple enough for direct completion
• Latency is critical
• Resources are limited

Example: Multi-Agent Workflow

Scenario

A user wants a comprehensive report on a topic.

Configuration

Main Agent (Report Coordinator)

• Tools: Agent tool (with sub-agents enabled)
• Instructions: Coordinate report creation

Research Sub-Agent

• Tools: Web search, Knowledge base
• Instructions: Find relevant information

Writing Sub-Agent

• Tools: Artifact creation
• Instructions: Write formatted content

Flow

1. User requests report
2. Main agent delegates research to Research Agent
3. Research Agent searches and returns findings
4. Main agent delegates writing to Writing Agent
5. Writing Agent creates report artifact
6. Main agent presents completed report

Troubleshooting

Sub-Agent Not Available

If sub-agents can't be used:

• Verify Agent tool is enabled
• Check sub-agent is selected
• Confirm permissions

Poor Results

If sub-agent results are lacking:

• Review sub-agent instructions
• Check context being passed
• Verify sub-agent tools are enabled

Performance Issues

If workflows are slow:

• Reduce unnecessary sub-agent calls
• Optimize sub-agent instructions
• Consider consolidating agents