Sub-Agents

🤖 Multi-Agent Architecture & Delegation

The Sub-Agents tab transforms your AI agent from a single assistant into a coordinated team of specialized experts. Here, you configure hierarchical agent relationships, delegation patterns, and collaborative workflows that enable sophisticated multi-agent problem-solving.

🎯 What Are Sub-Agents?

Sub-agents are specialized AI assistants that your primary agent can delegate specific tasks to, creating a hierarchical system where:

Primary Agent: Acts as orchestrator and user interface
Sub-Agents: Handle specialized functions, domains, or complex sub-tasks
Delegation: Intelligent routing of tasks to most appropriate sub-agent
Coordination: Results aggregation and workflow management
Escalation: Complex cases handled by multiple agents working together

🏗️ Sub-Agent Architecture Patterns

🎭 Specialization by Domain

Different sub-agents handle distinct subject areas:

Example: Customer Service Agent Hierarchy

Primary Agent: "Customer Support Assistant"
├── Technical Support Sub-Agent
│   ├── Handles: Hardware issues, software bugs, integrations
│   ├── Knowledge: Technical documentation, troubleshooting guides
│   └── Tools: Ticketing system, diagnostic tools, remote access
│
├── Billing & Payments Sub-Agent
│   ├── Handles: Invoices, payment issues, subscription changes
│   ├── Knowledge: Billing policies, payment processing, pricing
│   └── Tools: Payment gateway, billing system, accounting software
│
├── Account Management Sub-Agent
│   ├── Handles: Account setup, user management, permissions
│   ├── Knowledge: Account policies, user roles, compliance
│   └── Tools: User management system, audit logs, access controls
│
└── Sales Support Sub-Agent
    ├── Handles: Upselling, renewals, product recommendations
    ├── Knowledge: Product catalog, pricing, competitor analysis
    └── Tools: CRM, sales tracking, proposal generation

🔄 Process-Based Delegation

Sub-agents organized around business processes:

Example: Sales Process Agent Team

Primary Agent: "Sales Assistant"
├── Lead Qualification Sub-Agent
│   ├── Handles: Initial prospect assessment, scoring
│   ├── Process: BANT qualification, needs assessment
│   └── Output: Qualified leads with priority scores
│
├── Proposal Generation Sub-Agent  
│   ├── Handles: Custom proposals, pricing calculations
│   ├── Process: Requirements analysis, solution design
│   └── Output: Tailored proposals with ROI analysis
│
├── Demo Coordination Sub-Agent
│   ├── Handles: Demo scheduling, preparation, follow-up
│   ├── Process: Calendar management, demo customization
│   └── Output: Scheduled demos with personalized content
│
└── Contract Negotiation Sub-Agent
    ├── Handles: Terms discussion, legal review coordination
    ├── Process: Contract preparation, stakeholder alignment
    └── Output: Finalized agreements ready for signature

⚡ Capability-Based Distribution

Sub-agents with specialized functional abilities:

Example: Content Creation Agent Network

Primary Agent: "Content Manager"
├── Research Sub-Agent
│   ├── Capability: Data gathering, fact-checking, analysis
│   ├── Sources: Web research, database queries, API calls
│   └── Specialty: Market research, competitive analysis
│
├── Writing Sub-Agent
│   ├── Capability: Content creation, editing, optimization
│   ├── Styles: Blog posts, whitepapers, social media
│   └── Specialty: SEO optimization, brand voice consistency
│
├── Visual Design Sub-Agent
│   ├── Capability: Image generation, layout design, graphics
│   ├── Tools: AI image generation, template libraries
│   └── Specialty: Brand compliance, accessibility standards
│
└── Distribution Sub-Agent
    ├── Capability: Multi-channel publishing, scheduling
    ├── Platforms: Social media, email, website, blog
    └── Specialty: Timing optimization, audience targeting

⚙️ Sub-Agent Configuration

How to Configure Sub-Agents in Tab 7

In the Visual Agent Builder, Tab 7 allows you to add other agents as "tools" that your primary agent can delegate tasks to. This creates a hierarchical multi-agent system where specialized sub-agents handle specific domains.

