> ## Documentation Index > Fetch the complete documentation index at: https://docs.poly.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](/tools/classes/conv-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. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. | ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} # 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](/flows/transition-functions#debugging-tips) 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](/flows/no-code/introduction)** – 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 ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/tools/classes/conv-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. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} conv.goto_flow("Identity Verification") return ``` See [triggering flows](/flows/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. ```python theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/flows/introduction) for more on flow design. ## Next steps Naming conventions, common mistakes, and best practices for flow routing logic. Full reference for conv.goto\_flow() and conv.exit\_flow(). All the ways to start a flow with conv.goto\_flow().