Subagents & Multi-Agent Hierarchy

Overview

Subagents allow you to create a hierarchy of agents where a parent agent delegates specific tasks to specialized child agents. This enables more complex, modular, and maintainable agent architectures. TalkifAI automatically creates handoff tools for each subagent, allowing the parent agent to seamlessly transfer conversations to specialists when needed. Best for:

Complex workflows with multiple stages
Agents requiring different expertise areas
Scalable agent systems
Separation of concerns in conversation handling

How It Works

User Call
    │
    ▼
Parent Agent (Main Controller)
    │
    ├──→ [Handoff Tool] → Subagent 1: Greeting & Triage
    │    "Hello! How can I help you today?"
    │
    ├──→ [Handoff Tool] → Subagent 2: Technical Support
    │    "Let me help you troubleshoot..."
    │
    ├──→ [Handoff Tool] → Subagent 3: Billing Specialist
    │    "I can help with your invoice..."
    │
    └──→ [Return Tool] → Parent Agent
         "Thank you for calling. Have a great day!"

Key Features:

Automatic handoff tools — Parent agent automatically gets transfer_to_{subagent} tools
Return mechanism — Subagents can return control to parent agent
Sibling handoffs — Subagents can transfer to other subagents
Inherited settings — Subagents inherit parent’s functions and knowledge bases

Architecture

Parent Agent

The parent agent is the main entry point:

Receives all incoming calls
Handles initial greeting and triage
Has automatic handoff tools to transfer to subagents
Manages conversation flow
Handles closing and follow-up

Requirements:

Must use Pipeline architecture (enforced by API)
Acts as orchestrator/controller
Cannot be Realtime or Text architecture

Automatic Tools Created:

# For each subagent, parent gets:
transfer_to_sales_agent()
transfer_to_billing_specialist()
transfer_to_technical_support()

Subagents

Subagents are specialized agents:

Handle specific conversation stages
Have their own system prompts and models
Can use different voices and temperatures
Inherit parent’s functions automatically
Cannot be called directly by users (only via parent)

Automatic Tools Created:

# Each subagent gets:
return_to_parent()  # Return control to parent
transfer_to_sibling_agent()  # Transfer to other subagents

Inherited Settings:

✅ Functions (enabled on parent)
✅ Knowledge bases (linked to parent)
✅ Organization context
✅ Authentication

Independent Settings:

✅ System prompt
✅ Model (can differ from parent)
✅ Temperature
✅ Voice (for realtime/pipeline)

Step 1: Create Parent Agent

Configure Parent Agent

Create a new agent with Pipeline architecture
Set up basic configuration:
- Name: “Customer Support Main”
- System prompt: Orchestration logic
- Model: GPT-4o or similar (for reasoning)
- Voice: Professional, clear

Subagents only work with Pipeline architecture. If you try to add subagents to a Realtime or Text agent, the API will return an error.

Parent Agent System Prompt

You are the main customer support agent for Acme Corp.

## Your Role
You coordinate the conversation and route to specialists as needed.

## Conversation Flow
1. Greet the customer warmly
2. Ask how you can help
3. Identify the type of request:
   - Technical issue → Use transfer_to_technical_support tool
   - Billing question → Use transfer_to_billing_specialist tool
   - General inquiry → Handle yourself
4. After resolution, confirm satisfaction
5. Close the call professionally

## Using Handoff Tools
When you need a specialist:
1. Briefly explain: "Let me connect you with our technical specialist..."
2. Call the appropriate transfer_to_* tool
3. The system will handle the handoff automatically

Step 2: Create Subagents

Create Subagent via Studio

Go to your agent → Settings → Subagents section
Click Add Subagent
Configure subagent:

Field	Required	Description
Name	✅	Internal identifier (e.g., “Technical Support”)
Description	✅	What this subagent handles (used by parent for routing)
System Prompt	✅	Specialized instructions for this subagent
Model	❌	Defaults to parent’s model (GPT-4o Mini, GPT-4.1, or Gemini)
Temperature	❌	Defaults to 0.7 (0.0-1.0 range)
Function Calling	❌	Inherited from parent + custom functions

Click Save

Create Subagent via API

POST /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Technical Support Specialist",
  "description": "Handles technical troubleshooting and product support",
  "sysMsg": "You are a technical support specialist with deep product knowledge...",
  "model": "gpt_4o_mini",
  "temperature": 0.3,
  "functionCallingEnabled": true,
  "enabledFunctions": [],
  "enabledCustomFunctions": []
}

Response:

