Tutorial: Flow fundamentals

Flows enforce a specific sequence of steps – the step prompt stays anchored at the end of conversation history, preventing the model from improvising and keeping it focused on collecting, validating, and acting on information reliably.

Use flows when order matters: collecting a booking reference, verifying identity, routing based on input. Without flows, the LLM guesses the sequence, which leads to inconsistent outcomes.

For reference documentation on flows, see the Flows overview. This lesson focuses on how flows work and when to use them.

When to use flows vs other tools

If the interaction takes more than 2–3 turns and the steps must happen in a specific order, you probably need a flow.

How flows work

A flow is a sequence of steps. Each step contains:

• A prompt – instructions the model follows for this step
• Functions – scoped to this step only, used for transitions and actions
• A transition – how the flow moves to the next step (or exits)

The persistent prompt

The step prompt is always the last message in the conversation history. This is the most important thing to understand about flows.

Unlike content returned from a function (which appears at a specific point in history and becomes less relevant as more turns happen), the step prompt is re-injected on every turn. It cannot be “forgotten” by the model.

assistant: "Hi, how can I help?"
user: "I want to register"
function: "Ask the user for their phone number"    ← fades over time
assistant: "Sure, what's your phone number?"
user: "Actually, what are your opening hours?"
assistant: "We're open 9 to 5. Now, about that phone number..."  ← model may drift

This persistent control is why flows are more reliable than prompting alone for multi-turn interactions.

Check your understanding

Creating and entering a flow

There are two ways to create a flow:

1. Go to Flows and create one directly
2. Create one from any behavior menu (e.g., inside a managed topic action)

When you create a flow, Agent Studio generates:

• The flow itself (with a start step)
• A corresponding start function that contains conv.goto_flow("flow_name")

The start function is what triggers entry into the flow. You must expose it somewhere – in agent behavior, a knowledge topic, or another function. If a flow has no entry point, it exists but cannot be reached.

Step transitions

Each step shows only its own functions to the model. When the model calls a flow function, that function can:

• Save data (to conv.state)
• Call an API
• Move to the next step using flow.goto_step("step_name")
• Exit the flow using conv.exit_flow()

When transitioning between steps:

• The previous step prompt is removed
• The new step prompt is injected
• Only the new step’s functions are visible

This means the model cannot skip ahead, look at future steps, or call functions from a previous step.

def save_phone_number(conv, flow, phone_number: str) -> str:
    conv.state["phone_number"] = phone_number
    flow.goto_step("collect_name")
    return f"Phone number {phone_number} saved. Now ask for their full name."

Check your understanding

What happens without transitions

If you tell the model to ask for a phone number but don’t define what happens next, the model improvises. It may start asking for names, emails, or other details based on its training patterns.

This is not a model failure – it is a design failure. You did not give it the next step.

Transition pitfalls

Neither conv.goto_flow nor flow.goto_step interrupt the execution of your function. If you have multiple conditions, be careful not to overwrite one transition with another.

# If condition_1 and condition_2 are both True,
# we set step A, then overwrite with B, then C.
# Final transition is always C.
if condition_1:
    flow.goto_step("A")
if condition_2:
    flow.goto_step("B")
flow.goto_step("C")

Exiting a flow

When conv.exit_flow() is called:

• The step prompt disappears from conversation history
• The model returns to normal behavior (behavioral rules, knowledge, global functions)
• Any state saved during the flow persists in conv.state

Try it yourself

def save_phone_number(conv, flow, phone_number: str) -> str:
    conv.state["phone_number"] = phone_number
    flow.goto_step("collect_name")
    return "Phone number saved."

def save_name(conv, flow, full_name: str) -> str:
    conv.state["full_name"] = full_name
    conv.exit_flow()
    return f"Registration complete for {full_name}."

Check your understanding