Actions overview

An action is a tool you give your agent. Where the agent's knowledge lets it answer questions, actions let it do things — look up an order over your API, show an interactive widget, capture a lead, search the web, or call a connected service like Shopify or Stripe. The agent decides when to use each action from its “when to use” description, calls it with the inputs it collected from the customer, and uses the result in its reply.

How an action gets triggered

Every enabled action is handed to the AI model as a function‑calling tool (actionService.toolDefs). For each one, the model receives three things:

{ name: a.name,                 // e.g. "go_to_pricing"
  description: a.description,    // your "when to use" text
  parameters: <input schema> }  // the inputs + their descriptions

Then, on every turn, the model decides whether to call a tool by weighing all of:

1. 1The description — the biggest lever you control ("when to use").
2. 2The action name — go_to_pricing is itself a strong hint; action_7 wouldn't be.
3. 3The parameter descriptions — e.g. an input "order_id — the customer's order number" tells it when it has what it needs.
4. 4The customer's actual message + the conversation so far.
5. 5The agent's system prompt (general instructions/persona).

So it's not purely the description, and importantly it's not keyword matching — the model makes a semantic judgment. You don't have to list every literal phrase; you describe the intent, and it generalizes (someone saying "what'll this run me?" still matches a pricing description even though they never said "pricing").

What that means practically

• A vague description like "Show the X widget" gives the model nothing to decide on → it fires unpredictably (or never).
• A good description states the situations/intents that should trigger it. Listing a few example phrasings helps (it anchors the model), but you're giving examples of intent, not an exact-match list.
• Name + inputs reinforce it, so a clear name and well‑described inputs also improve reliability.

Actions vs. Skills

Skills are written playbooks (instructions) injected into the agent's prompt — they teach it how to handle a situation, and can call APIs through a generic request tool. Actions are structured tools with typed inputs the agent calls directly. They work hand in hand: a skill can describe a workflow and rely on actions (or the built-in request tool) to carry out the steps. See Skills overview.

Types of action

Run mode: automatic vs. confirm

Every action runs either automatically or asks the user to confirm first. Use confirm for anything that changes data — cancelling an order, updating a profile, charging a card — so the customer approves before it happens. Read-only lookups can run automatically.

Connect a service

Connector actions call a third-party API. Add the connector from the Actions gallery, then set its credentials under Settings → Integrations so the agent can authenticate. Without credentials the action returns a clear auth error rather than failing silently.

Hand off to a human

Add a Send to Help Desk action (a custom action type) so the agent can open a ticket in your Help Desk when it can't resolve something itself — collecting name, email, and the question, then routing it to your team.

What's next