Skip to main content

Flows choreograph multi-step processes. At any given moment, the model only sees the current step’s prompt and tools.

A good flow keeps each step focused on a single task. Use Python for branching, validation, and routing logic, and use prompts for conversational behavior.

​
What flows are for

Flows are best used when the agent needs to move through a structured process such as:
  • collecting information in a defined order
  • confirming details before taking action
  • calling APIs or deterministic logic at specific points
  • handling success, failure, and retry paths explicitly

Default steps

LLM-driven steps for collecting information and transitioning based on conditions.

Advanced steps

Steps with more control over ASR, DTMF, and callable transition functions.

Function steps

Deterministic Python steps for routing, validation, and API calls.

​
Entering a flow

A flow can be entered in several ways.

​
From code

conv.goto_flow("Flow Name")
This enters the flow at its configured start step.

​
Via a returned transition

return {"transition": {"goto_flow": "Flow Name", "goto_step": "Step Name"}}

​
Within a flow

flow.goto_step("Step Name")
This is only available inside flow functions.

​
File structure

Flows live under the flows/ directory. 
flows/
└── {flow_name}/
    ├── flow_config.yaml
    ├── steps/
    │   └── {step_name}.yaml
    ├── function_steps/
    │   └── {function_step}.py
    └── functions/
        └── {function_name}.py
The flow directory name is derived from the flow’s name field, converted to lowercase snake_case. A flow named Booking Flow must live in flows/booking_flow/. If the directory name does not match, the ADK will not recognize the flow.

​
Flow configuration

Each flow includes a flow_config.yaml file that defines the flow itself.

​
Fields

FieldRequiredDescription
nameNoHuman-readable flow name
descriptionYesWhat the flow does
start_stepYesThe step to enter when the flow starts

​
Example

name: Example Flow
description: Handles the booking process
start_step: Collect Details

​
Step types

A step represents the agent’s current position in the flow. There are three step types:
  1. default steps
  2. advanced steps
  3. function steps

​
Default steps

Default steps live in steps/*.yaml. These steps use LLM logic to process information and transition based on configured conditions. They cannot call transition functions from their prompt. ASR biasing is automatically configured based on the entities requested in the step.

​
Fields

FieldDescription
step_typeMust be default_step
nameHuman-readable step name
conditionsConditions that control transitions
extracted_entitiesEntities to collect in the step
promptPrompt shown to the model

​
Prompt behavior

Default step prompts may use entity references such as: 
{{entity:entity_name}}
They should not contain function calls.

​
Conditions

Conditions define how the agent transitions out of a default step. A condition can:
  • go to another step
  • exit the flow

​
Condition fields

FieldDescription
condition_typestep_condition or exit_flow_condition
descriptionWhen this condition applies
child_stepNext step, only for step_condition
required_entitiesEntities that must be collected before the condition can trigger

​
child_step rules

Use the correct step identifier depending on target type:
  • Default step or advanced step: use the step’s name
  • Function step: use the Python filename without .py

​
Advanced steps

Advanced steps also live in steps/*.yaml. These steps support additional controls such as:
  • custom ASR tuning
  • DTMF collection rules
  • transition function calls from the prompt

​
Fields

FieldDescription
step_typeMust be advanced_step
nameHuman-readable step name
asr_biasingASR tuning for the turn
dtmf_configDTMF collection settings
promptPrompt shown to the model

​
ASR biasing

Advanced steps can tune ASR toward specific kinds of user input. Supported ASR biasing fields include:
  • alphanumeric
  • name_spelling
  • numeric
  • party_size
  • precise_date
  • relative_date
  • single_number
  • time
  • yes_no
  • address
  • custom_keywords

​
DTMF configuration

Advanced steps can also define DTMF behavior, including:
  • inter_digit_timeout
  • max_digits
  • end_key
  • collect_while_agent_speaking
  • is_pii

​
Step prompt design

Prompts should be used for:
  • collecting input
  • presenting information
  • shaping the conversational turn
Python should be used for:
  • comparisons
  • conditionals
  • routing
  • state-driven decisions
Do not put deterministic branching logic into promptsDo not encode logic like “If $x == 0 do A, else do B” in prompts. Put that logic in Python and transition to the correct step explicitly.

​
Prompt tips

  • use markdown headers to structure instructions
  • keep one clear purpose per step
  • include validation and edge cases where needed
  • use voice-friendly phrasing for spoken interactions
  • make transitions explicit

​
Function steps

Function steps live in function_steps/*.py. These are deterministic Python steps. They execute directly, with no model interpretation. Use them for:
  • API calls
  • validation
  • state updates
  • explicit routing

​
Signature

def function_name(conv: Conversation, flow: Flow):

​
Important rules

Function steps:
  • cannot define extra parameters
  • cannot use @func_description
  • must control flow explicitly
A function step must call either:
  • flow.goto_step(...)
  • conv.exit_flow()
and may also return a context string for the model.

​
Common uses

Validation

Check whether collected input is valid before the flow continues.

Routing

Move to the correct step based on deterministic logic.

External calls

Call APIs and store the results in state.

Error handling

Send the flow to an error step with a useful context string.

​
Transition functions

Transition functions live in functions/*.py inside a flow. They can be called from advanced-step prompts and are referenced using: 
{{ft:flow_function}}
Unlike function steps, transition functions:
  • may define custom parameters
  • may have a description shown to the model
  • can be called by the model within the same flow
Logic reused across flows is usually better placed in global functions.

​
Best practices

  • keep one clear purpose per step
  • start with a simple linear path, then add branching
  • use confirmation steps before function steps that change state
  • add explicit error and failure paths
  • use meaningful step names
  • test the full path from entry to exit
Prefer simple flows firstA clean A → B → C path is easier to reason about and test than a highly branched flow built too early.

​
Common mistakes

  • leaving a flow function without advancing the flow
  • encoding branching logic in prompts
  • using internal IDs instead of resource names
  • putting too much deterministic logic into LLM-driven steps
  • mixing conv.exit_flow() with additional navigation
  • using end_turn=False when the user is actually expected to reply

​
Design principles

  1. start with a single path
  2. add branching only where needed
  3. use function steps for deterministic logic
  4. use prompts for conversational behavior
  5. make every transition explicit

Functions

Learn how global functions, transition functions, and function steps differ.

Topics

See how topics trigger flow entry via conv.goto_flow in their actions.

Entities

See how structured data collection fits into flow steps and conditions.

Return values reference (platform)

All supported function return shapes used in flow transitions — utterance, hangup, goto_flow, and combined dicts.

Conversation object reference (platform)

Full reference for conv.goto_flow, conv.exit_flow, flow.goto_step, and all other flow navigation methods.
Last modified on July 9, 2026