Transfer Agent Node

Overview

Transfer agent nodes hand off the conversation to a different Hamsa AI agent within your workspace. Unlike transfer call nodes that connect to external phone numbers, transfer agent nodes keep the conversation within your AI ecosystem with optional context preservation. Key characteristic: Transfer agent nodes maintain the call connection while switching which AI agent is handling the conversation—no phone system transfer needed.

When to Use

Use transfer agent nodes to:

Specialist routing - Technical support, billing, sales specialists
Language switching - English → Spanish → Mandarin agents
Skill-based routing - Route to agents with specific capabilities
Complexity escalation - Simple → advanced agent for complex issues
Department handoff - Different agents for different departments
Workflow stages - Lead qualification → sales closing agents
Regional expertise - Route to agents familiar with specific regions
Product-specific agents - Different agents for different product lines

Use Transfer Agent Node when:

Destination is another Hamsa AI agent
Want the option to preserve conversation history and variables
Need faster, more reliable transfers than phone transfers
Staying within your AI agent ecosystem
Want seamless transitions without hold music or ringing

Use Transfer Call Node instead when:

Transferring to human agents at phone numbers
Connecting to external phone systems
Regulatory requirements for human interaction
Need to connect to traditional phone lines

→ Compare: Transfer Call Node

Core Configuration

{
  type: "transfer_agent",
  label?: string,
  description?: string,

  // Target agent (required)
  agentId: string,  // ID of the Hamsa agent to transfer to

  // Handoff options
  handoffConversation: boolean,  // default: false — transfer conversation history
  handoffVariables: boolean,     // default: false — transfer extracted variables

  // Transfer message (optional)
  transferMessage?: string,
  transferMessageType: "static" | "prompt",  // Default: "static"

  // Timeout
  timeout: number,  // milliseconds, default: 30000

  // Global node settings
  isGlobal?: boolean,
  globalConditionType?: "prompt" | "dtmf",
  globalCondition?: string,
  globalDtmfKey?: string,

  // Transitions (usually none needed)
  transitions?: Transition[]
}

Agent Selection

Selecting the Target Agent

Click on the Transfer Agent Node
In configuration panel, click Select Agent
Choose from available agents in your workspace
Agent details auto-populate (name, ID)

Available agents:

All Flow Agents in your workspace
All Single Prompt Agents in your workspace
Agents from same project

You can only transfer to agents within your workspace. Agents in other workspaces are not accessible.

Agent ID

Each agent has a unique ID used for transfers.

Transfer Agent Node: Transfer_To_Spanish
  agentId: "agent_abc123xyz"  # Spanish support agent

Using Variables for Dynamic Routing

# Extract or determine which agent to use
Router Node: Language_Router
  transitions:
    - Equation: {{preferred_language}} == "spanish"
      → Transfer_Spanish
    - Equation: {{preferred_language}} == "french"
      → Transfer_French

Transfer Agent Node: Transfer_Spanish
  agentId: "spanish_support_agent_id"

Transfer Agent Node: Transfer_French
  agentId: "french_support_agent_id"

Transfer Message

Static Message (Default)

Exact message spoken before transfer.

Transfer Agent Node: Transfer_To_Tech_Support
  agentId: "tech_support_agent"

  Transfer Message:
    message: "I'm connecting you with our technical specialist who can better assist you."
    messageType: static

Use static when:

Professional, consistent messaging
Short, simple transfer announcement
No personalization needed

Prompt-Based Message

AI generates contextual transfer message.

Transfer Agent Node: Transfer_To_Billing
  agentId: "billing_agent"

  Transfer Message:
    message: "Explain to the user that you're transferring them to a billing specialist who can help with their specific question about invoices."
    messageType: prompt

AI might say:

“Let me connect you with our billing team who specializes in invoice questions.”
“I’m getting you to someone in billing who can review your invoices.”

Use prompt when:

Want natural, conversational transfer
Personalization based on context
Flexible, adaptive messaging

Message with Variables

Reference conversation data in transfer message.

Transfer Agent Node: Transfer_Premium_Support
  agentId: "premium_support_agent"

  Transfer Message:
    message: "Thank you {{customer_name}}. As a {{tier}} member, I'm connecting you with our premium support specialist."
    messageType: static

Silent Transfer (No Message)

Omit transfer message for instant, seamless transition.

