Node Types Reference

This is intended as a quick reference (not a tutorial) and works for chatbot engines, workflow DSLs, and LLM orchestration flows.

Each node type is documented with:

• YFlow syntax - How to write it in YFlow format

• Customer v2 data structure - The corresponding TypeScript interface from packages/model/src/

• Field mapping - How YFlow fields map to Customer v2 fields

Node Type	YFlow `type:`	Customer v2 `NodeType`	Purpose
Start	(implicit)	START	Flow entry point
End	end	END	Flow termination
Say	say	SAY	Output text/speech
Agent	agent	AGENT	GenAI conversation
Menu	menu	MENU	DTMF phone menu
API	api	API_CALL	REST API call
Transfer	transfer	TRANSFER	Call transfer
Tools	tools	TOOLS	MCP tool binding
Branch	branch	BRANCH	Conditional routing
Set	set	SET	Assign/compute variables

Common Node Properties

These properties apply to most or all node types, regardless of whether the node is message, decision, api_call, etc.

nodes:    
      - main_agent:    
          type: agent    
          pos: [200, 100] # Optional: UI position [x, y]    
          # ... node-specific fields    

Property	Type	Required	Description
pos	[x, y]	No	UI canvas position. If omitted, auto-layout applies.

Customer v2 Mapping:

    // Source: packages/model/src/flow/node-metadata.interface.ts    
    interface NodeMetadata {    
      x: number; // ← pos[0]    
      y: number; // ← pos[1]    
    }    

Behavior:

• If pos is present → use specified coordinates

• If pos is omitted → auto-layout calculates position on import

• Export always includes pos to preserve user's layout

Start Node

The start node is the entry point to the flow - it's whichever node is named start:

nodes:    
      - start:    
          next: main_menu    

Customer v2 Data Structure:

    // Source: packages/model/src/flow/nodes/start-node.interface.ts    
    interface StartNode extends Node {    
      readonly type: NodeType.START; // ← YFlow: node named "start"    
    }    
         
    // Source: packages/model/src/flow/node.interface.ts    
    interface Node {    
      nodeId: string; // ← Generated UUID    
      type: NodeType; // ← YFlow: type field    
      exits: Exit[]; // ← YFlow: next field    
      metadata: NodeMetadata; // ← UI position { x, y }    
    }    

Field Mapping:

Field Mapping describes how values from a source structure are copied, transformed, or derived into target variables used by subsequent nodes.

YFlow	Customer v2 Field	Notes
start: (key)	nodeId (generated)	Node identifier
(implicit)	type: NodeType.START	Auto-detected from node named start
next:	exits[0].nodeId	Single exit to next node

End Node:

End nodes terminate the flow. They require explicit type: end:

nodes:    
      # Named end node    
      - end_1:    
          type: end    
         
      # Multiple end points for different outcomes    
      - success_end:    
          type: end    
         
      - failure_end:    
          type: end    
         
      # Typical pattern: say node leading to end    
      - farewell:    
          type: say    
          message: Thank you for calling. Goodbye!    
          next: end_1    

Note: The target next: end routes to a node named end. If you have multiple end points, name them descriptively (e.g., end_1, success_end).

Customer v2 Data Structure:

    // Source: packages/model/src/flow/nodes/end-node.interface.ts    
    interface EndNode extends Node {    
      readonly type: NodeType.END; // ← YFlow: type: end    
    }

Field Mapping:

YFlow	Customer v2 Field	Notes
end_1: (key)	nodeId (generated)	Node identifier
type: end	type: NodeType.END	Direct mapping
(no exits)	exits: []	End nodes have no exits

Say Node

Say nodes output text or speech. They require explicit type: say:

    nodes:    
      # Standard say node    
      - greeting:    
          type: say    
          message: Welcome to our service!    
          next: main_agent    
         
      # Say with variable interpolation    
      - goodbye_message:    
          type: say    
          message: { goodbye_message } # From slot value    
          next: end    
         
      # Say with options (Possible Future enhancement)    
      - detailed_greeting:    
          type: say    
          message:    
            text: Welcome to our service!    
            voice: Matthew # Override flow voice    
            speed: 1.1 # Future: speech rate    
            lang: # Future: language variants    
              en-US: Welcome to our service!    
              es-MX: ¡Bienvenido a nuestro servicio!    
              fr-CA: Bienvenue à notre service!    
          next: main_agent    
         
      # Multi-line say using YAML literal block    
      - help_message:    
          type: say    
          message: |    
            I can help you with:    
            - Account questions    
            - Billing issues    
            - Technical support    
          next: main_agent    

Customer v2 Data Structure:

