Flow object

The Flow object controls step transitions and exposes the current step name in a flow.

This page requires Python familiarity. It is a reference for developers writing transition functions inside flows.

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

Parameter	Type	Required	Description
step_name	str	Yes	The exact name of the target step as it appears in the Flow Editor. Case-sensitive.
condition_label	str	No	A label for the transition edge. This is purely decorative – it appears on the edge in the Flow Editor for readability but does not affect runtime behavior.

# Basic transition
flow.goto_step("Confirm Name")
return

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

Always call return immediately after goto_step().

The runtime executes your function to completion before honoring the transition. If you call goto_step() more than once without returning, each call overwrites the previous transition state – only the final one takes effect. Using return after each call prevents accidental overwrites and makes control flow explicit.

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

Every flow should have at least one exit path. Un-exited flows can cause the agent to hallucinate or loop. See the flows overview for more on flow design.

Next steps

Transition functions

Naming conventions, common mistakes, and best practices for flow routing logic.

Conversation object

Full reference for conv.goto_flow() and conv.exit_flow().

Triggering flows

All the ways to start a flow with conv.goto_flow().