Skip to main content

​
Overview

A FlowConfig describes a conversation flow as data: the nodes, what each one says, which tools each node offers, and where each tool leads. It contains no Python callables. Every tool it references is a Flows direct function that lives in your code and is resolved by name when the config is joined to your handlers by constructing a Flow.
FlowConfig is a Pydantic model. It rejects unknown keys, and every model below does the same except Action, which passes extra keys through to its handler.
For a walkthrough of the format rather than a field list, see the Flow Configs guide.

​
Fields

​
str
required
Name of the node the flow starts in. Must be a key of nodes.
​
dict[str, FlowConfig.Node]
required
The flow’s nodes, keyed by name. At least one entry.
​
list[FlowConfig.Function]
default:"[]"
Tools offered at every node. Names must be unique among themselves and must not collide with any node’s functions.

​
Loaders

​
from_file

Load a config from a .yaml, .yml, or .json file. A file with any suffix other than .json is parsed as YAML, and may use !include with paths relative to the file’s own directory. Included paths are not confined to that directory, so load only files you control.

​
from_yaml

Load a config from YAML text. base_dir is the directory !include paths resolve against; when it is omitted, !include is unavailable. An include can read any file the process can read, so omit base_dir for text from an untrusted source.

​
from_json

Load a config from JSON text.

​
model_validate

Pydantic’s own loader, for a dict that is already parsed.

​
Models

​
FlowConfig.Node

One node of the flow. Its key under nodes is its name.
​
list[FlowConfig.Message]
required
What the LLM should do at this node.
​
str | None
default:"None"
The bot’s role or personality, sent as the LLM’s system instruction on entering this node. It persists across transitions until another node sets its own. May contain {{ key }} placeholders.
​
list[FlowConfig.Function]
default:"[]"
Tools offered at this node, in addition to the config’s global_functions. Names must be unique within the node.
​
list[FlowConfig.Action]
default:"[]"
Actions run before the LLM responds at this node.
​
list[FlowConfig.Action]
default:"[]"
Actions run after the LLM responds at this node.
​
"append" | "reset" | None
default:"None"
How the LLM context is updated on entering this node. Defaults to the FlowManager’s strategy. RESET_WITH_SUMMARY is not available here.
​
bool
default:"True"
Whether the LLM responds as soon as the node is entered.

​
FlowConfig.Message

One message in a node’s task_messages.
​
str
required
Message role, e.g. developer or system.
​
str
required
Message text. May contain {{ key }} placeholders.

​
FlowConfig.Function

A tool offered at a node, or globally.
​
str
required
The tool’s name, as the LLM sees it. For an ordinary entry, also the name of the direct function in the handlers.
​
bool
default:"False"
Whether the tool is defined here rather than in code. Such a tool takes no parameters, runs no code, and moves the conversation to transition_to when the LLM calls it. Requires description and a transition_to that names a node.
​
str | None
default:"None"
What the tool is for, for the LLM. Only a transition_only entry has one; a direct function describes itself in its docstring, and setting this on an ordinary entry is a validation error.
​
str | FlowConfig.Branch | None
default:"None"
Node to transition to after the tool completes, or a branch table. Omitted for tools that stay on the current node.

​
FlowConfig.Branch

A transition chosen by a field of the tool’s result.
​
str
required
Key of the tool’s result whose value selects the case. If the result is not a mapping, or has no such key, the call raises FlowError.
​
dict[str, str]
required
Result value to node name. At least one entry. Keys may be written as strings, booleans, or numbers; they are matched against the result value by its canonical string, so true: matches a result of Python True.
​
str | None
default:"None"
Node to transition to when the value matches no case. When omitted, an unmatched value stays on the current node.

​
FlowConfig.Action

A pre- or post-action on a node. Unlike the other models, this one allows extra keys, which pass through to the handler on the action dict.
​
str
required
Action type identifier. The built-in types are tts_say, end_conversation, and function.
​
str | None
default:"None"
Name of the handler in the handlers the Flow is constructed with. Required for function, optional for a custom type, and not allowed on tts_say or end_conversation.
A custom type with no handler must be registered in code with FlowManager.register_action.

​
Placeholders

Prompt text may refer to the manager’s state with {{ key }} placeholders: a node’s role_message, the content of its task_messages, and the text of a tts_say action. FlowManager fills them from flow_manager.state each time it enters the node, so a value stored by a handler earlier in the conversation can appear in a later prompt.
  • {{ order.size }} walks into a stored mapping.
  • Values are rendered with str().
  • A key that is not in state raises FlowError when the node is entered.
  • To show the LLM a literal {{ key }}, escape it as \{{ key }}.

​
Validation

Loading validates the config’s structure. A failure raises a Pydantic ValidationError.
  • The top level is a mapping.
  • initial_node names a defined node.
  • Every transition_to, including every case and default of a branch, names a defined node.
  • Function names are unique within a node and within global_functions, and a node’s function name does not collide with a global one.
  • A transition_only entry has a description and a transition_to that is a plain node name.
  • An ordinary entry has no description.
  • A function action has a handler; tts_say and end_conversation do not.
References into your code are checked separately, when the Flow is constructed.

​
Schema

The format’s JSON Schema is published in the Pipecat repository at src/pipecat/flows/flow_config.schema.json, for editors and other tools to vendor.