config

Declarative flow configuration.

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 a node references is a Flows direct function that lives in the application’s code and is resolved by name when the config is joined to the application’s handlers by constructing a Flow. The exception is a transition_only function, which does nothing but move the conversation to another node: the config supplies its description and it needs no code.

The config loads from YAML, JSON, or a plain dict, and is validated structurally on load: the initial node exists, every transition names a node, tool names are unique within a node, and every action is well-formed. Constructing a Flow validates the references to code.

Example YAML:

initial_node: greet

nodes:
  greet:
    role_message: You are a friendly order-taking assistant.
    task_messages:
      - role: developer
        content: Greet the caller and ask whether they want pizza or sushi.
    functions:
      - name: choose_pizza
        transition_only: true
        description: The caller wants to order pizza.
        transition_to: pizza
      - name: choose_sushi
        transition_only: true
        description: The caller wants to order sushi.
        transition_to: sushi

  pizza:
    task_messages:
      - role: developer
        content: Take a pizza order.
    functions:
      - name: select_pizza_order
        transition_to:
          field: status
          cases:
            ok: confirm
            unavailable: pizza
          default: confirm

global_functions:
  - name: get_delivery_estimate

pipecat.flows.config.BUILT_IN_ACTIONS_WITHOUT_HANDLER = frozenset({'end_conversation', 'tts_say'}): Built-in action types whose behavior is fixed, so a handler is not allowed.

pipecat.flows.config.BUILT_IN_ACTIONS = frozenset({'end_conversation', 'function', 'tts_say'}): Every action type the runtime provides without registration.

pipecat.flows.config.case_key(value: Any) → str[source]

The canonical string a branch matches a case key or result value on.

Booleans, and strings spelling one in any case, become true and false; everything else is its str(). So true:, "True":, and a result of Python True all meet at the same case.

class pipecat.flows.config.FlowConfig(*, initial_node: str, nodes: ~typing.Annotated[dict[str, ~pipecat.flows.config.FlowConfig.Node], ~annotated_types.MinLen(min_length=1)], global_functions: list[~pipecat.flows.config.FlowConfig.Function] = <factory>)[source]

Bases: BaseModel

A conversation flow described as data.

Load one with from_file() for a YAML or JSON file, from_yaml() for YAML text, from_json() for JSON text, or Pydantic’s model_validate for a dict that is already parsed.

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, and 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 }}.

Parameters:

initial_node – Name of the node the flow starts in.
nodes – The flow’s nodes, keyed by name.
global_functions – Tools offered at every node.

class Message(*, role: str, content: str)[source]

Bases: BaseModel

One message in a node’s task_messages.

Parameters:

role – Message role, e.g. developer or system.
content – Message text. May contain {{ key }} placeholders; see FlowConfig.

role: str

content: str

class Branch(*, field: str, cases: Annotated[dict[str, str], MinLen(min_length=1)], default: str | None = None)[source]

Bases: BaseModel

A transition chosen by a field of the tool’s result.

Parameters:

field – Key of the tool’s result whose value selects the case.
cases – Result value to node name. Keys may be written as strings, booleans, or numbers; they match the result value by its canonical string (see case_key()), so true: matches a result of True.
default – Node to transition to when the value matches no case. When omitted, an unmatched value stays on the current node.

field: str

cases: dict[str, str]

default: str | None

targets() → list[str][source]: Every node name this branch can transition to.

class Function(*, name: str, transition_only: bool = False, description: str | None = None, transition_to: str | Branch | None = None)[source]

Bases: BaseModel

A tool offered at a node.

Ordinarily the entry names a Flows direct function in the handlers a Flow is constructed with, and the tool’s description and parameters come from that function. A transition_only entry is defined entirely here instead: it takes no parameters, runs no code, and moves the conversation to transition_to when the LLM calls it.

Parameters:

name – The tool’s name, as the LLM sees it. For an ordinary entry, also the name of the direct function in the handlers.
transition_only – Whether the tool is defined here rather than in code. Requires description and a transition_to that names a node.
description – What the tool is for, for the LLM. Only a transition_only entry has one; a direct function describes itself in its docstring.
transition_to – Node to transition to after the tool completes, or a FlowConfig.Branch. Omitted for tools that stay on the current node.

name: str

transition_only: bool

description: str | None

transition_to: str | FlowConfig.Branch | None

targets() → list[str][source]: Every node name this function can transition to.

class Action(*, type: str, handler: str | None = None, **extra_data: Any)[source]

Bases: BaseModel

A pre- or post-action on a node.

The built-in tts_say and end_conversation types take no handler. The built-in function type requires one: the handler runs inline in the pipeline, queued behind the bot’s turn. A custom type may name a handler too, which then runs immediately when the node’s actions execute; a custom type without one must be registered in code with FlowManager.register_action. Any additional keys pass through to the handler. The text of a tts_say action may contain {{ key }} placeholders; see FlowConfig.

Parameters:

type – Action type identifier.
handler – Name of the handler in the handlers a Flow is constructed with. Required for function, optional for custom types, not allowed on tts_say or end_conversation.

type: str

handler: str | None

property registered_in_code: bool: Whether this is a custom type whose handler the config does not name.

extras() → dict[str, Any][source]: The pass-through keys beyond type and handler.

class Node(*, task_messages: list[~pipecat.flows.config.FlowConfig.Message], role_message: str | None = None, functions: list[~pipecat.flows.config.FlowConfig.Function] = <factory>, pre_actions: list[~pipecat.flows.config.FlowConfig.Action] = <factory>, post_actions: list[~pipecat.flows.config.FlowConfig.Action] = <factory>, context_strategy: ~typing.Literal['append', 'reset'] | None = None, respond_immediately: bool = True)[source]

Bases: BaseModel

One node of the flow.

Parameters:

task_messages – What the LLM should do at this node.
role_message – 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; see FlowConfig.
functions – Tools offered at this node, in addition to the config’s global_functions.
pre_actions – Actions run before the LLM responds at this node.
post_actions – Actions run after the LLM responds at this node.
context_strategy – How the LLM context is updated on entering this node. Defaults to the FlowManager’s strategy.
respond_immediately – Whether the LLM responds as soon as the node is entered. Defaults to True.