Runtime Guide

The runtime guide explains how a visual AI Workflow becomes a graph of nodes and edges that executes, waits, resumes, logs, and surfaces debugging information in Interactions.

Key concepts

Term	Definition
Graph	The runtime representation of a workflow version.
Node	A workflow stencil such as Start, AI Agent, Tool, Function, Wait, If/else, Transfer, or End.
Edge	A connection from one node output port to another node input port.
Port	A named input or output on a node. Dynamic ports can represent exit conditions or branches.
Execution log	Runtime evidence showing which nodes ran and where the flow paused or failed.

What you can do

Action	Description
Understand graph shape	Read how nodes and edges map to builder stencils.
Debug wait and resume	Follow an execution that pauses and later receives an event.
Interpret failures	Identify whether a failure came from configuration, a tool, runtime code, or an external provider.
Connect UI and API behavior	Use Interactions, workflow versions, and developer APIs together.

Graph structure

A workflow version executes as nodes connected by edges.

{
  "nodes": [
    {
      "id": "start",
      "type": "flow-engine-start",
      "label": "Start",
      "config": {}
    },
    { "id": "agent", "type": "ai-agent", "label": "AI Agent", "config": {} }
  ],
  "edges": [
    {
      "id": "edge-1",
      "source": { "nodeId": "start", "portId": "out" },
      "target": { "nodeId": "agent", "portId": "in" }
    }
  ]
}

Builder to runtime map

Builder concept	Runtime concept
Start node	Initial node that receives the first event.
AI Agent stencil	LLM step that can respond, call tools, use variables, and choose exit paths.
Tool stencil	Runtime call to a configured Tool.
Function stencil	JavaScript execution step.
Wait stencil	Pause point that expects a later resume event.
If/else stencil	Condition node with branch output ports.
Transfer stencil	Handoff to a configured Contact or voice transfer target.
End stencil	Terminal node for the execution.

Execution lifecycle

1. An entry point, test panel, or API request starts an execution with payload and context.
2. The runtime loads the workflow graph and starts at the Start node.
3. Each node receives context, updates state, and selects the next output port.
4. Tool and Function nodes can call external systems or custom JavaScript.
5. Wait nodes pause execution until a resume event arrives.
6. End nodes finalize the flow; interaction APIs can then finalize the conversation record.
7. Logs and transcript details appear in Interactions when the execution is tied to an interaction.

Failure modes

Failure	What it usually means	Where to look
Missing next node	A port is not connected or a branch was not handled.	Workflow Builder canvas.
Tool failure	External API, credentials, template variables, timeout, or response parsing failed.	Tool test modal and interaction tool-call details.
Function failure	Script threw an error or returned an unexpected shape.	Function stencil configuration and runtime logs.
Wait never resumes	The expected user or integration event did not arrive.	Entry point, resume API call, interaction transcript.
Voice failure	Telephony provider, phone number, or recording setup failed.	Phone Numbers, Entry Points, voice interaction details.

Debug from Interactions

1. Open the interaction created by the entry point, test panel, or API flow.
2. Confirm the workflow version and channel.
3. Read the transcript from oldest to newest.
4. Expand tool calls and metadata sections.
5. Open the workflow version and compare the highlighted execution path with the current graph.
6. If a published workflow must change, create a new draft, fix it, and publish a new version.

FAQ

Do edits to a draft change in-progress executions? No. In-progress executions stay tied to the workflow version they started with.

Why does an AI Agent have multiple output ports? Exit conditions and branch-like behavior can create dynamic ports, allowing the agent to choose a path based on the conversation and configuration.

Related pages

• AI Workflows - build and publish graph versions
• AI Workflow Execution - start and resume executions by API
• Interactions - inspect transcripts and execution path