// Source: packages/model/src/flow/nodes/say-node.interface.ts    
    interface SayNode extends Node {    
      readonly type: NodeType.SAY; // ← YFlow: type: say    
      message: string; // ← YFlow: message field    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
greeting: (key)	nodeId (generated)	Node identifier
type: say	type: NodeType.SAY	Direct mapping
message:	message	Text/speech content
next:	exits[0].nodeId	Single exit to next node

Note: Variable interpolation {variable_name} in messages is resolved at runtime using session context variables.

Slots

Slots capture data from agent goals. Each slot has four properties:

Property	Required	Description
name	yes	The key in the slots map
type	yes	string, number, boolean, object
description	yes	What this slot captures (max 200 chars)
optional	no	If true, slot is not required (default: false)

goals:    
      search_character:    
        description: User wants to search for a character    
        slots:    
          character_name:    
            type: string    
            description: 'Name of the character to search for'    
         
          include_films:    
            type: boolean    
            description: 'Whether to include film appearances'    
            optional: true    
         
          max_results:    
            type: number    
            description: 'Maximum number of results to return'    
            optional: true    
        next: search_api    

Note: Slots default to required. Only add optional: true when the slot is truly optional.

Agent Node

Agent nodes are the heart of conversational AI:

nodes:    
      - main_agent:    
          type: agent    
         
          # System prompt - use YAML's literal block for multi-line    
          system: |    
            You are a helpful customer service agent.    
            Be friendly but professional.    
            When the user wants to check their balance, trigger the 'check_balance' goal.    
            When the user wants to end the call, trigger the 'goodbye' goal.    
         
          # Behavioral flags (all optional, default to false/0)    
          single_turn: false    
          take_initiative: false    
          iteration_limit: 5    
         
          # Optional: memory identifier for conversation context    
          memory_id: main_agent    
         
          # MCP tools (optional) - references a tools node by name    
          tools: customer_tools # See Tools Node section    
         
          # Goals define how the agent routes    
          goals:    
            check_balance:    
              description: User wants to check account balance    
              slots:    
                account_type:    
                  type: string    
                  description: 'Type of account (checking, savings)'    
              next: balance_api    
         
            goodbye:    
              description: User is done with the conversation    
              next: farewell    
         
          # Fallback is REQUIRED when iteration_limit is set    
          fallback:    
            next: fallback_message    
         
          # Error exit (optional) - runtime errors (e.g., LLM failure)    
          error:    
            next: error_handler    
         
      - fallback_message:    
          type: say    
          message: I'm sorry, I didn't understand that.    
          next: end    
         
      - error_handler:    
          type: say    
          message: An error occurred. Let me transfer you.    
          next: transfer_to_agent    

Customer v2 Data Structure:

// Source: packages/model/src/flow/nodes/agent-node.interface.ts    
    interface AgentNode extends Node {    
      readonly type: NodeType.AGENT; // ← YFlow: type: agent    
      name: string; // ← YFlow: node key (e.g., "main_agent")    
      systemPrompt: string; // ← YFlow: system field    
      iterationLimit?: number; // ← YFlow: iteration_limit    
      singleTurn: boolean; // ← YFlow: single_turn    
      takeInitiative: boolean; // ← YFlow: take_initiative    
      memoryIdentifier?: string; // ← YFlow: memory_id    
      tools?: string[]; // ← YFlow: tools (reference to tools node)    
      goals: AgentGoal[]; // ← YFlow: goals map → AgentGoal[]    
    }    
         
    // Source: packages/model/src/flow/nodes/agent/agent-goal.interface.ts    
    interface AgentGoal {    
      name: string; // ← YFlow: goal key (e.g., "check_balance")    
      description: string; // ← YFlow: description field    
      slots: Slot[]; // ← YFlow: slots map → Slot[]    
    }    
         
    // Source: packages/model/src/flow/nodes/agent/slot.interface.ts    
    interface Slot {    
      name: string; // ← YFlow: slot key (e.g., "account_type")    
      description: string; // ← YFlow: description field    
      type: 'string' | 'number' | 'boolean'; // ← YFlow: type field    
      required: boolean; // ← YFlow: optional (inverted)    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
main_agent: (key)	name	Node name
type: agent	type: NodeType.AGENT	Enum value
system:	systemPrompt	Multi-line string
single_turn:	singleTurn	Boolean flag
take_initiative:	takeInitiative	Boolean flag
iteration_limit:	iterationLimit	Optional number
memory_id:	memoryIdentifier	Optional conversation context ID
tools:	tools	Reference to tools node name
goals:	goals: AgentGoal[]	Map → array conversion
fallback:	Exit with label "fallback"	Required when iteration_limit set
error:	Exit with label "error"	Optional runtime error exit

Menu Node

Menu nodes are a specialized agent with DTMF (phone keypad) capabilities. They extend AgentNodeBase — same behavioral flags as Agent (iteration_limit, take_initiative):

nodes:    
      - main_menu:    
          type: menu    
         
          # System prompt (same as agent — inherited from AgentNodeBase)    
          system: |    
            You are collecting menu entries.    
            Present the options and wait for the user to press a key.    
         
          # Behavioral flags (same as agent — inherited from AgentNodeBase)    
          iteration_limit: 3    
          take_initiative: true    
         
          # Optional: memory identifier for conversation context    
          memory_id: main_menu    
         
          options:    
            '1':    
              name: sales    
              description: Press 1 for Sales    
              next: sales_agent    
         
            '2':    
              name: support    
              description: Press 2 for Support    
              next: support_agent    
         
            '0':    
              name: operator    
              description: Press 0 for a representative    
              next: transfer_agent    
         
          # Fallback when iteration_limit is exceeded (same as agent)    
          fallback:    
            next: menu_fallback    
         
      - menu_fallback:    
          type: say    
          message: Let me connect you with someone who can help.    
          next: transfer_agent    

Customer v2 Data Structure:

// Source: packages/model/src/flow/nodes/menu-node.interface.ts    
    interface MenuNode extends AgentNodeBase {    
      readonly type: NodeType.MENU; // ← YFlow: type: menu    
      options: MenuOption[]; // ← YFlow: options map → MenuOption[]    
    }    
         
    // AgentNodeBase provides: systemPrompt, iterationLimit, takeInitiative, memoryIdentifier    
         
    // Source: packages/model/src/flow/nodes/menu/menu-option.interface.ts    
    interface MenuOption {    
      key: string; // ← YFlow: option key (e.g., "1")    
      name: string; // ← YFlow: name field    
      description: string; // ← YFlow: description field    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
main_menu: (key)	nodeId (generated)	Node identifier
type: menu	type: NodeType.MENU	Direct mapping
system:	systemPrompt	Inherited from AgentNodeBase
iteration_limit:	iterationLimit	Inherited from AgentNodeBase
take_initiative:	takeInitiative	Inherited from AgentNodeBase
memory_id:	memoryIdentifier	Inherited from AgentNodeBase
options:	options: MenuOption[]	Map → array conversion
"1": (option key)	key: "1"	DTMF key (0-9, *, #)
name:	name	Option identifier
description:	description	Spoken option text (max 200 chars)
next: (in option)	Exit with label: "1"	Exit per option
fallback:	Exit with no label	Default exit

Simple Menu Example:

    nodes:    
      - quick_menu:    
          type: menu    
          system: Press 1 for yes, 2 for no    
          iteration_limit: 1    
          options:    
            '1':    
              name: yes    
              description: Confirm    
              next: confirm    
            '2':    
              name: no    
              description: Cancel    
              next: cancel    
          fallback:    
            next: operator    

API Node

API calls to external services:

    nodes:    
      - get_balance:    
          type: api    
         
          # Reference integration and method by human-readable name    
          integration: banking_api    
          method: get_account_balance    
         
          # Optional: resolved UUIDs (populated at save time, stripped on export)    
          integration_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'    
          method_id: 'f9e8d7c6-b5a4-3210-fedc-ba0987654321'    
         
          # Map slots to API parameters    
          params:    
            accountId: '{account_number}'    
            accountType: '{account_type}'    
         
          # Store result with prefix    
          result_prefix: balance    
         
          # Named exits    
          exits:    
            success:    
              next: process_result    
            failure:    
              next: api_error   

Customer v2 Data Structure:

    // Source: packages/model/src/flow/nodes/api-call-node.interface.ts    
    interface ApiCallNode extends Node {    
      readonly type: NodeType.API_CALL; // ← YFlow: type: api    
      apiName: string; // ← Display name (from integration label)    
      integrationConnectionId: string; // ← YFlow: integration (resolved to UUID)    
      methodName: string; // ← YFlow: method (display name)    
      methodDefinitionId: string; // ← YFlow: method (resolved to UUID)    
      variablePrefix: string; // ← YFlow: result_prefix    
      requestVariables?: Record<string, string>; // ← YFlow: params (converted)    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
get_balance: (key)	nodeId (generated)	Node identifier
type: api	type: NodeType.API_CALL	Note: api → apiCall
integration:	apiName	Human-readable name (always present)
integration_id:	integrationConnectionId	Optional UUID (resolved at save time)
method:	methodName	Human-readable name (always present)
method_id:	methodDefinitionId	Optional UUID (resolved at save time)
params:	requestVariables	{var} → bare name
result_prefix:	variablePrefix	Result variable prefix
exits:	exits[]	Named exits → Exit[]

Params Conversion:

    # YFlow params (with {variable} syntax)    
    params:    
      accountId: '{account_number}'    
      accountType: '{account_type}'    

//  Customer v2 requestVariables (bare variable names)    
    requestVariables: {    
      "accountId": "account_number",    
      "accountType": "account_type"    
    }    

Transfer Node

Transfer calls to human agents. Destination must use tel: or sip: prefix. A successful transfer hands the caller off — there is no return to the flow. Only the error exit returns to the flow.

nodes:    
      - transfer_to_sales:    
          type: transfer    
         
          destination: tel:[phone] # Required: tel: or sip: prefix    
          label: Sales Department    
         
          # Optional: pass context via UUI (SIP only)    
          context_variable: case_id    
         
          # Error route (required) - called when transfer fails    
          exits:    
            error:    
              next: transfer_failed    
         
      - transfer_failed:    
          type: say    
          message: I couldn't complete the transfer.    
          next: main_menu    

Destination Formats:

• tel:[phone] — E.164 telephone (recommended)

• tel:[phone] — With dashes

• sip:[email protected] — Named SIP endpoint

• sip:[email protected] — Internal PBX extension

Customer v2 Data Structure:

    // Source: packages/model/src/flow/nodes/transfer-node.interface.ts    
    interface TransferNode extends Node {    
      readonly type: NodeType.TRANSFER; // ← YFlow: type: transfer    
      destination: string; // ← YFlow: destination (tel:+1... or sip:...)    
      label?: string; // ← YFlow: label    
      integrationIdVariable?: string; // ← YFlow: context_variable    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
transfer_to_sales: (key)	nodeId (generated)	Node identifier
type: transfer	type: NodeType.TRANSFER	Direct mapping
destination:	destination	Must start with tel: or sip:
label:	label	Display name for transfer
context_variable:	integrationIdVariable	UUI context (SIP only)
exits:	exits[0] (label: "error")	Error-only exit (type: "handoff")

Validation Rules:

• destination is required and must start with tel: or sip:

• exits: { error: } is required — there is no success exit (successful transfers leave the flow)

• context_variable (UUI) only works with sip: destinations

Tools Node

Tools nodes bind MCP integration tools to an agent. They define which MCP methods are available for the agent to call.

    nodes:    
      # Agent that can call MCP tools    
      - retail_agent:    
          type: agent    
          system: |    
            You are a helpful retail assistant.    
            Use the sendProductLink tool to send product links via SMS.    
          tools: retail_tools # Agent has ACCESS to these tools    
          goals:    
            done:    
              next: farewell    
          fallback:    
            next: end    
         
      # Tools definition - referenced by agent's `tools:` property    
      - retail_tools:    
          type: tools    
          tools:    
            - connection: retail_mcp # Human-readable name (always present)    
              connection_id: 'a1b2c3d4-...' # Optional UUID (resolved at save, stripped on export)    
              tools:    
                - sendProductLink # Specific tools to expose    
                - checkInventory    
         
    integrations:    
      retail_mcp: # ID - immutable    
        label: 'Retail MCP Server' # Display name - can change    
        type: mcp    
        endpoint: https://api.example.com/mcp/sse    
        auth:    
          type: customheaders    
          custom_headers: '{"x-api-key":"your-api-key"}'    

Key Points:

• Agent nodes reference tools via tools: <tools_node_name>

• Tools nodes use type: tools and define available MCP connections

• connection: references an integration by human-readable name (always present)

• connection_id: is the optional resolved UUID (populated at save time, stripped on export)

• tools: lists specific MCP tools to expose to the agent (matched by name at runtime)

• Multiple MCP connections can be listed in the tools: array

Customer v2 Data Structure:

// Source: packages/model/src/flow/nodes/tools-node.interface.ts    
    interface ToolsNode extends Node {    
      readonly type: NodeType.TOOLS; // ← YFlow: type: tools    
      tools: MCPConnection[]; // ← YFlow: tools array    
    }    
         
    // Source: packages/model/src/flow/nodes/tools/mcp-connection.interface.ts    
    interface MCPConnection {    
      readonly type: ToolType.MCP;    
      connectionId: string; // ← YFlow: connection (resolved to UUID)    
      tools: MCPTool[]; // ← YFlow: tools list    
    }    
         
    // Source: packages/model/src/flow/nodes/tools/mcp-tool.interface.ts    
    interface MCPTool {    
      name: string; // ← YFlow: tool name in list    
    }    
         
    // Source: packages/model/src/flow/nodes/tools/tool-type.enum.ts    
    enum ToolType {    
      MCP = 'MCP',    
      INTERNAL = 'INTERNAL',    
    }    

Field Mapping:

YFlow	Customer v2 Field	Notes
retail_tools: (key)	nodeId (generated)	Node identifier
type: tools	type: NodeType.TOOLS	Direct mapping
tools:	tools: MCPConnection[]	Array of connections
connection:	(display name)	Human-readable name (always present)
connection_id:	connectionId	Optional UUID (resolved at save time)
tools: [sendProductLink]	tools: [{ name: "sendProductLink" }]	Tool names → MCPTool[]