Types

NodeConfig

Configuration for a single node in a conversation flow. task_messages is the only required field.

task_messages

list[dict]

required

List of message dicts defining the current node’s objectives. These tell the LLM what to do in this conversation state.

"task_messages": [
    {"role": "developer", "content": "Ask the user for their name and email address."}
]

name

str

Identifier for the node. Useful for debug logging. If not provided, a UUID is generated automatically.

role_message

str

The bot’s role and personality as a plain string. Sent as the LLM’s system instruction via LLMUpdateSettingsFrame. Once set, the system instruction persists across node transitions until a new node explicitly sets role_message again.

"role_message": "You are a friendly customer service agent."

role_messages

list[dict[str, Any]]

deprecated

Deprecated list-of-dicts format for the bot’s role and personality. Use role_message (str) instead. Will be removed in 2.0.0.

"role_messages": [
    {"role": "developer", "content": "You are a friendly customer service agent."}
]

functions

list[FlowsFunctionSchema | FlowsDirectFunction]

List of function definitions available in this node. Accepts FlowsFunctionSchema objects or direct functions. See Function Types.

pre_actions

list[ActionConfig]

Actions to execute before LLM inference when transitioning to this node. See ActionConfig.

post_actions

list[ActionConfig]

Actions to execute after LLM inference when transitioning to this node. If respond_immediately is False, post-actions are deferred until after the first LLM response in this node. See ActionConfig.

context_strategy

ContextStrategyConfig

Strategy for managing conversation context when transitioning to this node. Overrides the default strategy set on FlowManager. See ContextStrategyConfig.

respond_immediately

bool

default:"True"

Whether to trigger LLM inference immediately upon entering the node. Set to False when you want to wait for user input before the LLM responds (e.g., after a tts_say pre-action that asks a question).

FlowsFunctionSchema

Dataclass for defining function call schemas with Flows-specific properties. Provides a uniform way to define functions that works across all LLM providers.

name

str

required

Name of the function. This is used to identify the function in LLM tool calls.

description

str

required

Description of what the function does. The LLM uses this to decide when to call the function.

properties

dict[str, Any]

required

Dictionary defining the function’s parameters using JSON Schema format.

"properties": {
    "city": {
        "type": "string",
        "description": "The city to get weather for"
    },
    "units": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature units"
    }
}

required

list[str]

required

List of required parameter names from properties.

handler

FunctionHandler

required

Function handler to process the function call. Can be a modern handler (args, flow_manager), legacy handler (args), or zero-arg handler (). Legacy and zero-arg handlers are deprecated. The handler returns any JSON-serializable value, or a ConsolidatedFunctionResult tuple to also specify the next node.

cancel_on_interruption

bool

default:"False"

Whether to cancel this function call when the user interrupts. Set to True if you want the function call to be cancelled when the user speaks.

timeout_secs

float

default:"None"

Optional per-tool timeout in seconds. Overrides the global function_call_timeout_secs set on the LLM service. When None, the global timeout is used.

Methods

to_function_schema

schema.to_function_schema() -> FunctionSchema

Convert to a standard FunctionSchema for use with LLMs. Strips Flows-specific fields (handler, cancel_on_interruption, timeout_secs).

Example

from pipecat.flows import FlowsFunctionSchema, FlowResult

async def handle_weather(args, flow_manager):
    city = args["city"]
    weather = await get_weather(city)
    return {"status": "success", "weather": weather}

weather_function = FlowsFunctionSchema(
    name="get_weather",
    description="Get current weather for a city",
    properties={
        "city": {"type": "string", "description": "City name"}
    },
    required=["city"],
    handler=handle_weather,
)

ActionConfig

TypedDict for configuring actions that execute during node transitions.

type

str

required

Action type identifier. Must match a registered action handler. Built-in types are "tts_say", "end_conversation", and "function".

handler

Callable

default:"None"

Action handler function. Required for custom action types if not previously registered via FlowManager.register_action(). Can be a legacy handler (action) or modern handler (action, flow_manager).

text

str

default:"None"

Text to speak for the tts_say action, or the optional goodbye message for the end_conversation action.

append_text_to_context

bool

default:"True"

For the built-in TTS actions (tts_say and end_conversation), whether the spoken text is appended to the LLM context. Defaults to True.

Additional fields are allowed and passed through to the handler. For example, a "notify_slack" action could include "channel" and "text" fields.

Built-in Action Types

Type	Description	Required Fields
`tts_say`	Speak text using the pipeline’s TTS service. The spoken text is appended to the LLM context by default.	`text`
`end_conversation`	End the conversation, optionally speaking a goodbye message.	`text` (optional)
`function`	Execute a function inline in the pipeline	`handler`