Transfer Agent Node: Silent_Transfer
  agentId: "specialist_agent"
  # No transferMessage configured - instant transfer

Timeout Configuration

Set maximum wait time for transfer to complete.

Transfer Agent Node: Quick_Transfer
  agentId: "sales_agent"
  timeout: 15000  # 15 seconds

Default: 30000ms (30 seconds) Range: 1000ms - 60000ms (1-60 seconds) Recommendations:

Agent transfers: 15-30 seconds (faster than phone transfers)
Critical transfers: 10-15 seconds
Non-critical: 30 seconds

Agent transfers are typically much faster than phone transfers since there’s no phone system involved. Most complete in under 1 second.

Handoff Options

Transfer agent nodes can optionally pass context to the receiving agent. Both options are off by default — enable them when the new agent needs prior context.

Handoff Conversation

When enabled, the full conversation history (user inputs and agent responses) is transferred to the new agent. The receiving agent can reference what was discussed without asking the user to repeat themselves.

Transfer Agent Node: Transfer_To_Billing
  agentId: "billing_agent"
  handoffConversation: true  # New agent sees full chat history

Handoff Variables

When enabled, all extracted variables from the current flow are passed to the new agent and available in its prompts.

Transfer Agent Node: Transfer_To_Specialist
  agentId: "specialist_agent"
  handoffVariables: true  # New agent has access to {{customer_name}}, {{account_id}}, etc.

Both Enabled (Full Context Transfer)

For a seamless handoff where the new agent has complete context:

Transfer Agent Node: Transfer_Premium_Support
  agentId: "premium_support_agent"
  handoffConversation: true
  handoffVariables: true
  transferMessage: "I'm connecting you with a specialist who has your full details."

The receiving agent can immediately reference previous conversation and extracted data — no repeated questions.

Both handoffConversation and handoffVariables default to false. If you need the new agent to have context, you must explicitly enable them.

Use Cases & Examples

Example 1: Language Switching

Scenario: Transfer English speaker to Spanish-speaking agent.

Conversation Node: Detect_Language
  message: "For English, press 1. Para español, oprima 2."
  transitions:
    - DTMF: key=1 → English_Flow
    - DTMF: key=2 → Transfer_Spanish

Transfer Agent Node: Transfer_Spanish
  agentId: "spanish_support_agent_id"

  Transfer Message:
    message: "Let me connect you with our Spanish-speaking representative."
    messageType: static

  timeout: 15000

Example 2: Technical Support Escalation

Scenario: Basic support agent transfers complex technical issues.

Conversation Node: Diagnose_Issue
  message: "Can you describe the technical problem you're experiencing?"

  Extract Variables:
    - issue_description: "Description of the issue"
    - issue_complexity: "Rate complexity: simple, moderate, complex"

  transitions:
    - Equation: {{issue_complexity}} == "complex" → Transfer_Tech_Specialist
    - Always → Attempt_Basic_Support

Transfer Agent Node: Transfer_Tech_Specialist
  agentId: "advanced_tech_support_agent"

  Transfer Message:
    message: "This sounds like a complex issue. Let me connect you with one of our senior technical specialists who can help."
    messageType: static

Example 3: Department Routing

Scenario: Route to specialized department agents.

Conversation Node: Identify_Department
  message: "Are you calling about sales, technical support, or billing?"

  transitions:
    - Natural Language: "sales" → Transfer_Sales
    - Natural Language: "technical" → Transfer_Tech
    - Natural Language: "billing" → Transfer_Billing

Transfer Agent Node: Transfer_Sales
  agentId: "sales_specialist_agent"
  transferMessage: "Connecting you with our sales team."

Transfer Agent Node: Transfer_Tech
  agentId: "tech_support_agent"
  transferMessage: "Connecting you with technical support."

Transfer Agent Node: Transfer_Billing
  agentId: "billing_specialist_agent"
  transferMessage: "Connecting you with our billing department."

Example 4: VIP Customer Routing

Scenario: High-value customers get specialized agent.

Tool Node: Lookup_Customer
  outputMapping:
    customer_tier: $.tier
    lifetime_value: $.ltv
  transitions:
    - Always → Tier_Router

Router Node: Tier_Router
  transitions:
    - Structured Equation (logic: all):
        - {{customer_tier}} == "vip"
        - {{lifetime_value}} >= 50000
      → Transfer_VIP_Concierge

    - Always → Standard_Support