{
  "subagent": {
    "id": "subagent_abc123",
    "name": "Technical Support Specialist",
    "description": "Handles technical troubleshooting and product support",
    "sysMsg": "You are a technical support specialist...",
    "model": "gpt_4o_mini",
    "temperature": 0.3,
    "agentArchitecture": "pipeline",
    "functionCallingEnabled": true,
    "enabledFunctions": [],
    "enabledCustomFunctions": [],
    "agentId": "agent_xyz789",
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-10T09:00:00Z"
  }
}

Example Subagent Prompts

Technical Support Subagent:

You are a technical support specialist for Acme Corp products.

## Your Expertise
- Product setup and configuration
- Troubleshooting errors and bugs
- Feature explanations
- Integration support

## Process
1. Ask for specific error messages or symptoms
2. Walk through troubleshooting steps systematically
3. If unresolved, use return_to_parent to escalate
4. Document the issue and solution

## Tone
- Patient and methodical
- Use simple language, avoid jargon
- Confirm understanding at each step

Billing Subagent:

You are a billing specialist for Acme Corp.

## Your Responsibilities
- Invoice inquiries and explanations
- Payment processing support
- Refund requests
- Subscription changes
- Pricing questions

## Guidelines
- Always verify customer identity first
- Never promise refunds — use "I can initiate a refund request"
- For disputes, use return_to_parent to escalate to billing manager
- Be empathetic but professional

## Available Tools
- check_invoice: Get invoice details
- process_refund_request: Initiate refund
- update_subscription: Modify subscription

Step 3: Understanding Automatic Handoffs

How Handoff Tools Work

When you create subagents, the system automatically creates tools for navigation: Parent Agent Gets:

transfer_to_technical_support()
transfer_to_billing_specialist()
# One tool per subagent

Each Subagent Gets:

return_to_parent()  # Return control to parent agent
transfer_to_technical_support()  # Transfer to siblings
transfer_to_billing_specialist()

Handoff Strategies

1. Sequential Handoff

Greeting → Triage → Specialist → Closing

Use Case: Structured workflows (support, sales) Example:

Parent: "Hello! How can I help you today?"
User: "I have a billing question"
Parent: [Calls transfer_to_billing_specialist]
Billing: "I can help with your invoice. What's your account number?"

2. Conditional Handoff

If technical → Technical subagent
If billing → Billing subagent
Else → Handle directly

Use Case: Multi-department support 3. Consultative Handoff

Main agent handles conversation
Consults subagent for specific questions via tool calls
Returns to main agent

Use Case: Specialized queries within general conversation

Implementing Handoff in System Prompt

## Using Your Handoff Tools

You have access to specialist tools:
- transfer_to_technical_support: For product issues and bugs
- transfer_to_billing_specialist: For invoices and payments

When to use handoff tools:
1. User asks about topics outside your expertise
2. User requests a specific department
3. Issue requires specialized knowledge

How to use:
1. Briefly explain: "Let me connect you with our specialist..."
2. Call the appropriate transfer_to_* tool
3. The system handles the rest automatically

Step 4: Manage Subagents

List Subagents

Via Studio:

Go to your agent → Settings → Subagents
See all subagents in creation order

Via API:

GET /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY

Response:

{
  "subagents": [
    {
      "id": "subagent_abc123",
      "name": "Technical Support Specialist",
      "description": "Handles technical troubleshooting",
      "sysMsg": "You are a technical support specialist...",
      "model": "gpt_4o_mini",
      "temperature": 0.3,
      "agentArchitecture": "pipeline",
      "functionCallingEnabled": true,
      "enabledFunctions": [],
      "enabledCustomFunctions": [],
      "createdAt": "2024-01-10T09:00:00Z",
      "updatedAt": "2024-01-10T09:00:00Z"
    }
  ]
}

Update Subagent

Via Studio:

Go to agent → Settings → Subagents
Click Edit (pencil icon) on subagent
Modify settings
Click Save

Via API:

PUT /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "id": "subagent_abc123",
  "name": "Senior Technical Support",
  "description": "Handles complex technical issues",
  "sysMsg": "You are a senior technical support specialist...",
  "model": "gpt_4o_mini",
  "temperature": 0.2,
  "functionCallingEnabled": true,
  "enabledFunctions": [],
  "enabledCustomFunctions": []
}

Delete Subagent

Via Studio:

Go to agent → Settings → Subagents
Click Delete (trash icon)
Confirm deletion

Via API:

DELETE /api/agents/{agentId}/subagents?subagentId={subagentId}
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "message": "Subagent deleted successfully"
}

Advanced Patterns

Pattern 1: Tiered Support

Level 1: General Support (Parent)
    │
    ├──→ Level 2: Technical Specialist
    │       │
    │       └──→ [Return to Parent for follow-up]
    │
    └──→ Level 2: Billing Specialist
            │
            └──→ [Return to Parent for follow-up]

