State Management

Cross-Node State

Pipecat Flows supports cross-node state through the flow_manager.state dictionary. This persistent storage lets you share data across nodes throughout the entire conversation:

Declarative
Programmatic

handlers.py

async def collect_party_size(flow_manager: FlowManager, size: int):
    """Record the number of people in the party.

    Args:
        size (int): Number of people in the party. Must be between 1 and 12.
    """
    flow_manager.state["party_size"] = size  # Cross-node state setting
    return {"size": size}, TRANSITION_IN_YAML

async def record_favorite_color(
    flow_manager: FlowManager,
    color: str,
) -> tuple[str, NodeConfig]:
    """Record the color the user said is their favorite.

    Args:
        color: The user's favorite color.
    """
    flow_manager.state["color"] = color  # Cross-node state setting
    print(f"Your favorite color is: {color}")
    return color, create_end_node()

State is also where you put the facts a session starts with — a caller’s name, a tenant’s restaurant, a practice’s details — by writing them before initialize().

Placeholders

A node’s prompt text can read from state with {{ key }} placeholders. FlowManager fills them in each time it enters the node, so a value a handler stored earlier in the conversation can appear in a later prompt, including after a context reset. Placeholders are rendered in three places:

a node’s role_message
the content of each of its task_messages
the text of a tts_say action

Because the manager does the rendering, placeholders work the same way in a flow config and in a NodeConfig built in code.

Session Facts

Write the facts before initializing, and every node’s prompts can refer to them:

flow_manager.state.update(
    {
        "practice_name": os.getenv("PRACTICE_NAME", "Tri-County Health Services"),
        "patient_name": os.getenv("PATIENT_NAME", "Chad Bailey"),
    }
)

await flow_manager.initialize(flow.initial_node)

role_message: >
  You are Jessica, an agent for {{ practice_name }}, on the phone with a
  patient.

Values a Handler Stored

A placeholder is filled on every entry, not once at load, so a prompt sees whatever handlers have stored by the time the node is reached. The insurance quote example turns on this: each quote handler stores the figures in state, and the results node reads them back.

handlers.py

async def update_coverage(flow_manager: FlowManager, coverage_amount: int, deductible: int):
    """Recalculate quote with new coverage options.

    Args:
        coverage_amount (int): The desired coverage amount in dollars.
        deductible (int): The desired deductible amount in dollars.
    """
    monthly_premium = (coverage_amount / 250000) * 100
    if deductible > 1000:
        monthly_premium *= 0.9  # 10% discount for a higher deductible

    # Store each figure formatted the way the prompt reads it aloud.
    flow_manager.state["quote"] = {
        "monthly_premium": f"{monthly_premium:.2f}",
        "coverage_amount": f"{coverage_amount:,}",
        "deductible": f"{deductible:,}",
    }
    return {"monthly_premium": monthly_premium}, TRANSITION_IN_YAML

quote_results:
  task_messages:
    - role: developer
      content: >-
        The current quote is {{ quote.monthly_premium }} dollars a month for
        {{ quote.coverage_amount }} dollars of coverage with a
        {{ quote.deductible }} dollar deductible. Tell the customer the
        premium, coverage, and deductible in one sentence, then ask if they'd
        like to change the coverage or deductible.
  functions:
    - name: update_coverage
      transition_to: quote_results

update_coverage leads back to quote_results, so re-entering the node renders it again with the new figures. That is a loop with no code behind it.

Dotted Paths, Escaping, and Missing Keys

Dotted paths walk into a stored mapping: {{ quote.monthly_premium }} reads state["quote"]["monthly_premium"]. Values are rendered with str().
Escaping: to show the LLM a literal {{ key }}, write \{{ key }}.
A missing key raises. If a placeholder names a key that isn’t in state when the node is entered, Flows raises a FlowError. There is no silent empty string — a prompt with a hole in it is a bug worth failing on.

Store values in state already formatted for speech, as update_coverage does above. The placeholder is substituted verbatim, so "81.00" reads better than the 81.0 a raw float would produce.

Global Functions

Pipecat Flows supports defining functions that are available across all nodes in your flow. They’re defined the same way as node-specific functions, and are passed into the FlowManager at initialization:

Declarative
Programmatic

List them at the top level of the config, then hand flow.global_functions to the manager:

global_functions:
  - name: get_delivery_estimate

flow_manager = FlowManager(
    worker=worker,
    llm=llm,
    context_aggregator=context_aggregator,
    global_functions=flow.global_functions,  # Cross-node functions
)

A global function is written like any other entry, so it can transition too. Its name can’t also be used by a node’s functions.

flow_manager = FlowManager(
    worker=worker,
    llm=llm,
    context_aggregator=context_aggregator,
    transport=transport,
    global_functions=[global_function_1, global_function_2],  # Cross-node functions
)

Get Started

Migration

Learning Pipecat

Fundamentals

Flows

Evals

Features

Telephony

Deployment

Examples & Recipes

State Management

Cross-Node State

Placeholders

Session Facts

Values a Handler Stored

Dotted Paths, Escaping, and Missing Keys

Global Functions

​Cross-Node State

​Placeholders

​Session Facts

​Values a Handler Stored

​Dotted Paths, Escaping, and Missing Keys

​Global Functions

Cross-Node State

Placeholders

Session Facts

Values a Handler Stored

Dotted Paths, Escaping, and Missing Keys

Global Functions