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

# Functions

> Define Pipecat Flows tools: node and edge functions, transition_only entries, branch tables, and the direct-function handler contract.

A function is a tool the LLM can call. It does work, such as reading or writing an external system, moves the conversation to another node, or both. A node's `task_messages` describe the task and name the functions it may use; when the LLM has what it needs, it calls one, and the conversation moves on.

## Node and Edge Functions

A function is one of two kinds, in either form of flow:

* A **node function** does work within the current conversation state without switching nodes.
* An **edge function** transitions to another conversation state, optionally doing work first.

What differs between the two forms is *who decides* which kind a function is. In a [flow config](https://docs.pipecat.ai/pipecat/flows/flow-configs.md) the entry decides: an entry with `transition_to` is an edge function. In code the handler decides, by returning the next node or not.

## Declarative

A `functions` entry names a tool and, optionally, where it leads:

```yaml theme={null}
functions:
  - name: select_pizza_order
    transition_to: confirm
```

**name** `str` *required*

The tool's name, as the LLM sees it, and the name of the direct function in
the handlers. The config carries no description or parameters for an ordinary
entry — those come from the function's signature and docstring.

**transition\_to** `str | Branch`

The node to transition to after the tool completes, or a [branch
table](#branch-tables). Omit it for a node function, which stays put.

**transition\_only** `bool` (default: false)

Whether the tool is defined here rather than in code. See
[below](#transition-only-functions).

**description** `str`

What the tool is for, for the LLM. Only a `transition_only` entry takes one;
an ordinary entry describes itself in its docstring, and giving it a
description here is an error.

### The Handler Contract

The Python behind an ordinary entry is a **direct function**: a single async function that is *both* the handler and the schema. Flows derives the tool's description, parameter properties, and which parameters are required from the signature and a Google-style docstring. The first parameter is always `flow_manager`; the function's own parameters follow.

```python handlers.py theme={null}
from pipecat.flows import TRANSITION_IN_YAML, FlowManager


async def select_pizza_order(flow_manager: FlowManager, size: str, pizza_type: str):
    """Record the pizza order details.

    Args:
        size (str): Size of the pizza. Must be one of "small", "medium", or "large".
        pizza_type (str): Type of pizza. Must be one of "pepperoni", "cheese", "supreme", or "vegetarian".
    """
    price = {"small": 10.00, "medium": 15.00, "large": 20.00}[size]
    flow_manager.state["order"] = {"size": size, "type": pizza_type, "price": price}
    return {"size": size, "type": pizza_type, "price": price}, TRANSITION_IN_YAML
```

A handler in a declarative flow returns `(result, TRANSITION_IN_YAML)`. The result is any JSON-serializable value, or `None`, and is given to the LLM as context. `TRANSITION_IN_YAML` is a sentinel meaning "the config decides" — it is what keeps transitions out of your Python.

> [!WARNING]
>
> Returning anything else in the next-node slot raises a `FlowError` at call
> time. A node name string, a `NodeConfig`, or `None` are all rejected: in a
> declarative flow the config owns transitions, so there is nothing for the
> handler to decide. Return `TRANSITION_IN_YAML` even from a node function that
> stays put — the config's missing `transition_to` is what makes it stay.

To leave the bot silent after the tool finishes, rather than responding immediately, return `(result, NO_RESPONSE)`. That passes through to the manager unchanged.

### Transition-Only Functions

A function that only moves the conversation needs no Python. Mark the entry `transition_only: true` and give it a `description` for the LLM and a node name to transition to:

```yaml theme={null}
functions:
  - name: choose_pizza
    transition_only: true
    description: The caller wants to order pizza.
    transition_to: pizza
```

It takes no parameters and runs no code. A `transition_only` entry must have both a `description` and a `transition_to` that names a node — a branch table needs a result to branch on, and there is none.

### Branch Tables

When the destination depends on the tool's outcome, `transition_to` can be a **branch table** that routes on a field of the result:

```yaml theme={null}
functions:
  - name: check_availability
    transition_to:
      field: status
      cases:
        available: confirm
        unavailable: no_availability
```

**field** `str` *required*

Key of the tool's result whose value selects the case. The result must be a
mapping with that key, or the call raises a `FlowError`.

**cases** `dict[str, str]` *required*

Result value to node name. At least one entry.

**default** `str`

Node to transition to when the value matches no case. When omitted, an
unmatched value stays on the current node.

Case keys may be written as strings, booleans, or numbers. They are matched against the result value by a canonical string, so `true:` in YAML matches a Python `True`, and `"True":` matches it too:

```yaml theme={null}
functions:
  - name: verify_birthday
    transition_to:
      field: verified
      cases:
        true: get_prescriptions
```

### Routing on Business Logic

A branch table routes on a field, not on arbitrary logic, and that is the point. Keep the business logic flow-agnostic, wrap it in a thin tool, a shim, that reports the outcome as a named field, and let the config route on that field.

`check_availability` in the [restaurant reservation example](https://github.com/pipecat-ai/pipecat/tree/main/examples/flows/yaml/restaurant_reservation) is the shape:

```python handlers.py theme={null}
class MockReservationSystem:
    """Business logic. Knows nothing about the flow."""

    async def check_availability(
        self, party_size: int, requested_time: str
    ) -> tuple[bool, list[str]]:
        ...


reservation_system = MockReservationSystem()


async def check_availability(flow_manager: FlowManager, time: str, party_size: int):
    """Check availability for requested time.

    Args:
        time (str): Requested reservation time in "HH:MM AM/PM" format. Must be between 5 PM and 10 PM.
        party_size (int): Number of people in the party.
    """
    is_available, alternative_times = await reservation_system.check_availability(
        party_size, time
    )

    # The business logic answered with a bool. Report it as a named status so
    # the config can branch on it; the config, not this tool, picks the node.
    return {
        "status": "available" if is_available else "unavailable",
        "time": time,
        "alternative_times": alternative_times,
    }, TRANSITION_IN_YAML
```

The reservation system stays reusable and testable on its own, the tool stays a few lines, and where "unavailable" leads is a config change.

## Programmatic

In a flow built in code, the handler returns the next node itself. A direct function is written the same way — `flow_manager` first, then its own parameters, documented in a Google-style docstring:

```python theme={null}
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.
    """
    print(f"Your favorite color is: {color}")
    return color, create_end_node()

# List the function in a node
node_config = NodeConfig(
    # ...
    functions=[record_favorite_color],
)
```

> [!NOTE]
>
> The direct-function schema generator doesn't yet map `Literal` types to a
> JSON-schema `enum`. Express enum-like constraints in the docstring prose
> instead (e.g. *'Must be one of "red", "green", or "blue"'*). If you need a
> strict `enum` in the schema, use the
> [`FlowsFunctionSchema`](#advanced-defining-a-function-with-flowsfunctionschema)
> pattern.

### Return Values

A function returns a tuple:

* **Result**: Data provided to the LLM for context in subsequent completions, or `None`. Any JSON-serializable value is accepted.
* **Next Node**: The `NodeConfig` for Flows to transition to next, or `None`.

A node function returns `None` for the next node. One that *only* changes conversational state, without doing other work, can return `None` for the result. Returning `NO_RESPONSE` in the next-node slot keeps the bot silent after the call.

### Advanced: Defining a Function with `FlowsFunctionSchema`

Direct functions cover most cases. Reach for `FlowsFunctionSchema` when you need explicit control over the schema — for example a strict `enum` constraint or a numeric `minimum`/`maximum` — that a direct function can't yet express. This is one of the reasons to write a flow in code rather than a config.

A `FlowsFunctionSchema` spells out the function's name, description, and parameters by hand, and takes the `handler` that runs when the LLM calls the function:

```python theme={null}
from pipecat.flows import FlowsFunctionSchema

async def record_favorite_color(
    args: FlowArgs, flow_manager: FlowManager
) -> tuple[str, NodeConfig]:
    """Record the color, then set the next node."""
    print(f"Your favorite color is: {args['color']}")
    return args["color"], create_end_node()

record_favorite_color_func = FlowsFunctionSchema(
    name="record_favorite_color",
    description="Record the color the user said is their favorite.",
    properties={
        # A strict enum — the kind of explicit control a direct function can't yet express.
        "color": {"type": "string", "enum": ["red", "green", "blue"]},
    },
    required=["color"],
    handler=record_favorite_color,
)

# List the schema in a node
node_config = NodeConfig(
    # ...
    functions=[record_favorite_color_func],
)
```

The `handler` is required. It receives the LLM-supplied arguments and returns the same [result and next-node values](#return-values) as a direct function.

## Per-Function Call Options

By default, a function is not cancelled when the user interrupts, and it uses the LLM service's global timeout. To override either, decorate the handler with `@flows_tool_options`. This works the same in both forms — it is a property of the Python, so a declarative flow's handlers take it too:

```python theme={null}
from pipecat.flows import TRANSITION_IN_YAML, flows_tool_options

# This lookup is only useful for the current turn, so cancel it if the user
# interrupts and the conversation moves on.
@flows_tool_options(cancel_on_interruption=True)
async def check_weather(
    flow_manager: FlowManager,
    city: str,
):
    """Look up the current weather for a city.

    Args:
        city: The city to look up.
    """
    return {"weather": await get_weather(city)}, TRANSITION_IN_YAML
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.