flow

A flow config joined to the application’s handlers.

A Flow is a FlowConfig joined to the code it names: the config’s nodes turned into runnable NodeConfig dicts, with every tool reference resolved to a Flows direct function, every transition_only function built from the config alone, and every transition wired to the node the config names.

Constructing a flow validates the references the config could not: each tool exists and has a valid direct-function signature, each function action names a callable. Tool return values are checked at call time against the configured-flow contract: a tool returns (result, TRANSITION_IN_YAML) and the config decides the next node. {{ key }} placeholders in prompts are left in place; FlowManager fills them from its state when it enters the node.

class pipecat.flows.flow.Flow(config: FlowConfig, *, handlers: Mapping[str, Callable] | Sequence[Mapping[str, Callable] | Any] | Any)

Bases: object

A FlowConfig joined to handlers.

The flow hands ready-made node configs to FlowManager:

config = FlowConfig.from_file("flow.yaml")
flow = Flow(config, handlers=handlers)
flow_manager = FlowManager(..., global_functions=flow.global_functions)
await flow_manager.initialize(flow.initial_node)

__init__(config: FlowConfig, *, handlers: Mapping[str, Callable] | Sequence[Mapping[str, Callable] | Any] | Any)

Join a config to the handlers it refers to.

Parameters:

• config – The flow config.

• handlers – The Python behind the config: the direct functions that implement its tools and the callables that implement its actions. A mapping of names to callables, or any object whose attributes are the callables, typically a module. A list or tuple of those lets tools and action handlers live in separate modules; a name that resolves to different callables in more than one of them is an error rather than a silent choice. Only the names the config references are looked up.

Raises:

FlowReferenceError – If a referenced tool or handler is missing or ambiguous, or a tool is not a valid direct function. Every such problem is collected and reported together.

property config: FlowConfig

The config this flow was constructed from.

property initial_node: NodeConfig

The node config the flow starts in.

property global_functions: list[FlowsFunctionSchema | Callable[[...], Awaitable[tuple[Any, NodeConfig | None | _NoResponse]]]]

Tools available at every node, for FlowManager(global_functions=...).

A fresh list each time, so the caller may extend it.

node(name: str) → NodeConfig

The node config for name.

Parameters:

name – A node name from the config.

Raises:

FlowError – If the config has no such node.