Step-by-Step Configuration

1. Navigate to Tab 7: Sub-Agents & Delegation

Open your primary agent in the Visual Agent Builder
Click on Tab 7 in the configuration interface
This is where you'll add and configure all sub-agents

2. Add a Sub-Agent

Click "Add Sub-Agent" or similar action button
Select an existing agent from your workspace to use as a sub-agent
Each sub-agent must be a fully configured agent in your workspace

3. Configure Sub-Agent Tool Settings

For each sub-agent, you configure:

Setting

Description

Configuration Details

Sub-Agent Selection

Choose which agent to use

Select from your existing agents in the workspace

Description

How primary agent should use this sub-agent

Describe the sub-agent's role, expertise, and when to delegate to it

Metadata

Visual positioning (for multi-agent system diagrams)

Optional: Position coordinates for visual representation

4. Write Effective Sub-Agent Descriptions

The description field is critical - it tells your primary agent when and how to use each sub-agent:

Good Description Examples:

Technical Support Specialist
Use this agent when users report technical issues, bugs, API errors,
integration problems, or need help with system configuration.
This agent has access to technical documentation and troubleshooting guides.

Billing & Payments Expert
Delegate to this agent for all billing inquiries, payment issues,
invoice questions, subscription changes, or pricing discussions.
This agent can access billing systems and process payment-related requests.

Content Writer
Use this agent to create blog posts, marketing copy, social media content,
or any written materials. This agent specializes in brand voice consistency
and SEO optimization.

Poor Description Examples:

