Workflows

A workflow chains your API tools into one step-by-step flow that the agent calls as a single tool. You decide the exact order, pass each step's response into the next, branch on the results, and control precisely what the agent gets back at the end.

Use a workflow when one customer request needs several dependable steps — the agent triggers it with the inputs, and the flow itself runs deterministically, the same way every time.

Our example: Balloon Bliss wants Bella to answer "what's the status of my order?" The flow looks up the order in the shop's order API, checks whether the total qualifies for free delivery (orders above 20 OMR in Muscat), and returns a clean answer either way. We'll build it as a workflow called check_order.

---

Where to Find It

Integrations → Workflows in the sidebar.

Each card shows the workflow's steps and an enable/disable toggle. Click New workflow to open the builder.

The Builder

The builder is a visual canvas. You add nodes from the toolbar, connect them, and configure each one in a side drawer.

Node types

Node	What it does
Start	Entry point. Holds the workflow's inputs — the parameters the agent fills when it calls the workflow.
Tool	Calls one of your API tools, with its inputs mapped from workflow inputs or previous steps.
Internal	Runs a built-in platform action mid-flow (e.g. handover, send media).
File	"Convert to File" — turns a base64 payload from a previous step into a downloadable file the agent can send.
Branch	If/else routing. Cases are checked top-to-bottom; the first match wins, otherwise the else path is taken.
Return	Ends the workflow with a message written for the agent — a clear result, not a raw data dump.
End	Plain terminal node for flows that don't need a custom return message.

---

Building check_order Step by Step

1. Name it and add the entry input

Type the name in the header — snake_case, like a tool name: check_order.

Click the Start node and add an input component: order_id. This is what the agent will ask the customer for. Steps reference it as {{input.order_id}}.

Then open Workflow settings (the gear next to the name) and write the Description — this is how the agent decides when to use the workflow, so make it concrete:

Check a Balloon Bliss order by order number and tell the customer the total, item count, and whether it qualifies for free Muscat delivery. Use when a customer asks about the status or delivery of an existing order.

tip

The description is required — Save won't submit without it.

2. Add the tool step

Click Tool in the toolbar and pick your API tool (here: order_status_lookup, which calls the Balloon Bliss order API).

The drawer shows the tool's inputs and an Available data panel with everything you can feed into them — entry inputs and customer attributes ($name, $phone, …). Drag a pill onto an input, or type the reference directly:

Here we map the tool's order_id input to {{input.order_id}}.

Referencing step outputs. Every step's response is available to later steps as {{steps.<step_id>.json.<path>}} — for example {{steps.step_1.json.total}}. Use Fetch sample in the drawer to run the tool once and browse its real response fields.

3. Branch on the result

Add a Branch node and one case:

• Field: steps.step_1.json.total
• Type: number
• Condition: ≥
• Compare to: 20

If the order total is 20 OMR or more, the case path fires (free delivery). Anything else takes the else path.

4. Write the Return messages

Add a Return node for each path. The return message is what the agent reads — write it as the answer, using placeholders:

Free delivery path (outcome free_delivery):

Order {{input.order_id}} is confirmed. It has {{steps.step_1.json.totalQuantity}} items and the total is {{steps.step_1.json.total}} OMR — it qualifies for FREE delivery across Muscat (orders above 20 OMR).

Else path (outcome delivery_fee_applies):

Order {{input.order_id}} found: {{steps.step_1.json.totalQuantity}} items, total {{steps.step_1.json.total}} OMR. A 2 OMR delivery fee applies for Muscat orders under 20 OMR — suggest a small add-on to reach free delivery.

Each Return also takes an optional outcome slug (the agent can key off it) and optional curated data fields.

5. Connect and save

Wire: Start → tool step → Branch, then each branch handle to its Return. The header shows live validation — valid means every issue is resolved (unmapped inputs, unreachable nodes, cycles). Hit Tidy to auto-arrange the canvas, then Save.

---

Assigning to an Agent

A workflow does nothing until you assign it

Saving a workflow doesn't expose it to any agent. If the agent never triggers your workflow, check this assignment first — it's the most common miss.

1. Go to Agents → (your agent) → Workflows
2. Toggle the workflow on

Don't also assign the workflow's tools

Workflow steps run their tools server-side — the tools themselves do not need to be assigned to the agent. If a tool should only ever run inside the flow (like order_status_lookup here), leave it unassigned on the agent's Tools tab so the agent can't call it directly and skip your branching logic. Only assign a tool directly when the agent should also use it on its own (like search_gift_addons for gift questions).

From the agent's point of view, check_order is now just another tool with one parameter (order_id). When Salim asks "what's the status of order 5?", Bella calls the workflow once and answers from its return message — she never sees the raw API response, the branching, or the delivery math.

Testing

Ask the assigned agent in the Playground (or your web chat) something that matches the description and confirm the reply uses the return message's facts. Here's Bella answering through check_order on the Balloon Bliss site:

---

Workflow Settings

The gear menu next to the workflow name:

• Description (required) — the agent's trigger criteria.
• Loose type matching in conditions — lets branch conditions compare "20" (string) with 20 (number) instead of failing on type.
• Require a verified customer phone number — gates the whole workflow behind OTP phone verification, same as the per-tool security option.

Best Practices

• One job per workflow. "Check an order" and "cancel an order" are two workflows — the agent picks better between narrowly-described tools.
• Return messages are the product. Spend your effort there: state the outcome plainly and include the numbers the agent should repeat.
• Branch for the customer-facing difference, not for every API status code. Two or three outcomes is usually plenty.
• Use Fetch sample before writing references — guessing JSON paths is the most common cause of empty placeholders.
• Names are snake_case and shown to the model — check_order beats workflow_1.

Troubleshooting

• Save does nothing — check the issues chip in the header, and make sure the Description in Workflow settings is filled.
• A placeholder comes out empty — the JSON path doesn't match the step's real response; verify with Fetch sample.
• The agent never calls the workflow — sharpen the description ("Use when a customer asks about…") and confirm it's assigned to the agent and enabled.
• The tool step fails on a new domain — external domains must be whitelisted; see the note in Creating API Tools.

Next Steps

• Creating API Tools — the building blocks workflows chain together
• Authentication for API Tools — attach credentials to the tools your steps call
• System Events — push events from your backend to the agent