Flow object

The Flow object gives you control over how the agent moves between steps in a flow. It is available as a parameter in any flow-scoped function (transition function).

The two companion methods on the Conversation object – conv.goto_flow() and conv.exit_flow() – handle transitions between flows and are documented at the bottom of this page.

goto_step(step_name, condition_label)

Moves the agent to another step in the current flow. This replaces the current step’s prompt and functions with those of the target step.

goto_step(step_name: str, condition_label: str = None) -> None

# Basic transition
flow.goto_step("Confirm Name")
return
# With a condition label (decorative only)
flow.goto_step("Group Booking", "large party")
return

If step_name doesn’t match any step in the flow, the transition fails silently. Step names are case-sensitive. See transition functions – debugging for troubleshooting guidance.

Execution context matters

flow.goto_step() behaves differently depending on where it’s called:

• In a transition function (LLM step) – the LLM decides whether to call the function based on the step prompt and user input. The transition only happens if the LLM invokes the function.
• In a Function step – the code runs directly without LLM involvement. The transition is deterministic. Here, the condition_label parameter controls which edge is highlighted in the visual editor.

Conditional transition

if conv.state.has_phone_number:
    flow.goto_step("Confirm phone number")
    return
flow.goto_step("Collect phone number")
return

Input validation and state update

def save_user_name(conv: Conversation, flow: Flow, first_name: str, last_name: str):
    if not first_name or not last_name:
        return "Please make sure we have both first and last name before continuing."
    conv.state.first_name = first_name
    conv.state.last_name = last_name
    flow.goto_step("Confirm Name")
    return

This is the recommended structure: validate input, update state, transition, then return.

current_step

Type: str Returns: The name of the current step the agent is in.

if flow.current_step == "Collect Name":
    return "You're in the name collection step."

Useful for debugging or conditional routing when a single function serves multiple steps.

Companion methods on the Conversation object

These methods live on the Conversation object, not on Flow, but are commonly used alongside flow.goto_step() in transition logic.

conv.goto_flow(flow_name)

Transitions to a different flow at the end of the current turn. Can be called from any function – flow-scoped or global.

conv.goto_flow("Identity Verification")
return

See triggering flows for all the ways to start a flow.

conv.exit_flow()

Exits the current flow and returns the agent to its default (non-flow) behavior. Exit steps are visually marked in yellow in the Flow Editor.

def complete_booking(conv: Conversation, flow: Flow):
    conv.state.booking_confirmed = True
    conv.exit_flow()
    return

Next steps