New to building conversational flows? Check out our Pipecat Flows guide first.

​
Installation

Pipecat Flows requires an additional dependency:

pip install "pipecat-ai[flows]"

​
FlowManager

Main class for managing conversation flows.

​
Constructor Parameters

flow_config
dict
required

Complete flow configuration including initial_node and nodes

task
PipelineTask
required

Pipeline task for frame queueing

tts_service
TTSService

Optional TTS service for immediate speech actions

​
Configuration Structure

flow_config
Object

​
Example flow_config

Here’s a minimal example demonstrating the flow_config structure:

flow_config = {
    "initial_node": "start",
    "nodes": {
        "start": {
            "messages": [
                {
                    "role": "system",
                    "content": "Ask if user wants option A or B"
                }
            ],
            "functions": [
                {
                    "type": "function",
                    "function": {
                        "name": "choose_a",  # Transitions to choose_a node
                        "description": "User chooses option A",
                        "parameters": {"type": "object", "properties": {}}
                    }
                }
            ]
        },
        "choose_a": {
            "messages": [
                {
                    "role": "system",
                    "content": "Handle option A selection"
                }
            ],
            "functions": [
                {
                    "type": "function",
                    "function": {
                        "name": "select_value",  # Terminal function (stays in node)
                        "description": "Select a value",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "value": {"type": "string"}
                            }
                        }
                    }
                }
            ],
            "pre_actions": [
                {
                    "type": "tts_say",
                    "text": "Processing option A..."
                }
            ],
            "post_actions": [
                {
                    "type": "end_conversation",
                    "text": "All done!"
                }
            ]
        }
    }
}

See the Pipecat Flows guide for a more complete example.

​
Methods

initialize
async method

Initialize the flow with starting messages

Parameters:

  • initial_messages: List[dict] - Initial context messages
register_functions
async method

Register flow functions with LLM service

Parameters:

  • llm_service: LLMService - Service to register functions with
register_action
method

Register custom action handler

Parameters:

  • action_type: str - Action identifier
  • handler: Callable - Action handler function

​
Built-in Actions

tts_say
action

Speaks text immediately using TTS service

end_conversation
action

Ends the conversation and closes the connection

​
Example Usage

# Pre-action with immediate TTS
"pre_actions": [
    {
        "type": "tts_say",
        "text": "Processing your request..."
    }
]

# Post-action to end conversation
"post_actions": [
    {
        "type": "end_conversation",
        "text": "Thank you for using our service. Goodbye!"
    }
]

​
Function Types

​
Terminal Functions

Execute without changing nodes. Used for refinement within a state.

​
Transitional Functions

Execute and change to new node. Used for major state changes.

SoundfileMixerBase Frame Types