Pipecat Flows

Structure a conversation as a graph of nodes with Pipecat Flows: declarative flow configs, programmatic nodes, and transitions.

Pipecat Flows structures a conversation as a flow: a graph of nodes, where each node focuses the LLM on a single task with only the tools it needs.

Flows ships as the pipecat.flows module, so the classes you write against are FlowConfig, Flow, FlowManager, NodeConfig, and FlowsFunctionSchema.

This approach solves a common problem: monolithic prompts with many tools lead to hallucinations and lower accuracy. Pipecat Flows breaks complex tasks into focused steps with clear, specific instructions.

When to Use Flows

A flow is best suited for use cases where:

• You need precise control over how a conversation progresses through specific steps
• Your bot handles complex tasks that can be broken down into smaller, manageable pieces
• You want to improve LLM accuracy by focusing the model on one specific task at a time instead of managing multiple responsibilities simultaneously

How Pipecat Flows Builds on the Pipeline

A Pipecat pipeline provides your bot’s core mechanics — receiving audio, transcribing input, running LLM completions, converting responses to audio, and sending audio back to the user.

Pipecat Flows builds on that pipeline to structure the conversation, managing context and tools as it moves from one state to the next. This keeps your conversation logic cleanly separated from the pipeline mechanics.

Pipecat Flows needs a text LLM that supports function calling — use a cascaded STT → LLM → TTS pipeline (OpenAI, Anthropic, Google Gemini, AWS Bedrock, or any OpenAI-compatible service).

Speech-to-speech (realtime) models aren’t supported — Gemini Live, OpenAI Realtime, Ultravox, and AWS Nova Sonic. Flows moves between nodes by rewriting the LLM’s context and tools mid-session, and these realtime APIs don’t yet expose the controls to do that (a known limitation, tracked upstream). To get a graph-of-nodes structure with a realtime model today, build it yourself with function calling instead. See the supported providers table.

Two Ways to Write a Flow

A flow can be declarative — the graph is data — or programmatic — the graph is code. Both are fully supported, and a node means the same thing in each.

Declarative

A declarative flow separates business logic from code. The graph, the prompts, which tools each node offers, and where each tool leads live in a flow config: a YAML or JSON document loaded at runtime. The handlers — the Python that does work when a tool is called — ship with the bot.

Because the flow is data, one deployed bot can run whichever flow a session calls for, loaded from a file, a database, or a CMS. Someone who is not an engineer can change what the bot says or where a step leads without a deploy.

Lives in the flow config	Lives in Python
The nodes and the initial node	The tools a node offers, as functions
Each node’s role and task messages	What each tool does when it is called
Which tools each node offers	Action handlers
Where each tool leads	The pipeline and the FlowManager
Pre- and post-actions
Transition-only functions, entirely

Programmatic

A programmatic flow builds NodeConfig objects in Python. Functions do their work and return the next node directly, so the graph exists only as the code that constructs it.

Choosing

Start declarative. Write the flow in code when it needs code:

• Schema control. A direct function’s parameters come from its signature and docstring. When a tool needs an enum, a numeric range, or another JSON Schema constraint, define it with FlowsFunctionSchema.
• Structure from runtime data. A prompt can read state, but a node whose shape depends on the conversation — offering different tools, or routing somewhere the graph doesn’t name — has to be built in code.
• A flow driven from outside the conversation. Nodes set from transport events, a parallel pipeline playing hold music, another worker handing off over the bus.
• The flow is incidental. When the code is about a pipeline feature, the flow stays in Python beside it.

Installation

Pipecat Flows is included with Pipecat. Install Pipecat with the dependencies for your transport, STT, LLM, and TTS providers:

uv add "pipecat-ai[daily,openai,deepgram,cartesia,silero]"

Visual Flow Editor

The Pipecat Flows Visual Editor lets you design conversation flows visually.

Ready to Build?

Quickstart

Build your first conversation flow in minutes

Flow Configs

Write a flow as data and load it at runtime

Examples

Explore real-world examples and use cases

API Reference

Complete reference docs and technical details