> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="task_messages" type="list[dict]" required>
  List of message dicts defining the current node's objectives. These tell the
  LLM what to do in this conversation state.

  ```python theme={null}
  "task_messages": [
      {"role": "developer", "content": "Ask the user for their name and email address."}
  ]
  ```
</ParamField>

<ParamField path="name" type="str">
  Identifier for the node. Useful for debug logging. If not provided, a UUID is
  generated automatically.
</ParamField>

<ParamField path="role_message" type="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.

  ```python theme={null}
  "role_message": "You are a friendly customer service agent."
  ```
</ParamField>

<ParamField path="role_messages" type="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.

  ```python theme={null}
  "role_messages": [
      {"role": "developer", "content": "You are a friendly customer service agent."}
  ]
  ```
</ParamField>

<ParamField path="functions" type="list[FlowsFunctionSchema | FlowsDirectFunction]">
  List of function definitions available in this node. Accepts
  [`FlowsFunctionSchema`](#flowsfunctionschema) objects or [direct
  functions](#flowsdirectfunction). See [Function
  Types](/api-reference/pipecat-flows/overview#function-types).
</ParamField>

<ParamField path="pre_actions" type="list[ActionConfig]">
  Actions to execute before LLM inference when transitioning to this node. See
  [ActionConfig](#actionconfig).
</ParamField>

<ParamField path="post_actions" type="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](#actionconfig).
</ParamField>

<ParamField path="context_strategy" type="ContextStrategyConfig">
  Strategy for managing conversation context when transitioning to this node.
  Overrides the default strategy set on
  [FlowManager](/api-reference/pipecat-flows/flow-manager). See
  [ContextStrategyConfig](#contextstrategyconfig).
</ParamField>

<ParamField path="respond_immediately" type="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).
</ParamField>

## FlowsFunctionSchema

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

<ParamField path="name" type="str" required>
  Name of the function. This is used to identify the function in LLM tool calls.
</ParamField>

<ParamField path="description" type="str" required>
  Description of what the function does. The LLM uses this to decide when to
  call the function.
</ParamField>

<ParamField path="properties" type="dict[str, Any]" required>
  Dictionary defining the function's parameters using JSON Schema format.

  ```python theme={null}
  "properties": {
      "city": {
          "type": "string",
          "description": "The city to get weather for"
      },
      "units": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "description": "Temperature units"
      }
  }
  ```
</ParamField>

<ParamField path="required" type="list[str]" required>
  List of required parameter names from `properties`.
</ParamField>

<ParamField path="handler" type="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`](#consolidatedfunctionresult) tuple
  to also specify the next node.
</ParamField>

<ParamField path="cancel_on_interruption" type="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.
</ParamField>

<ParamField path="timeout_secs" type="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.
</ParamField>

### Methods

#### to\_function\_schema

```python theme={null}
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

```python theme={null}
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.

<ParamField path="type" type="str" required>
  Action type identifier. Must match a registered action handler. Built-in types
  are `"tts_say"`, `"end_conversation"`, and `"function"`.
</ParamField>

<ParamField path="handler" type="Callable" default="None">
  Action handler function. Required for custom action types if not previously
  registered via
  [`FlowManager.register_action()`](/api-reference/pipecat-flows/flow-manager#register_action).
  Can be a legacy handler `(action)` or modern handler `(action, flow_manager)`.
</ParamField>

<ParamField path="text" type="str" default="None">
  Text to speak for the `tts_say` action, or the optional goodbye message for
  the `end_conversation` action.
</ParamField>

<ParamField path="append_text_to_context" type="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`.
</ParamField>

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

### 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

```python theme={null}
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](/pipecat/fundamentals/context-summarization) instead. Requires `summary_prompt` in `ContextStrategyConfig`. |

```python theme={null}
from pipecat_flows import ContextStrategy

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

## ContextStrategyConfig

Dataclass for configuring context management behavior.

<ParamField path="strategy" type="ContextStrategy" required>
  The context management strategy to use. See
  [ContextStrategy](#contextstrategy).
</ParamField>

<ParamField path="summary_prompt" type="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.
</ParamField>

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

### Example

```python theme={null}
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.

```python theme={null}
@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`. |

<Note>
  `@flows_direct_function` is a deprecated alias of `@flows_tool_options`. It
  still works but emits a `DeprecationWarning`; use `@flows_tool_options`
  instead.
</Note>

### Example

```python theme={null}
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:

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

### Deprecated: flows\_direct\_function

<Warning>
  **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.
</Warning>

## 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.

```python theme={null}
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

<Warning>
  **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.
</Warning>

```python theme={null}
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

```python theme={null}
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.

<Note>
  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.
</Note>

### ConsolidatedFunctionResult

```python theme={null}
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

```python theme={null}
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

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

```python theme={null}
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

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

```python theme={null}
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.