Skip to main content
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
ParameterTypeRequiredDescription
step_namestrYesThe exact name of the target step as it appears in the Flow Editor. Case-sensitive.
condition_labelstrNoA 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 behaviour.
  • step_name (required) — the name of the target step, exactly as it appears in the Flow Editor.
  • condition_name (optional) — a label for the transition edge. In Function steps, this label appears on the edge in the visual editor for readability.
# 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 honouring 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.
Silent failure on invalid step namesIf step_name doesn’t match any step in the flow — due to a typo, trailing space, or case mismatch — the transition fails silently. There is no error message.To debug:
  • Open the Flow Functions modal and verify the exact step name.
  • Use flow.current_step to log which step the agent is currently in.
  • Remember that step names are case-sensitive: "CollectName" and "collectname" are different targets.
When you rename a step in the Flow Editor, Agent Studio automatically updates flow.goto_step() references across the project. However, verify after renaming — auto-rename may not catch step names stored in variables or constructed dynamically.

​
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. In this context, 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. Use this when the conversation needs to leave the current flow entirely — for example, to start an identity verification or escalation flow. 
conv.goto_flow("Identity Verification")
return
Unlike flow.goto_step(), conv.goto_flow() can be called from any function — flow-scoped or global. 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) behaviour. 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.
  • Transition functions — naming conventions, common mistakes, and best practices for flow routing logic
  • Conversation object — full reference for conv.goto_flow(), conv.exit_flow(), and other methods
  • No-code flows — Default steps vs Function steps, and how goto_step() behaves in each
  • Triggering flows — all the ways to start a flow with conv.goto_flow()
Last modified on March 20, 2026