Transfer Agent Node: Transfer_VIP_Concierge
  agentId: "vip_concierge_agent"

  Transfer Message:
    message: "As a VIP member, I'm connecting you with your dedicated concierge specialist."
    messageType: static

Example 5: Product Specialist Routing

Scenario: Route to agents specialized in specific products.

Conversation Node: Identify_Product
  message: "Which product do you need help with?"

  Extract Variables:
    - product_name: "Product name"

  transitions:
    - Always → Product_Router

Router Node: Product_Router
  transitions:
    - Equation: {{product_name}} contains "Enterprise"
      → Transfer_Enterprise_Specialist

    - Equation: {{product_name}} contains "API"
      → Transfer_API_Specialist

    - Always → Transfer_General_Product_Support

Transfer Agent Node: Transfer_Enterprise_Specialist
  agentId: "enterprise_product_agent"
  transferMessage: "Connecting you with our Enterprise product specialist."

Transfer Agent Node: Transfer_API_Specialist
  agentId: "api_specialist_agent"
  transferMessage: "Let me connect you with our API specialist."

Example 6: Sales Pipeline Handoff

Scenario: Qualification agent hands off to closing agent.

Conversation Node: Qualify_Lead
  message: "Let me understand your needs..."

  Extract Variables:
    - budget: "Budget amount"
    - timeline: "Purchase timeline"
    - decision_maker: "Are they the decision maker"

  transitions:
    - Always → Qualification_Router

Router Node: Qualification_Router
  transitions:
    - Structured Equation (logic: all):
        - {{budget}} >= 10000
        - {{timeline}} == "immediate"
        - {{decision_maker}} == true
      → Transfer_Closing_Agent

    - Always → Continue_Nurture

Transfer Agent Node: Transfer_Closing_Agent
  agentId: "sales_closing_specialist"

  Transfer Message:
    message: "Based on your needs, I'm connecting you with {{sales_rep_name}} who can finalize the details with you."
    messageType: static

Example 7: After-Hours Language Support

Scenario: Route to 24/7 multilingual support after hours.

Router Node: Hours_And_Language_Check
  transitions:
    - Structured Equation (logic: all):
        - {{current_hour}} < 9 OR {{current_hour}} >= 17
        - {{preferred_language}} != "english"
      → Transfer_24_7_Multilingual

    - Always → Standard_Support

Transfer Agent Node: Transfer_24_7_Multilingual
  agentId: "multilingual_24_7_agent"

  Transfer Message:
    message: "I'm connecting you with our 24/7 multilingual support team."
    messageType: static

Example 8: Global Transfer (Anytime Access)

Scenario: Press 9 anytime to speak with a supervisor agent.

Transfer Agent Node: Supervisor_Transfer
  # Global configuration
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 9

  # Transfer configuration
  agentId: "supervisor_agent_id"

  Transfer Message:
    message: "I'm transferring you to a supervisor now."
    messageType: static

Advantages Over Phone Transfers

Feature	Transfer Agent Node	Transfer Call Node
Speed	Faster (no phone transfer)	Slower (phone system)
Context	Optional (handoff toggles)	Lost (new call)
Reliability	Very high	Depends on phone network
User Experience	Seamless	Hold music, ringing
Costs	No additional cost	Telephony transfer costs
Variables	Optional (handoff toggle)	Not transferred
Conversation History	Optional (handoff toggle)	Starts fresh
Setup	Just agent ID	Phone number needed

Global Agent Transfers

Make transfer agent nodes accessible from anywhere in the flow.

Global via DTMF

Transfer Agent Node: Global_Supervisor
  isGlobal: true
  globalConditionType: dtmf
  globalDtmfKey: 9

  agentId: "supervisor_agent_id"
  transferMessage: "Connecting you with a supervisor."

Press 9 from any node to transfer to supervisor.

Global via Natural Language

Transfer Agent Node: Global_Specialist_Request
  isGlobal: true
  globalConditionType: prompt
  globalCondition: "User asks for a specialist or expert"

  agentId: "specialist_agent_id"
  transferMessage: "I'm connecting you with a specialist."

Say “I need a specialist” from any node to trigger transfer. → Learn More: Global Nodes

Troubleshooting

Issue: Transfer fails

Possible causes:

Target agent doesn’t exist
Target agent is inactive
Invalid agent ID
Agent in different workspace

Solution:

