Registry / llm-agents / pipecat-ai-flows

pipecat-ai-flows

JSON →
library1.2.0pypypiunverified

Pipecat AI Flows provides a powerful conversation flow management system for Pipecat AI applications. It allows developers to define structured conversational experiences using dynamic nodes and functions, managing transitions and LLM interactions. The library is currently at version 1.0.0 and follows an active release cadence, with frequent updates preceding major version releases.

pip install pipecat-ai-flows
INSTALL
IMPORT
SIG · PIPECAT-AI-FLOWS
P
pipecat-ai-flows
llm-agentspythonv1.2.0
Install
31.4s avg
Import
Disk
808MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.0.24 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 36.5s
py 3.11
✕ build_error
✓ 30.3s
py 3.12
✕ build_error
✓ 28.95s
py 3.13
✕ build_error
✓ 29.75s
py 3.9
✕ build_error
✕ build_error
808MB installed
● package 808MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FlowManager
from pipecat_ai_flows import FlowManager
NodeConfig
from pipecat_ai_flows import NodeConfig
flows_direct_function
from pipecat_ai_flows import flows_direct_function
ActionConfig
from pipecat_ai_flows import ActionConfig

This quickstart demonstrates how to define a conversation flow using `FlowManager` and `NodeConfig`, including how to register direct functions with `@flows_direct_function`. It uses mock services to define the structure of a flow without requiring a full Pipecat AI pipeline setup. To run a full conversational agent, the `FlowManager`'s `llm_service` and `transport` would be connected to actual Pipecat AI components and integrated into a `PipelineRunner`.

import asyncio from pipecat_ai_flows import FlowManager, NodeConfig, flows_direct_function from pipecat_ai_flows.llm import LLMService # Base class from pipecat.frames.frames import TextFrame, EndFrame # Required for type hints import os # Minimal mock LLMService and Transport to make the example runnable class MockLLM(LLMService): def __init__(self): super().__init__("mock_llm") async def process_input(self, input_frames): for frame in input_frames: if isinstance(frame, TextFrame): yield TextFrame(f"Mock LLM received: {frame.text}") yield EndFrame() class MockTransport: async def send_frame(self, frame): if isinstance(frame, TextFrame): print(f"Transport received text: {frame.text}") elif isinstance(frame, EndFrame): print("Transport received EndFrame") async def receive_audio_frame(self): return None async def receive_text_frame(self): return None @flows_direct_function(cancel_on_interruption=True) async def greet_user(flow_manager: FlowManager, user_name: str = "there"): """Greets the user by their name.""" await flow_manager.transport.send_frame(TextFrame(f"Hello, {user_name}!")) return "Greeting complete.", "start" # Transition back to start async def main(): print("Setting up Pipecat AI Flow Manager...") # Define nodes for the conversation flow start_node = NodeConfig( name="start", task_messages=[ {"role": "developer", "content": "Ask the user for their name or just say hello."} ], functions=[greet_user], # Make `greet_user` available from this node next_node="ask_name_node", # Define a transition ) ask_name_node = NodeConfig( name="ask_name_node", task_messages=[ {"role": "developer", "content": "If the user hasn't provided a name, ask for it. Otherwise, acknowledge the name."} ], next_node=None # End of simple flow for this example ) # Initialize the FlowManager with nodes and required services flow_manager = FlowManager( initial_node=start_node, # The starting point of the flow llm_service=MockLLM(), # In a real app, use pipecat_ai.services.openai.OpenAILLMService etc. transport=MockTransport(), # In a real app, use pipecat_ai.transports.daily.DailyService etc. ) print(f"Flow Manager initialized. Current node: {flow_manager.current_node.name}") print("\nTo activate the flow and start a conversation, integrate this FlowManager with a Pipecat AI PipelineRunner.") print("For example: `pipeline = Pipeline(llm=flow_manager.llm_service, vad=..., stt=..., tts=..., transport=flow_manager.transport)`") print("Then: `await PipelineRunner().run(pipeline)`") if __name__ == "__main__": asyncio.run(main())
Debug
Known issues
breakingVersion 1.0.0 requires Python >= 3.11 and `pipecat-ai>=1.0.0`. Older Python or Pipecat AI versions are not supported.
fix
Upgrade your Python environment to 3.11 or higher and run `pip install --upgrade pipecat-ai` to ensure compatibility.
affects: >=1.0.0
breakingAll task and summary messages in `NodeConfig` must now use `"role": "developer"` instead of `"role": "user"` to correctly distinguish application instructions from user speech.
fix
Review all `task_messages` and summary messages in your `NodeConfig` definitions and change `"role": "user"` to `"role": "developer"`.
affects: >=1.0.0
breakingStatic Flows (configured via the `flow_config` argument and `FlowConfig` type) have been deprecated since v0.0.19 and are now removed in v1.0.0. Only Dynamic Flows using `NodeConfig` are supported.
fix
Migrate your flow definitions from `FlowConfig` to `NodeConfig` and remove the `flow_config` argument from `FlowManager` initialization. Refer to the migration guide for v1.0.0.
affects: >=1.0.0
gotchaThe `role_message` field is now the preferred way to set the bot's role/personality. System instructions are sent via `LLMUpdateSettingsFrame` rather than as system messages in the conversation context.
fix
Use the `role_message` field in your configurations for bot personality. If you rely on LLM system messages, ensure your `pipecat-ai` setup correctly handles `LLMUpdateSettingsFrame`.
affects: >=0.0.24
gotchaThe `@flows_direct_function` decorator allows configuring specific behaviors like `cancel_on_interruption` for functions directly invoked by the flow manager. This is crucial for controlling function execution during user interruptions.
fix
Apply `@flows_direct_function` to your direct functions and set `cancel_on_interruption=True` (default) or `False` as needed, to manage interruption behavior.
affects: >=0.0.23
gotcha`FlowManager` now supports a `global_functions` parameter during initialization, making functions available at every node without explicit definition in each `NodeConfig`.
fix
To make functions universally accessible, pass a list of `FlowsFunctionSchema` or `FlowsDirectFunction` objects to the `global_functions` parameter when initializing `FlowManager`.
affects: >=0.0.22
Upgrade
Version history
1.2.0latest on PyPI · released May 30, 2026
Audit
Dependencies
pipecat-airequiredCore dependency for Pipecat AI functionalities, required version >=1.0.0
pythonrequiredRequires Python 3.11 or higher
Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
pipecat-ai-flows — pip install pipecat-ai-flows · libregistry