Pipecat Flows

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 is part of Pipecat, in the pipecat.flows module. 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

​

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.

​

Two Ways to Write a Flow

A flow can be written as data, a declarative flow config loaded at runtime, or as Python code, a programmatic flow. 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.

​

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. The guides that follow show both forms side by side.

​

Choosing

Start declarative with a flow config. Move the flow into Python only when one of these is true:

• A tool needs a strict parameter schema. A direct function’s parameters come from its signature and docstring. If a parameter needs an enum, a numeric range, or another JSON Schema constraint, define the tool with FlowsFunctionSchema.
• A node has to be built at runtime. A config’s prompts can read state, but its nodes are fixed. If which tools a node offers, or where it can go next, depends on what has happened in the conversation, build that node in code.
• Something outside the conversation drives the flow. A transport event that moves the caller to a new node, a transfer that runs a second pipeline, another worker taking over. Those happen in code, so the flow lives there too.

​

Visual Flow Editor

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

​

Ready to Build?