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

# How your AI agent chooses and runs Procedures

> How the AI agent decides which Procedure to run, why a Procedure may be skipped, and how Procedure-only Actions keep certain tools on rails.

When a message comes in, the AI agent looks at your **active** Procedures, decides
whether one applies, and if so, follows its steps. This page explains the rules
that govern that decision so your Procedures behave predictably.

Most surprises with [Procedures](https://chatbase.co/docs/user-guides/chatbot/procedures/procedures-overview.md)
come from these rules: a Procedure that is skipped on one channel, a flow that
switches partway through, or an Action that never fires on its own. Knowing how a
turn runs makes those cases easy to diagnose.

## What happens on one turn

Here is one turn of a conversation on WhatsApp, where you have a refund Procedure
that references `@Get_Orders` and `@Create_Return`:

**1. The customer sends a message**

The customer writes "I'd like a refund for my last order."

**2. The AI agent filters the Procedures it can use**

Only **Active** Procedures are considered. Any Procedure that references an
Action that is unavailable on WhatsApp is skipped, so the refund Procedure stays
in the running only if both `Get_Orders` and `Create_Return` are on for WhatsApp.

**3. The AI agent picks at most one Procedure**

The refund Procedure's trigger matches the request best, so the AI agent engages
it. If no Procedure applies, the AI agent replies without one.

**4. The AI agent works through the steps in order**

It runs each step top to bottom. At a branch step, it evaluates the conditions
from the top, runs the first one that matches, then continues after the branch.
When a step references an Action, the AI agent calls it, including Actions set to
**Only use in Procedures**.

**5. The AI agent pauses when it needs the customer**

If a step needs something from the customer, such as which items to return, the
AI agent asks and stops. On the next turn, the refund Procedure stays in flight
and picks up where it left off, unless the customer clearly switches topics.

## Only one Procedure runs per turn

Within a single turn, the AI agent runs **at most one Procedure**: the one whose
**trigger** best matches what the customer is asking for *right now*. It never
executes two Procedures in the same reply.

This is a per-turn limit, not a lock. The active Procedure can change from one
message to the next: if the customer is partway through Procedure A and then sends
a message that matches Procedure B's trigger, the AI agent can switch to Procedure B
on that turn.

> [!NOTE]
>
> A Procedure stays in flight across turns while the customer is mid-flow (for
> example, replying "yes" or providing a value the AI agent asked for). It ends when
> the situation is handled, or when the customer clearly switches topics, at which
> point a different Procedure can engage on the next turn.

## Procedures are dropped when an Action isn't available

A Procedure can reference Actions (with `@action_name`) in its steps. Before a
Procedure is even considered for a conversation, the AI agent checks that **every**
Action it references is available on the **current channel**.

If even one referenced Action is unavailable, the **whole Procedure is skipped** for
that conversation. An Action counts as unavailable when it is:

* Disabled or removed,
* Disabled on the current channel, or
* Not supported on the current channel/medium (for example, a Widget-based Action
  on a channel that can't render Widgets).

> [!WARNING]
>
> The check is all-or-nothing and covers steps **inside conditional branches too**,
> even branches that might never run on a given conversation. If a deep branch
> references an Action that's off on, say, WhatsApp, the entire Procedure is dropped
> on WhatsApp. This is intentional: a half-runnable Procedure is worse than none.

**What this means for you:** if a Procedure works in one channel but seems to be
ignored in another, check that *all* of its referenced Actions are enabled on that
channel.

## Procedure-only Actions

By default, the AI agent can call any enabled Action on its own whenever the Action's
**When to use** matches. Sometimes you want the opposite: an Action the AI agent
should **never** reach for by itself, and only ever run as a deliberate step inside
a Procedure, for example a "process refund" Action you only want fired after the
refund Procedure's checks have passed.

Turn on **Only use in Procedures** in the Action's settings to enforce that. The
Action stays enabled and fully functional, but:

* The AI agent won't select it on its own judgment, so its **When to use** field is
  hidden (it no longer needs one).
* It runs **only** when a Procedure step references it with `@action_name`.

This keeps sensitive tools on rails: they can't fire outside the flow you
designed. See [Actions](https://chatbase.co/docs/user-guides/chatbot/actions/actions-overview.md#only-use-in-procedures)
for where to find the setting.

## Waiting on the customer

If a step calls an Action that needs user input (an account picker, a form, a
confirmation), the AI agent treats it as a **pause**, not a failure. It tells the
customer it's waiting, then stops. It resumes the same step once the customer
responds. It won't retry or jump to another Action.

## Troubleshooting

> [accordion] My Procedure never triggers
>
> Confirm it's **Active**, and that its trigger describes the customer's intent
> clearly and distinctly from other Procedures. Overlapping triggers can cause a
> different Procedure to win.

> [accordion] It works on the website but not on WhatsApp/another channel
>
> A referenced Action is likely unavailable on that channel, which drops the whole
> Procedure there. Enable every referenced Action on that channel.

> [accordion] Two things should happen at once
>
> Only one Procedure runs per turn. Combine the flow into a single Procedure (using
> branches) rather than expecting two Procedures to run together.

> [accordion] A Procedure-only Action never fires
>
> An Action with **Only use in Procedures** on runs only when a step references it
> with `@action_name`. Check that a Procedure references it, that the Procedure is
> **Active**, and that every Action in that Procedure is available on the channel.

> [accordion] The AI agent switched to a different flow partway through
>
> The customer's latest message matched another Procedure's trigger better, or they
> changed topics. Make each trigger describe a distinct situation, so triggers
> don't overlap.

> [accordion] The AI agent stopped and is waiting
>
> A step called an Action that needs the customer's input, such as a form or a
> confirmation. This is a pause, not a failure: the AI agent resumes the same step
> once the customer responds.

> [accordion] I can't set my Procedure to Active
>
> A step references an Action that doesn't exist or is disabled. The editor flags
> the reference. Fix or remove it, then enable the Procedure.

## Frequently asked questions

> [accordion] Can a customer leave a Procedure before it finishes?
>
> Yes. A Procedure isn't a lock. If the customer clearly switches topics, or sends a
> message that matches another Procedure's trigger, the AI agent can move to that
> Procedure on the next turn.

> [accordion] Can an Action used in a Procedure also run outside it?
>
> Yes, by default. The AI agent can also call the Action on its own whenever its
> **When to use** matches. Turn on **Only use in Procedures** to stop that.

> [accordion] Do Procedure-only Actions need a When to use?
>
> No. With **Only use in Procedures** on, the AI agent never decides when to call
> the Action, so its **When to use** field is hidden. The Procedure step that
> references the Action decides when it runs.


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