Example

node_config = NodeConfig(
    task_messages=[{"role": "developer", "content": "Help the user."}],
    pre_actions=[
        {"type": "tts_say", "text": "Welcome! Let me help you with that."},
    ],
    post_actions=[
        {"type": "end_conversation", "text": "Goodbye!"},
    ],
)

ContextStrategy

Enum defining strategies for managing conversation context during node transitions.

Value	Description
`APPEND`	Append new messages to existing context. This is the default behavior.
`RESET`	Reset context with new messages only. Previous conversation history is discarded.
`RESET_WITH_SUMMARY`	Deprecated. Reset context but include an LLM-generated summary. Use Pipecat’s native context summarization instead. Requires `summary_prompt` in `ContextStrategyConfig`.

from pipecat.flows import ContextStrategy

strategy = ContextStrategy.APPEND
strategy = ContextStrategy.RESET
strategy = ContextStrategy.RESET_WITH_SUMMARY

ContextStrategyConfig

Dataclass for configuring context management behavior.

strategy

ContextStrategy

required

The context management strategy to use. See ContextStrategy.

summary_prompt

str

default:"None"

Prompt text for generating a conversation summary. Required when using RESET_WITH_SUMMARY (deprecated). The LLM uses this prompt to summarize the conversation before resetting context.

Raises: ValueError if summary_prompt is not provided when using RESET_WITH_SUMMARY (deprecated).

Example

from pipecat.flows import ContextStrategy, ContextStrategyConfig

# Append (default)
config = ContextStrategyConfig(strategy=ContextStrategy.APPEND)

# Reset
config = ContextStrategyConfig(strategy=ContextStrategy.RESET)

# Reset with summary (deprecated — use Pipecat's native context summarization instead)
config = ContextStrategyConfig(
    strategy=ContextStrategy.RESET_WITH_SUMMARY,
    summary_prompt="Summarize the key information collected so far.",
)

flows_tool_options Decorator

Decorator that overrides a function’s default call options. It’s optional — a function works without it.

@flows_tool_options(*, cancel_on_interruption: bool = False, timeout_secs: float | None = None)

Parameter	Type	Default	Description
`cancel_on_interruption`	`bool`	`False`	Whether to cancel the function call when the user interrupts.
`timeout_secs`	`float`	`None`	Optional per-tool timeout in seconds, overriding the global `function_call_timeout_secs`.

@flows_direct_function is a deprecated alias of @flows_tool_options. It still works but emits a DeprecationWarning; use @flows_tool_options instead.

Example

from pipecat.flows import FlowManager, flows_tool_options, ConsolidatedFunctionResult

@flows_tool_options(cancel_on_interruption=True)
async def lookup_order(
    flow_manager: FlowManager, order_id: str
) -> ConsolidatedFunctionResult:
    """Look up an order by its ID.

    Args:
        order_id: The order ID to look up.
    """
    order = await db.get_order(order_id)
    flow_manager.state["order"] = order
    result = {"status": "success", "order": order}
    next_node = create_order_details_node(order)
    return result, next_node

The function can then be passed directly in a node’s functions list:

node_config = NodeConfig(
    task_messages=[{"role": "developer", "content": "Ask for the order ID."}],
    functions=[lookup_order],
)

Deprecated: flows_direct_function

Deprecated. The @flows_direct_function decorator has been renamed to @flows_tool_options. The old name still works but emits a DeprecationWarning and will be removed in a future version. Update your code to use @flows_tool_options instead.

FlowsDirectFunction

Type alias for direct functions with automatic metadata extraction. Any async callable matching this signature can be used as a direct function in node configurations.

FlowsDirectFunction = Callable[..., Awaitable[ConsolidatedFunctionResult]]

Direct functions must accept flow_manager: FlowManager as the first parameter, followed by any named parameters described in the function’s docstring. Python’s Protocol system cannot express “any concrete named-parameter list”, so this is defined as a generic Callable. Runtime validation is handled by FlowsDirectFunctionWrapper.validate_function.

NO_RESPONSE

Sentinel value used in ConsolidatedFunctionResult to indicate that a function should finish without an immediate response or node transition.

from pipecat.flows import NO_RESPONSE

async def handoff_to_router(flow_manager: FlowManager, reason: str):
    # Transfer control to another worker
    await flow_manager.worker.activate_worker("router", deactivate_self=True)
    # Don't respond - the other worker will handle the next turn
    return {"status": "transferred"}, NO_RESPONSE

When a function returns NO_RESPONSE as the second element:

The function result is added to the conversation context
No LLM inference is triggered
No node transition occurs
The next response is triggered by something else (e.g., user input or another worker)

This is useful for multi-worker handoffs where control is passed to another worker that should respond next, or when a function needs to pause the conversation until an external event occurs. For functions that transition to a new node, use respond_immediately: False in NodeConfig instead.

Type Aliases

FlowResult

Deprecated. No replacement. FlowResult is no longer required or referenced by any handler type, and Pipecat’s upstream function-call-result contract is Any — define your own TypedDict or return any JSON-serializable value. Will be removed in 2.0.0.

class FlowResult(TypedDict, total=False):
    status: str
    error: str

Optional convention TypedDict for status/error results. The status field indicates the outcome. The optional error field contains an error message if execution failed. Additional fields are allowed and passed through to the LLM.

FlowArgs

FlowArgs = dict[str, Any]

Type alias for function handler arguments. Contains the parameters extracted from the LLM’s function call. Each invocation gets its own dict, so handlers may mutate it freely.

In 2.0.0, this alias is planned to widen to Mapping[str, Any] to align with Pipecat’s typing. Handlers that only read args will be unaffected; handlers that mutate args will need to keep the annotation as dict[str, Any] explicitly.

ConsolidatedFunctionResult

ConsolidatedFunctionResult = tuple[Any, NodeConfig | None | NO_RESPONSE]

Return type for consolidated function handlers that both do work and specify the next node:

First element: Any JSON-serializable value (or None for transition-only functions)
Second element: The next node as a NodeConfig, None to stay on the current node and respond, or NO_RESPONSE to finish without transitioning or responding

FlowFunctionHandler

FlowFunctionHandler = Callable[[FlowArgs, FlowManager], Awaitable[Any]]

Type for modern function handlers that receive both arguments and the FlowManager instance. Args:

args (FlowArgs): Dictionary of arguments from the function call.
flow_manager (FlowManager): Reference to the FlowManager instance.

Returns: Any JSON-serializable value, or a ConsolidatedFunctionResult tuple to also specify the next node.

ZeroArgFunctionHandler

Deprecated. Zero-argument function handlers are deprecated and will be removed in 2.0.0. Update handlers to accept (args, flow_manager) instead.

ZeroArgFunctionHandler = Callable[[], Awaitable[Any]]

Type for function handlers that take no arguments. The flow manager detects the signature automatically and emits a DeprecationWarning. Returns: Any JSON-serializable value, or a ConsolidatedFunctionResult tuple to also specify the next node.

LegacyFunctionHandler

Deprecated. Single-argument function handlers are deprecated and will be removed in 2.0.0. Update handlers to accept (args, flow_manager) instead.

LegacyFunctionHandler = Callable[[FlowArgs], Awaitable[Any]]

Type for legacy function handlers that only receive arguments. Both legacy and modern handlers are supported; the flow manager detects the signature automatically and emits a DeprecationWarning. Args:

args (FlowArgs): Dictionary of arguments from the function call.

Returns: Any JSON-serializable value, or a ConsolidatedFunctionResult tuple to also specify the next node.

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

NodeConfig

FlowsFunctionSchema

Methods

to_function_schema

Example

ActionConfig

Built-in Action Types

Example

ContextStrategy

ContextStrategyConfig

Example

flows_tool_options Decorator

Example

Deprecated: flows_direct_function

FlowsDirectFunction

NO_RESPONSE

Type Aliases

FlowResult

FlowArgs

ConsolidatedFunctionResult

FlowFunctionHandler

ZeroArgFunctionHandler

LegacyFunctionHandler

​NodeConfig

​FlowsFunctionSchema

​Methods

​to_function_schema

​Example

​ActionConfig

​Built-in Action Types

​Example

​ContextStrategy

​ContextStrategyConfig

​Example

​flows_tool_options Decorator

​Example

​Deprecated: flows_direct_function

​FlowsDirectFunction

​NO_RESPONSE

​Type Aliases

​FlowResult

​FlowArgs

​ConsolidatedFunctionResult

​FlowFunctionHandler

​ZeroArgFunctionHandler

​LegacyFunctionHandler

NodeConfig

FlowsFunctionSchema

Methods

to_function_schema

Example

ActionConfig

Built-in Action Types

Example

ContextStrategy

ContextStrategyConfig

Example

flows_tool_options Decorator

Example

Deprecated: flows_direct_function

FlowsDirectFunction

NO_RESPONSE

Type Aliases

FlowResult

FlowArgs

ConsolidatedFunctionResult

FlowFunctionHandler

ZeroArgFunctionHandler

LegacyFunctionHandler