Verify agent exists and is active
Check agent ID is correct
Ensure agent is in same workspace
Test with different agent

Issue: Context not available in new agent

Possible causes:

Variables not extracted before transfer
Variable scope issue
Agent configuration error

Solution:

Verify variables are extracted before transfer
Check variable names are correct
Ensure variables are properly scoped
Test variable availability

Issue: Transfer message not playing

Possible causes:

Message field is empty
Message type misconfigured
Silent transfer configured

Solution:

Add transfer message content
Verify messageType setting
Check if silent transfer is intended

Issue: Timeout occurring

Possible causes:

Target agent has issues
Network problems
Timeout set too short

Solution:

Check target agent configuration
Increase timeout value
Test agent directly
Review agent logs

Flow Examples

Example Flow 1: Department Routing

Example Flow 2: Complexity-Based Routing

Example Flow 3: VIP Routing

Schema Reference

{
  type: "transfer_agent",
  label?: string,
  description?: string,

  // Target agent (required)
  agentId: string,  // UUID or ID of target Hamsa agent

  // Handoff options
  handoffConversation: boolean,  // default: false
  handoffVariables: boolean,     // default: false

  // Transfer message (optional)
  transferMessage?: string,
  transferMessageType: "static" | "prompt",  // Default: "static"

  // Timeout
  timeout: number,  // milliseconds, default: 30000

  // Global node settings
  isGlobal?: boolean,
  globalConditionType?: "prompt" | "dtmf",
  globalCondition?: string,  // For prompt-based global
  globalDtmfKey?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "*" | "#",

  // Transitions (optional, rarely needed)
  transitions?: Transition[],

  // Position
  position: { x: number, y: number }
}

Next Steps

Transfer Call Node

Transfer to external phone numbers

Router Node

Route to appropriate agent

Global Nodes

Make transfers accessible anytime

Variables

Pass context to new agent

Agent Management

Create and manage agents

Best Practices

Build better flows

Documentation Index

​Overview

​When to Use

​Core Configuration

​Agent Selection

​Selecting the Target Agent

​Agent ID

​Using Variables for Dynamic Routing

​Transfer Message

​Static Message (Default)

​Prompt-Based Message

​Message with Variables

​Silent Transfer (No Message)

​Timeout Configuration

​Handoff Options

​Handoff Conversation

​Handoff Variables

​Both Enabled (Full Context Transfer)

​Use Cases & Examples

​Example 1: Language Switching

​Example 2: Technical Support Escalation

​Example 3: Department Routing

​Example 4: VIP Customer Routing

​Example 5: Product Specialist Routing

​Example 6: Sales Pipeline Handoff

​Example 7: After-Hours Language Support

​Example 8: Global Transfer (Anytime Access)

​Advantages Over Phone Transfers

​Global Agent Transfers

​Global via DTMF

​Global via Natural Language

​Troubleshooting

​Issue: Transfer fails

​Issue: Context not available in new agent

​Issue: Transfer message not playing

​Issue: Timeout occurring

​Flow Examples

​Example Flow 1: Department Routing

​Example Flow 2: Complexity-Based Routing

​Example Flow 3: VIP Routing

​Schema Reference

​Next Steps

Transfer Call Node

Router Node

Global Nodes

Variables

Agent Management

Best Practices

Overview

When to Use

Core Configuration

Agent Selection

Selecting the Target Agent

Agent ID

Using Variables for Dynamic Routing

Transfer Message

Static Message (Default)

Prompt-Based Message

Message with Variables

Silent Transfer (No Message)

Timeout Configuration

Handoff Options

Handoff Conversation

Handoff Variables

Both Enabled (Full Context Transfer)

Use Cases & Examples

Example 1: Language Switching

Example 2: Technical Support Escalation

Example 3: Department Routing

Example 4: VIP Customer Routing

Example 5: Product Specialist Routing

Example 6: Sales Pipeline Handoff

Example 7: After-Hours Language Support

Example 8: Global Transfer (Anytime Access)

Advantages Over Phone Transfers

Global Agent Transfers

Global via DTMF

Global via Natural Language

Troubleshooting

Issue: Transfer fails

Issue: Context not available in new agent

Issue: Transfer message not playing

Issue: Timeout occurring

Flow Examples

Example Flow 1: Department Routing

Example Flow 2: Complexity-Based Routing

Example Flow 3: VIP Routing

Schema Reference

Next Steps