Skip to main content
You can edit nodes in either the visual node editor or the JSON editor. To create a node in the visual editor, click Add Node in the lower-left corner. For how the global role instruction fits with each node’s task instruction, see Role and task instructions.

​
Name

Each node name must be unique within the scenario. The node name is used as the identifier for:
  • initial_node (the scenario start node)
  • any function transition_to targets
When you rename a node in the node editor, Akapulu Labs also updates:
  • initial_node if that node is currently the start node
  • any function transitions that point to that node
The first node you create becomes the start node by default. A scenario has one start node at a time. JSON 
{
  "initial_node": "Greeting",
  "nodes": {
    "Greeting": {
      ...
    },
    ...
  }
}
UI Edit the node title directly to rename it. To set any node as the start node (other than the first one created), click the 3 dots in the top-right of that node, then click Set as start node.

​
Global role instruction

Scenarios use one global role_instruction at the top level. Use role_instruction for long-lived identity, tone, boundaries, and behavior that should apply across the full conversation. JSON 
{
  "initial_node": "Greeting",
  "role_instruction": "You are a friendly Akapulu Labs onboarding assistant. Keep responses concise because they will be converted to audio.",
  "nodes": {
    "Greeting": {
      ...
    }
  }
}
UI In the scenario editor, click the hamburger icon on the left to open the left-hand nav menu. That panel includes a text area where you edit the global role instruction.

​
Task instruction

task_instruction defines what the assistant should do in the current node. Each node must include one non-empty task_instruction. Recommended pattern:
  • Put long-lived persona and behavior rules in the global role_instruction
  • Use task_instruction in each node for node-specific goals and instructions
JSON 
{
  "role_instruction": "You are a friendly Akapulu Labs onboarding assistant. Keep responses concise because they will be converted to audio.",
  "nodes": {
    "Greeting": {
      "task_instruction": "Greet the user and gather what they want to build.",
      ...
    },
    "Planning": {
      "task_instruction": "Help the user plan their project based on gathered requirements.",
      ...
    }
  }
}
UI The task instruction is the text input on the node labeled Task Instruction.

​
Runtime variables in instructions

You can embed {{runtime.*}} placeholders in the global role_instruction and in any node’s task_instruction. Akapulu Labs substitutes them from the runtime_vars your server sends on connect, so the model sees session-specific text without you duplicating scenarios per customer.
secret and llm template variables are not supported in role_instruction or task_instruction. Use {{runtime.*}} for per-session variables; keep sensitive variables in endpoint headers with {{secret.*}}, and use {{llm.*}} only in HTTP endpoint templates. See Templates and Variables.
Example 
{
  "role_instruction": "You are a support agent for {{runtime.company_name}}. The caller’s account id is {{runtime.user_id}}.",
  "nodes": {
    "Ticket triage": {
      "task_instruction": "Greet {{runtime.display_name}} and ask which product line they need help with before looking anything up.",
      ...
    }
  }
}
Your connect request should include matching keys in runtime_vars, for example company_name, user_id, and display_name.
Web SDK: If using the Akapulu Labs Web SDK, in your connect route, call akapulu.connectConversation from @akapulu/server with a runtime_vars object whose keys match your {{runtime.*}} placeholders. See Customize Conversation UI for a complete server-side example.

​
Functions

Functions are tool calls available to the assistant while the node is active. Allowed function types:
  • transition
  • http
  • rag
  • vision
Function rules:
  • function name is required and must be unique within the node
  • function name can only use letters, numbers, underscores, and hyphens
  • function description is required
Type-specific requirements:
  • transition requires transition_to
  • http requires endpoint_id
  • rag requires knowledge_base_id
  • vision has no additional required ID field
Function description guidance:
  • this is the instruction shown to the model for when and why to call the tool
  • be explicit about the trigger, expected use, and what the tool does
JSON 
{
  "nodes": {
    "Greeting": {
      "functions": [
        {
          "name": "transition_to_planning_phase",
          "description": "Once project scope is clear, move to planning phase.",
          "type": "transition",
          "transition_to": "Planning Phase"
        },
        {
          "name": "Akapulu_RAG",
          "description": "Access information on the Akapulu Labs platform.",
          "type": "rag",
          "knowledge_base_id": "<KNOWLEDGE_BASE_ID>"
        }
      ],
      ...
    },
    "Planning Phase": {
      "task_instruction": "Help the user plan their project on Akapulu Labs.",
      "functions": [
        {
          "name": "create_project_brief",
          "description": "Create a project brief in your external planning system.",
          "type": "http",
          "endpoint_id": "<HTTP_ENDPOINT_ID>"
        },
        {
          "name": "inspect_user_whiteboard",
          "description": "Analyze a camera frame when the user shares a whiteboard or sketch.",
          "type": "vision"
        }
      ],
      ...
    },
    ...
  }
}
UI Click Add function on the node to open the function modal, then choose the function type: In the modal:
  • enter a function name
  • enter a function description
  • select type-specific targets from the dropdowns (saved HTTP endpoint for http, knowledge base for rag)
To set transition_to in the UI for any function, drag the probe on the right side of the function to the desired node.

​
Require function call

require_function_call makes the assistant call at least one function on the next model turn in this node instead of answering with only plain text.
Constraint: When require_function_call is true, the node must define at least one function in functions.
JSON 
{
  "nodes": {
    "Booking": {
      "task_instruction": "The user already gave date, time, and visit type in intake. Call scheduling to create the appointment from that information, then confirm out loud.",
      "require_function_call": true,
      "functions": [
        {
          "name": "create_appointment",
          "description": "Create the appointment using the date, time, and visit type the user provided earlier.",
          "type": "http",
          "endpoint_id": "<HTTP_ENDPOINT_ID>",
          "transition_to": "Confirmation"
        }
      ]
    }
  }
}
UI Open Advanced Settings on the node, then set Force Function Call to yes. While this is on, the function section on the node shows a Call required indicator.
Loop protection: If require_function_call is enabled and the assistant gets stuck repeatedly calling tools without replying in text, Akapulu Labs automatically relaxes the forced-call requirement after 5 consecutive tool-only turns for that session/node. After that, the assistant can either call a tool or reply in plain text to prevent infinite loops.

​
Respond immediately

respond_immediately controls whether the assistant speaks immediately after entering the node.
  • true (default): the assistant responds right away
  • false: the assistant waits for user input before responding
JSON 
{
  "nodes": {
    "Greeting": {
      "respond_immediately": false,
      ...
    },
    ...
  }
}
UI Open the Advanced Settings dropdown, then toggle Respond Immediately on or off.

​
End after bot response

end_after_bot_response controls whether the conversation ends after the bot finishes its first utterance in that node. Use this for terminal nodes like wrap-up, goodbye, or confirmation nodes where the assistant should speak once and then end the conversation. When end_after_bot_response is true, interruptions are disabled for that node so the bot can finish its closing response before the conversation ends. JSON 
{
  "nodes": {
    "End": {
      "task_instruction": "Thank the user, summarize next steps briefly, and end the conversation.",
      "end_after_bot_response": true
    }
  }
}