❌ "Technical agent" (too vague)
❌ "Use for support" (doesn't specify what kind)
❌ "Billing" (no context on when to use)

Creating Sub-Agents (Prerequisites)

Before adding sub-agents to your primary agent, you must first create them as standalone agents:

Sub-Agent Definition Example

Agent Name: "Technical Support Specialist"
Purpose: Handle technical troubleshooting and integration issues
Specialization: Hardware problems, software bugs, API integrations
Expertise Level: Expert in product technical specifications

Model Configuration (Tab 2):
- Primary Model: GPT-4.1 (for complex technical reasoning)
- Fallback Model: Claude 4.5 Sonnet (for detailed explanations)
- Temperature: 0.3 (precise, consistent responses)
- Max Tokens: 2000 (detailed technical guidance)

System Instructions (Tab 3):
- Role definition as technical support specialist
- Troubleshooting methodology and escalation procedures
- Response format requirements

Knowledge Sources (Tab 4):
- Technical documentation repository
- Known issues database
- Integration guides and API specifications
- Hardware compatibility matrices
- Software troubleshooting workflows

Tools (Tab 5):
- Ticketing system integration
- Diagnostic tools
- Database query tools
- Documentation search

Delegation Rules Configuration

Delegation Triggers:
Keywords: ["technical", "bug", "error", "integration", "API", "setup"]
Intent Classification: Technical support request
Complexity Threshold: Technical questions requiring specialized knowledge
User Indicators: Mentions of specific technologies or error messages

Example Rules:
IF user_message.contains("API error") OR user_message.contains("integration")
   THEN delegate_to("Technical Support Specialist")
   
IF intent == "technical_troubleshooting" AND confidence > 0.8
   THEN delegate_to("Technical Support Specialist")
   
IF user_mentions_product_features AND query_complexity == "high"
   THEN delegate_to("Technical Support Specialist")

How Sub-Agent Delegation Works

Runtime Execution Flow

When your primary agent decides to use a sub-agent, here's what happens:

1. Tool Invocation

Primary Agent Decision:
- Analyzes user request
- Determines appropriate sub-agent based on description
- Calls sub-agent as a tool with: run_agent_{sub_agent_name}(message, thread_id)

2. Message Parameters

message: The task or question to delegate to the sub-agent
thread_id: (Optional) UUID to continue an existing conversation thread
          - If provided: Sub-agent continues previous conversation
          - If omitted: Creates new conversation thread

3. Sub-Agent Execution

Sub-Agent Processing:
1. Receives delegated message
2. Processes using its own configuration:
   - AI model settings
   - System instructions
   - Knowledge bases
   - Available tools
3. Generates response
4. Returns results to primary agent

4. Response Format

Sub-Agent Returns:
{
  "final_message": "The sub-agent's complete response",
  "thread_id": "uuid-of-conversation-thread"
}

Primary Agent Receives:
- Full response from sub-agent
- Thread ID for potential follow-up
- Can continue conversation or return results to user

Conversation Thread Management

Single-Turn Delegation:

User → Primary Agent → Sub-Agent (new thread) → Primary Agent → User
- Each delegation creates a new conversation
- Best for independent, self-contained tasks

Multi-Turn Delegation:

User → Primary Agent → Sub-Agent (thread: abc-123) → Primary Agent → User
User → Primary Agent → Sub-Agent (thread: abc-123) → Primary Agent → User
- Primary agent maintains thread_id
- Sub-agent continues previous conversation
- Best for complex, multi-step problem solving

Handoff Protocols

Seamless Task Transfer:
1. Primary agent identifies delegation need based on sub-agent descriptions
2. Primary agent calls sub-agent tool with message and optional thread_id
3. Sub-agent receives message and processes with full capabilities
4. Sub-agent streams real-time progress updates
5. Sub-agent returns final response
6. Primary agent receives results
7. Primary agent synthesizes response for user or delegates further

Example Handoff:
User: "I'm getting a 401 error when calling your API"
Primary Agent: [Analyzes request, identifies technical nature]
Primary Agent: [Calls run_agent_technical_support("User getting 401 error on API")]
Technical Sub-Agent: [Processes using technical knowledge and tools]
Technical Sub-Agent: [Returns detailed troubleshooting steps]
Primary Agent: "I've consulted our technical specialist. Here's the solution..."

Multi-Agent Collaboration

Collaborative Problem Solving:
- Multiple sub-agents work on different aspects
- Real-time information sharing between agents
- Coordinated response compilation
- Conflict resolution and consensus building
- Quality assurance and consistency checking

Example Collaboration:
User Request: "Help me choose and implement a payment solution"
→ Research Sub-Agent: Analyzes payment options and requirements
→ Technical Sub-Agent: Evaluates integration complexity
→ Legal Sub-Agent: Reviews compliance and regulatory requirements
→ Primary Agent: Synthesizes recommendations into actionable plan

Context Management

Shared Context Pool

Information Sharing:
- User profile and preferences
- Conversation history and context
- Previous sub-agent interactions
- Ongoing projects and tasks
- Learned preferences and patterns

Context Categories:
User Information:
- Name, role, company, contact preferences
- Technical skill level, experience
- Previous interactions and resolutions
- Preferred communication style

Business Context:
- Current projects and objectives
- Budget constraints and timelines
- Stakeholder relationships
- Decision-making processes

Technical Context:
- System configurations and setups
- Integration requirements
- Performance considerations
- Security and compliance needs

Privacy & Access Control

Context Access Management:
- Role-based information access
- Sensitive data protection
- Audit logging of information sharing
- User consent for data sharing
- Automatic data cleanup and retention

Example Access Controls:
Financial Sub-Agent: Access to billing, payments, pricing
Technical Sub-Agent: Access to system configs, integrations
Sales Sub-Agent: Access to opportunities, requirements, contacts
Support Sub-Agent: Access to tickets, issues, resolutions

🚀 Advanced Sub-Agent Features

Dynamic Sub-Agent Creation

Automatically spawn specialized agents for complex scenarios:

Dynamic Agent Scenarios:
Complex Multi-Step Projects:
- Create project-specific coordination agent
- Spawn specialist agents for each work stream
- Establish temporary communication channels
- Coordinate deliverables and timelines

Crisis Response Situations:
- Incident commander agent for coordination
- Specialist agents for different impact areas
- Real-time status monitoring and reporting
- Stakeholder communication management

Learning & Adaptation:
- Create learning agents for new domains
- Develop expertise through interaction
- Share learnings across agent network
- Evolve capabilities over time

Sub-Agent Performance Optimization

Load Balancing & Scaling

Resource Management:
- Distribute workload across sub-agents
- Scale sub-agent capacity based on demand
- Queue management for high-volume periods
- Priority routing for urgent requests

Performance Monitoring:
- Response time tracking per sub-agent
- Success rate and user satisfaction metrics
- Resource utilization and efficiency
- Bottleneck identification and resolution

Continuous Learning & Improvement

Adaptive Sub-Agent Network:
- Performance analytics and optimization
- User feedback integration
- Knowledge base updates from interactions
- Best practice sharing across agents
- Automated improvement recommendations

Quality Assurance:
- Cross-agent validation and fact-checking
- Consistency monitoring across responses
- Brand voice and tone compliance
- Accuracy verification and correction

Specialized Sub-Agent Types

Research & Analysis Agents

Research Agent Capabilities:
- Web research and data gathering
- Competitive analysis and benchmarking  
- Market research and trend analysis
- Technical research and evaluation
- Data synthesis and insight generation

Configuration Example:
Name: "Market Research Specialist"
Tools: Web search, industry databases, analytics platforms
Knowledge: Market reports, competitor profiles, trend data
Output: Research reports, competitive analyses, recommendations

Creative & Content Agents

Creative Agent Capabilities:
- Content ideation and brainstorming
- Writing and editing in multiple styles
- Visual content creation and design
- Brand voice consistency maintenance
- Multi-channel content adaptation

Configuration Example:
Name: "Brand Content Creator"
Tools: AI writing tools, image generation, template libraries
Knowledge: Brand guidelines, content strategies, audience profiles
Output: Blog posts, social content, marketing materials

Technical Implementation Agents

Technical Agent Capabilities:
- Code review and technical validation
- Architecture design and recommendations
- Integration planning and execution
- Performance optimization guidance
- Security and compliance verification

Configuration Example:
Name: "Integration Architect"
Tools: API testing tools, documentation systems, monitoring
Knowledge: Technical specifications, best practices, security standards
Output: Integration plans, technical documentation, validation reports

📊 Sub-Agent Analytics & Management

Performance Metrics

Individual Sub-Agent Metrics

Agent Performance Tracking:
- Task completion rates and accuracy
- Average response times
- User satisfaction scores
- Knowledge utilization effectiveness
- Error rates and quality issues

Success Indicators:
- First-contact resolution rates
- User engagement and follow-through
- Knowledge gap identification
- Learning and improvement trends
- Resource efficiency metrics

Network-Level Analytics

Multi-Agent System Metrics:
- Overall system throughput and capacity
- Inter-agent collaboration effectiveness
- Context sharing accuracy and speed
- Escalation patterns and success rates
- Network resilience and fault tolerance

Optimization Opportunities:
- Delegation decision accuracy
- Sub-agent specialization effectiveness
- Communication overhead reduction
- Resource allocation optimization
- User experience consistency

Sub-Agent Lifecycle Management

Creation & Deployment

Sub-Agent Lifecycle:
1. Needs Assessment: Identify specialization requirements
2. Agent Design: Define role, capabilities, knowledge sources
3. Configuration: Set up models, tools, access controls
4. Training: Load knowledge, configure delegation rules
5. Testing: Validate performance with test scenarios
6. Deployment: Integrate with primary agent network
7. Monitoring: Track performance and user feedback
8. Optimization: Continuous improvement and updates

Maintenance & Evolution

Ongoing Management:
- Regular knowledge base updates
- Performance monitoring and tuning
- User feedback integration
- Capability expansion and enhancement
- Deprecation of obsolete agents

Version Control:
- Agent configuration versioning
- Rollback capabilities for issues
- A/B testing for improvements
- Change impact assessment
- Documentation and audit trails

🎯 Sub-Agent Best Practices

Design Principles

Clear Specialization

Effective Specialization Strategy:
- Define distinct, non-overlapping domains
- Establish clear expertise boundaries
- Avoid capability redundancy across agents
- Create fallback and escalation paths
- Document agent roles and responsibilities

Seamless User Experience

User Experience Guidelines:
- Transparent agent transitions
- Consistent brand voice across all agents
- Context preservation during handoffs
- Clear communication about specialist involvement
- Unified interaction interface

Implementation Strategy

Gradual Rollout Approach

Implementation Phases:
Phase 1: Single specialized sub-agent (high-impact domain)
Phase 2: Core sub-agent team (3-4 specialists)
Phase 3: Advanced delegation and collaboration features
Phase 4: Dynamic agent creation and optimization
Phase 5: Full multi-agent ecosystem with learning

Success Criteria:
- User satisfaction improvements
- Response accuracy increases
- Task completion rate improvements  
- Reduced escalation to human agents
- Positive ROI demonstration

Change Management

Organizational Adoption:
- Train users on multi-agent capabilities
- Set expectations for specialist interactions
- Provide feedback mechanisms for improvement
- Monitor and address user concerns
- Celebrate success stories and improvements

Staff Training:
- Understanding of agent specializations
- Escalation procedures for complex cases
- Monitoring and oversight responsibilities
- Quality assurance and feedback processes
- Continuous improvement participation

📈 Sub-Agent ROI & Business Impact

Value Creation Metrics

Business Value Indicators:
- Expertise Access: Specialized knowledge available through automated routing
- Consistency: Standardized expert-level responses
- Scalability: Handle multiple complex inquiries simultaneously
- Cost Efficiency: Reduce need for human specialists
- Speed: Faster resolution through appropriate routing
- Quality: Higher accuracy through specialization

Measurement Approaches:
- Time savings through efficient delegation
- Improved first-contact resolution rates
- Reduced human expert intervention needs
- Higher customer satisfaction scores
- Increased throughput capacity
- Better knowledge retention and application

Strategic Advantages

Competitive Benefits:
- Always-available expertise across all domains
- Consistent quality regardless of volume
- Rapid scaling of specialized capabilities
- Continuous learning and improvement
- Cost-effective expert knowledge deployment
- Enhanced customer experience through specialization

🎯 Sub-Agent Deployment Checklist

Before implementing sub-agent architecture:

🛠️ Complete Configuration Example

Scenario: Customer Support Multi-Agent System

Here's a complete example showing how to configure a customer support agent with three specialized sub-agents:

Step 1: Create Sub-Agents

Sub-Agent 1: Technical Support Specialist

Agent Name: Technical Support Specialist
Tab 2 (Model): Claude 4.5 Sonnet, Temperature: 0.3
Tab 3 (Instructions): "You are a technical support expert specializing in
                       troubleshooting software issues, API integrations,
                       and system configurations."
Tab 4 (Knowledge): Technical docs, API documentation, troubleshooting guides
Tab 5 (Tools): Database query tool, log analysis workflow

Sub-Agent 2: Billing Specialist

Agent Name: Billing Specialist
Tab 2 (Model): GPT-4.1, Temperature: 0.2
Tab 3 (Instructions): "You are a billing expert who handles payment inquiries,
                       subscription changes, and invoice questions."
Tab 4 (Knowledge): Billing policies, pricing documentation, payment FAQs
Tab 5 (Tools): Billing system integration, payment gateway workflow

Sub-Agent 3: Product Expert

Agent Name: Product Expert
Tab 2 (Model): Claude 4.5 Opus, Temperature: 0.4
Tab 3 (Instructions): "You are a product specialist who explains features,
                       provides usage guidance, and recommends solutions."
Tab 4 (Knowledge): Product documentation, feature guides, use case examples
Tab 5 (Tools): Product demo workflow, feature documentation search

Step 2: Configure Primary Agent

Primary Agent: Customer Support Coordinator

Agent Name: Customer Support Coordinator
Tab 2 (Model): GPT-4.1, Temperature: 0.4

Tab 3 (Instructions):
"You are a customer support coordinator who helps users with their inquiries.
You have access to three specialized agents:
- Technical Support Specialist for technical issues
- Billing Specialist for payment and subscription matters
- Product Expert for feature questions and usage guidance

Analyze each user request and delegate to the appropriate specialist when needed.
You can also handle general questions directly."

Tab 7 (Sub-Agents):

Step 3: Add Sub-Agents in Tab 7

Sub-Agent Configuration 1:

Selected Agent: Technical Support Specialist
Description:
"Use this agent when users report bugs, errors, technical issues,
API problems, integration challenges, or need help with system
configuration and troubleshooting. This agent has access to technical
documentation and can query system logs."

Sub-Agent Configuration 2:

Selected Agent: Billing Specialist
Description:
"Delegate to this agent for all billing-related inquiries including
payment issues, invoice questions, subscription changes, pricing
information, refund requests, and account balance questions.
This agent can access billing systems and payment records."

Sub-Agent Configuration 3:

Selected Agent: Product Expert
Description:
"Use this agent when users ask about product features, capabilities,
how to use specific functionality, best practices, or need product
recommendations. This agent provides detailed feature explanations
and usage guidance."

Step 4: Test Your Multi-Agent System

Test Case 1: Technical Issue

User: "I'm getting a 500 error when I try to create a new workflow"
Expected: Primary agent delegates to Technical Support Specialist
Result: Detailed troubleshooting steps and resolution

Test Case 2: Billing Question

User: "How do I upgrade to the enterprise plan?"
Expected: Primary agent delegates to Billing Specialist
Result: Upgrade process, pricing details, and subscription management

Test Case 3: Product Question

User: "What's the difference between agents and workflows?"
Expected: Primary agent delegates to Product Expert
Result: Clear explanation of both concepts and when to use each

Test Case 4: General Question

User: "What are your support hours?"
Expected: Primary agent handles directly (no delegation needed)
Result: Support hours and contact information

🎯 Configuration Best Practices

Sub-Agent Description Writing Tips

1. Be Specific About Scope

✅ Good: "Use for API authentication errors, webhook configuration issues,
         and integration troubleshooting"
❌ Poor: "Use for technical issues"

2. Mention Available Tools/Knowledge

✅ Good: "This agent has access to billing records and can process refunds"
❌ Poor: "This agent handles billing"

3. Include Example Scenarios

✅ Good: "Delegate when users mention: payment failed, invoice missing,
         subscription cancellation, or upgrade requests"
❌ Poor: "For billing stuff"

4. Clarify Boundaries

✅ Good: "Handles product features and usage. Does NOT handle billing
         or technical troubleshooting"
❌ Poor: "Product agent"

Common Configuration Mistakes

❌ Overlapping Responsibilities

Problem: Two sub-agents with similar descriptions
Sub-Agent 1: "Handles customer questions"
Sub-Agent 2: "Answers user inquiries"
Solution: Define distinct, non-overlapping domains

❌ Missing Context in Descriptions

Problem: Description doesn't explain when to use
"Technical support agent"
Solution: Provide clear delegation criteria
"Use when users report errors, bugs, or technical issues..."

❌ Too Many Sub-Agents

Problem: 10+ sub-agents causing delegation confusion
Solution: Start with 2-4 specialized agents, expand as needed

❌ Sub-Agents Missing Required Tools

Problem: Billing sub-agent has no billing system access
Solution: Ensure sub-agents have necessary tools in Tab 5

📋 Quick Reference

Configuration Checklist

Before deploying your multi-agent system:

When to Use Sub-Agents

✅ Use Sub-Agents When:

You need specialized expertise in different domains
Different tasks require different knowledge bases
You want to separate concerns (billing, technical, sales)
Different workflows/tools needed for different request types
You need to scale specialized capabilities independently

❌ Don't Use Sub-Agents When:

Single domain/expertise is sufficient
All requests can be handled with same knowledge/tools
Adding complexity without clear benefit
Sub-agents would just duplicate primary agent's capabilities

Transform your AI agent from a single assistant into an intelligent team of specialists—each expert bringing deep knowledge and specialized capabilities to solve complex challenges.

PreviousAgent Sharing NextAgent Variables

Last updated 1 month ago