New to building conversational flows? Check out our Pipecat Flows guide first.
Pipecat Flows is an add-on framework for Pipecat that allows you to build structured conversations in your AI applications. It enables you to define conversation paths while handling the complexities of state management and LLM interactions.

API Reference

Complete API documentation and method details

GitHub Repository

Source code, examples, and issue tracking

Hello World Example

Working example with basic conversation flow

​
Installation

​
Pipecat Flows

To use Pipecat Flows, install the required dependency: 
pip install pipecat-ai-flows

​
Pipecat Dependencies

For fresh installations, you’ll need to install Pipecat with depdencies for your Transport, STT, LLM, and TTS providers. For example, to use Daily, OpenAI, Deepgram, Cartesia, and Silero: 
pip install "pipecat-ai[daily,openai,deepgram,cartesia,silero]"

​
Flow Types

Create conversation paths at runtime based on user input, external data, or business logic. Enables more flexible and adaptive interactions. Additionally, can handle simple scenarios with predefined paths.
Dynamic Flows are the recommended approach for most applications, as they allow for greater flexibility and adaptability in conversation design.

​
Static Flows

Use predefined conversation paths configured upfront. Ideal for predefined interactions where the graph navigation can be predetermined.

​
Key Components

​
Core Classes

  • FlowManager - Main orchestration class for managing conversation flows
  • FlowsFunctionSchema - Standardized function call schema that works with any LLM provider

​
Type Definitions

  • FlowArgs - Function handler arguments
  • FlowResult - Function return type with status and optional data
  • NodeConfig - Complete node configuration including messages, functions, and actions
  • FlowConfig - Static flow configuration with nodes and initial state

​
Context Management

  • ContextStrategyConfig - Configuration for context management during transitions
  • ContextStrategy - Enum for APPEND, RESET, and RESET_WITH_SUMMARY strategies

​
Actions

  • ActionConfig - Configuration for custom pre- and post-actions during conversation flow

​
Function Types

​
Node Functions

Execute operations within a single conversation state without switching nodes. Return (FlowResult, None).

​
Edge Functions

Create transitions between conversation states, optionally processing data first. Return (FlowResult, NodeConfig) or (FlowResult, str).

​
Direct Functions

Functions passed directly to NodeConfig with automatic metadata extraction from signatures and docstrings.

​
LLM Provider Support

Pipecat Flows automatically handles format differences between providers:
ProviderFormat SupportInstallation
OpenAIFunction callingpip install "pipecat-ai[openai]"
AnthropicNative toolspip install "pipecat-ai[anthropic]"
Google GeminiFunction declarationspip install "pipecat-ai[google]"
AWS BedrockAnthropic-compatiblepip install "pipecat-ai[aws]"

​
Error Handling

Comprehensive exception hierarchy for flow management:
  • FlowError - Base exception for all flow-related errors
  • FlowInitializationError - Flow manager setup failures
  • FlowTransitionError - Node transition failures
  • InvalidFunctionError - Function registration or execution errors
  • ActionError - Action execution failures

​
Additional Notes

  • State Management: Use flow_manager.state dictionary for persistent conversation data
  • Automatic Function Call Registration and Validation: All functions are automatically registered and validated at run-time
  • Provider Compatibility: Format differences handled automatically via adapter system
  • Deprecation: Some legacy patterns (transition_to, transition_callback) are deprecated in favor of consolidated function handlers