Types

Type definitions and configuration schemas for Pipecat Flows

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 · default: "None"

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 content used by tts_say and optionally by end_conversation (as a goodbye message).

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	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_direct_function Decorator

Decorator that attaches metadata to a Pipecat direct function for use in Flows.

@flows_direct_function(*, 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.

Direct functions have their schema automatically extracted from the function signature and docstring. The first parameter must be flow_manager: FlowManager, and all other parameters become the function’s properties. The docstring provides the function description and parameter descriptions (Google-style).

Direct functions must return a ConsolidatedFunctionResult tuple.

Example

from pipecat_flows import FlowManager, flows_direct_function, ConsolidatedFunctionResult

@flows_direct_function(cancel_on_interruption=False)
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],
}

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.

Type Aliases

FlowResult

Deprecated. FlowResult is no longer required by any handler type and will be removed in 2.0.0. Function handlers can return any JSON-serializable value. Define your own TypedDict if you want a structured result.

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]

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, or None for node functions

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.