Most flow problems are one of: a transition that fires too early or never, a node that does not leave, a function that does not run or returns something unexpected, or wording that drifts. This page lists the tools Tried gives you to see what happened, then the common causes.
Tools for looking inside a flow#
Test LLM#
Click Test in the builder header, then Test LLM. Chat by text with the draft flow: no audio and no per-minute cost.
- Each node change shows as "Node transition →
<node id>". - Each function call shows as Tool Invocation with its arguments. Click it to expand.
- Reaching an end node shows "The flow reached an end node".
- Hover a caller turn for Edit (change it and rerun from there) and Delete.
- Hover an agent turn for Rerun and Debug. Debug regenerates that turn 10 times and lists the variants ("10 variants, 3 distinct"); Use keeps one. Different variants mean the turn is unstable: tighten the instruction or the transition conditions.
- Replay runs your caller lines again against the current flow. Reset clears the chat.
Test LLM (and Simulate, below) run on a text playground in the API, not on the voice worker's flow engine. The playground offers the current node's prompt transitions and, in a function node, that node's function. It does not evaluate equation transitions, global nodes or else edges, and it does not call your endpoints. A tool only returns a result there when you give it a mock. Use Test Audio or a real call to check equations, global nodes and live functions.
Mocks#
The wrench tab (Tool mocks) holds canned outputs: "When the agent calls one of these tools during a test chat, it gets this output instead of calling your endpoint." Add the tool name and the output (usually JSON). Mocked results are marked Mocked in the chat. Mocks are stored per agent in your browser and also apply to Simulate.
Simulate#
The robot tab (Simulated user) runs an AI caller against your flow on the same playground as Test LLM. Write the persona ("You are Sam, a busy customer who wants to book an appointment next Tuesday afternoon...") and Turns at most (1 to 20), then click Simulate. Both sides stream into the log with tool calls and node transitions. The run stops when the caller says goodbye, the agent ends the call, or a limit is reached, and the reason is shown.
Dynamic variables#
The { } button sets the variables used in test chats and test calls. Set the values a real call would carry (for example first_name, plan) to test equation branches.
Test Audio#
Test Audio places a web call to the draft agent through the full voice pipeline, including the real flow engine, functions, global nodes and equations. Transfers and SMS do not work in web calls, so they take their failure edges.
Testing one component#
Test subflow in the component editor runs the chat from the component's Begin node to its Exit. See Components.
After a real call#
The call object's transcript_with_tool_calls contains, in order, each utterance, each tool_call_invocation and tool_call_result, each node_transition (with former_node_id, new_node_id and transition_type), collected variables, SMS sent and injected context. collected_dynamic_variables shows the final values your equations saw.
Common problems#
The flow never leaves a node#
- No transition matches. Prompt transitions are judged by the LLM. Rewrite the condition as a fact about the conversation ("The caller has given a date and a time") and check it with Debug.
- The edge is not connected. On the card, a transition without "→ node" has no destination and is ignored.
- An equation never holds. Check the variable name and value in { } or in
collected_dynamic_variables. Remember: a missing variable makes every comparison false except!=andnot_contains. - An automatic node has no matching edge. Function, code, MCP and extract nodes stay put if no transition matches. Add an else edge where the type allows it, or cover all outcomes with equations.
The flow leaves too early#
- A broad global node condition is firing. Narrow it or add a Cool down (user turns).
- An Always edge fires after any caller reply, before anything else.
- A Skip response edge leaves as soon as the agent finishes speaking.
- Two prompt conditions overlap. Make them mutually exclusive.
A function did not run#
- In a conversation node, flow functions are not available. Use a function node or tick the function in a subagent node.
- In a function node, check that the selected function still exists (a deleted function is skipped).
- Custom function errors are returned to the LLM as text starting with
Error. Look at the Tool Invocation result, ortool_call_resultin the transcript. A blocked private URL returns "the function URL is not allowed".
Wrong path after a function#
- Wait for result is off, so the response variables were not saved when the transitions ran.
- The response was not JSON, or the JSON path does not exist, so the variable was never set.
The agent repeats itself or rambles#
- A Static Sentence is spoken on every entry into the node. A loop back into the node repeats it.
- Long global prompts and long example replies compete with the node instruction. Move step-specific rules into nodes.
A loop#
The engine follows at most 25 automatic transitions in one turn, then stays where it is and logs an error. If a call stops responding after a chain of automatic nodes, look for a cycle without a conversation node.