Use Case: Multi-tier support organizations

Pattern 2: Department-Based Routing

Receptionist (Parent)
    │
    ├──→ Sales Department
    ├──→ Support Department
    ├──→ Billing Department
    └──→ HR Department

Use Case: Company phone systems

Pattern 3: Geographic Routing

Main Agent (English)
    │
    ├──→ Spanish Subagent
    ├──→ French Subagent
    └──→ German Subagent

Use Case: Multi-language support

Pattern 4: Task-Specialized Pipeline

Greeting Agent (Parent)
    │
    ▼
Qualification Subagent
    │
    ▼
Solution Subagent
    │
    ▼
[Return to Parent] → Closing Agent

Use Case: Highly structured workflows

Best Practices

Clear Responsibilities

Each subagent should have a well-defined scope. Avoid overlap between subagents to prevent confusion.

Descriptive Names

Use clear, descriptive names for subagents. The parent agent uses these names to decide which handoff tool to call.

Consistent Voice

Use similar voice settings across subagents for a cohesive customer experience.

Context Preservation

Write system prompts that reference conversation history. Subagents can see the full conversation so far.

Fallback Handling

Always have a fallback — instruct subagents to use return_to_parent if they can’t help.

Test End-to-End

Test full conversation flows including all handoffs before going live. Verify each transfer works smoothly.

Limitations

Current Limitations

Limitation	Workaround
Subagents only work with Pipeline architecture	Use Pipeline for parent agent (required)
Subagents inherit parent’s functions	Configure all needed functions on parent agent
Handoff is tool-based (LLM decides)	Write clear system prompts with handoff examples
Subagents can’t be called directly	All calls must go through parent agent
No nested subagents	Use sibling handoffs instead (subagent → subagent)

Technical Notes

Maximum subagents: No enforced limit (test with your use case)
Model flexibility: Each subagent can use different models
Voice independence: Subagents can have different voice settings
Function inheritance: All parent functions available to subagents

Troubleshooting

Subagent isn't being activated

Check:

Is subagent properly configured with name and description?
Does parent prompt mention when to use handoff tools?
Are trigger conditions clearly defined in parent prompt?
Is function calling enabled on the parent agent?

Fix: Add explicit handoff examples to parent prompt:

When user mentions "bug" or "error", call transfer_to_technical_support
When user asks about "invoice" or "payment", call transfer_to_billing_specialist

Handoff is abrupt or confusing

Problem: Handoff protocol not defined clearly.Solution: Add to parent prompt:

Before transferring:
Explain what you're doing: "Let me connect you with..."
Summarize the issue briefly
Confirm customer is ready (optional)

Subagent loses conversation context

Problem: Context not passed during handoff.Solution: This shouldn’t happen — subagents automatically see the full conversation history. If issues persist:

Include context summary in subagent’s system prompt
Use return_to_parent with context: “I’ve helped with X, but Y needs parent assistance”

Too many subagents causing confusion

Problem: Over-complicated agent hierarchy.Solution:

Consolidate similar subagents
Use conditional logic in parent prompt instead of separate subagents
Limit to 3-5 subagents for most use cases

API returns 'Subagent not found'

Problem: The subagent ID doesn’t exist or doesn’t belong to this agent.Solution:

Verify the subagent ID with GET /api/agents/{agentId}/subagents
Ensure you’re using the correct agent ID in the URL
Check that the subagent wasn’t deleted

Can't add subagent to agent

Error: “Subagents can only be added to pipeline architecture agents”Solution: Change the parent agent’s architecture to Pipeline, or create a new Pipeline agent.

API Reference

Create Subagent

POST /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "string (required, max 100 chars)",
  "description": "string (required, max 500 chars)",
  "sysMsg": "string (required, max 5000 chars)",
  "model": "gpt_4o_mini | gpt_4_1 | gemini (default: gpt_4o_mini)",
  "temperature": "number 0.0-1.0 (default: 0.7)",
  "functionCallingEnabled": "boolean (default: false)",
  "enabledFunctions": "string[] (built-in function IDs)",
  "enabledCustomFunctions": "string[] (custom function IDs)"
}

Validation Errors:

Status	Error	Cause
`400`	”Subagent name is required”	Missing or empty name
`400`	”System message is required”	Missing or empty sysMsg
`400`	”Subagents can only be added to pipeline architecture agents”	Parent is not Pipeline
`403`	”You don’t have permission…”	User lacks edit rights

List Subagents

GET /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY

Response:

{
  "subagents": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "sysMsg": "string",
      "model": "string",
      "temperature": "number",
      "agentArchitecture": "pipeline",
      "functionCallingEnabled": "boolean",
      "enabledFunctions": "string[]",
      "enabledCustomFunctions": "string[]",
      "agentId": "string",
      "createdAt": "ISO 8601 datetime",
      "updatedAt": "ISO 8601 datetime"
    }
  ]
}

Update Subagent

PUT /api/agents/{agentId}/subagents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "id": "string (subagent ID, required)",
  "name": "string",
  "description": "string",
  "sysMsg": "string",
  "model": "string",
  "temperature": "number",
  "functionCallingEnabled": "boolean",
  "enabledFunctions": "string[]",
  "enabledCustomFunctions": "string[]"
}

Delete Subagent

DELETE /api/agents/{agentId}/subagents?subagentId={id}
Authorization: Bearer YOUR_API_KEY

Response:

{
  "success": true,
  "message": "Subagent deleted successfully"
}

Technical Implementation

Backend Architecture

Subagents are implemented using the Unified Agent system in the backend:

Parent Agent receives UnifiedAgentConfig with subagents array
Handoff Tools are automatically generated for each subagent
Subagent Personas are created as separate agent instances
Session Management handles seamless transfers between agents

Handoff Tool Generation

# Parent agent gets these tools automatically:
for subagent in config.subagents:
    create_handoff_tool(
        name=f"transfer_to_{subagent.name.lower()}",
        description=subagent.description,
        target_id=subagent.id
    )

# Subagents get return tool + sibling tools:
create_return_to_parent_tool()
for sibling in siblings:
    create_handoff_tool(
        name=f"transfer_to_{sibling.name.lower()}",
        target_id=sibling.id
    )

Session Flow

User calls → Parent agent session created
Parent handles conversation
Parent calls transfer_to_X tool
System creates X's session with conversation context
X handles conversation
X calls return_to_parent or transfer_to_Y
System switches session accordingly

Next Steps

Create Parent Agent

Set up your main orchestrator agent with Pipeline architecture.

Add Subagents

Create specialized subagents for different tasks via Studio or API.

Test Handoffs

Test conversation flows with subagent transfers to verify smooth handoffs.

Monitor Performance

Track which subagents are used most and optimize accordingly.

Agent Architecture — Pipeline vs Realtime vs Text
Custom Functions — Add actions to your agents
System Prompt Guide — Writing effective prompts
API Reference — Full agents API documentation

​Overview

​How It Works

​Architecture

​Parent Agent

​Subagents

​Step 1: Create Parent Agent

​Configure Parent Agent

​Parent Agent System Prompt

​Step 2: Create Subagents

​Create Subagent via Studio

​Create Subagent via API

​Example Subagent Prompts

​Step 3: Understanding Automatic Handoffs

​How Handoff Tools Work

​Handoff Strategies

​Implementing Handoff in System Prompt

​Step 4: Manage Subagents

​List Subagents

​Update Subagent

​Delete Subagent

​Advanced Patterns

​Pattern 1: Tiered Support

​Pattern 2: Department-Based Routing

​Pattern 3: Geographic Routing

​Pattern 4: Task-Specialized Pipeline

​Best Practices

Clear Responsibilities

Descriptive Names

Consistent Voice

Context Preservation

Fallback Handling

Test End-to-End

​Limitations

​Current Limitations

​Technical Notes

​Troubleshooting

​API Reference

​Create Subagent

​List Subagents

​Update Subagent

​Delete Subagent

​Technical Implementation

​Backend Architecture

​Handoff Tool Generation

​Session Flow

​Next Steps

Create Parent Agent

Add Subagents

Test Handoffs

Monitor Performance

​Related Documentation

Overview

How It Works

Architecture

Parent Agent

Subagents

Step 1: Create Parent Agent

Configure Parent Agent

Parent Agent System Prompt

Step 2: Create Subagents

Create Subagent via Studio

Create Subagent via API

Example Subagent Prompts

Step 3: Understanding Automatic Handoffs

How Handoff Tools Work

Handoff Strategies

Implementing Handoff in System Prompt

Step 4: Manage Subagents

List Subagents

Update Subagent

Delete Subagent

Advanced Patterns

Pattern 1: Tiered Support

Pattern 2: Department-Based Routing

Pattern 3: Geographic Routing

Pattern 4: Task-Specialized Pipeline

Best Practices

Limitations

Current Limitations

Technical Notes

Troubleshooting

API Reference

Create Subagent

List Subagents

Update Subagent

Delete Subagent

Technical Implementation

Backend Architecture

Handoff Tool Generation

Session Flow

Next Steps

Related Documentation