Workflow tool

A workflow tool is a workflow you've built, attached to an agent so it can call it. Whenever an agent needs to do something multi-step - hit an external API, read or write a database, branch on data, run business logic - you build that as a workflow and attach the workflow directly as a tool.

There's no separate "tool" object to author and no schema to hand-write: the workflow's input variables are the tool's inputs, its Output node is what the agent reads back, and its name plus the "When should the AI use this workflow?" description tell the agent when to call it.

Two kinds of workflow

When you click Create on the Workflows page, you pick one of two kinds. They're built and attached the same way - the difference is what they return:

Type	Returns	Use it for
Workflow	Data / a result the agent reads	Logic the agent calls as a tool - an API call, a database lookup, a record update, a calculation.
Rich media workflow	Rich media - cards, carousels, quick replies, or widgets	A visual reply the agent shows in chat - a product carousel, an order-status card, quick-reply chips.

Most of this page is about the first kind; rich media workflows get their own section below and their own Rich media workflows tab on the Workflows page.

When to use a workflow tool

Use one when:

• The agent needs to hit an external API or database (order lookup, CRM update, catalogue read, payment).
• The action takes multiple steps, or branches on data.
• You want the LLM to decide when to act, but the action itself should be deterministic.
• You want to reuse the same logic across several agents.

Reach for something else when:

• You just want to answer from documents - use the Knowledge Base tool.
• You want to hand off to a human - use Escalation tools.
• A fixed, multi-step procedure must run the same way every time as part of a longer journey - consider a multi agent.

Step 1: Build the workflow

In Studio → Build → Flows, build the workflow you want the agent to call. A workflow used as a tool typically:

• Receives input variables at the start - these are the arguments the agent fills when it calls the tool.
• Does its work (API calls, database reads/writes, conditional branches).
• Ends with an Output node that returns a value - Success/Failure plus the data the agent should read.

Any workflow can be attached as a tool - there's no special "agent-callable" flag. But workflows meant for agent use should be small, focused, and have a clear input → output contract.

Send Message nodes still deliver text bubbles

The "Output node ends the workflow" pattern is canonical, but Send Message nodes placed inside a workflow are also delivered to the user. The runtime captures their text bubbles and pushes them through alongside (or instead of) the Output node payload.

• Use the Output node for the canonical structured result and anything the agent needs to read downstream. (For replies built from cards or quick replies, use a rich media workflow instead.)
• Use Send Message nodes for one-off text bubbles the workflow wants to render directly - common in "informational" workflows that don't return a value the agent should branch on.

Gotcha - don't populate rich-media in both. If your Output node already returns cards or quick replies, do not also emit them from a Send Message node - the runtime ignores rich-media in the Send Message stream to avoid double-emit. Text-only Send Message bubbles always deliver.

Step 2: Name it and say when the AI should use it

Open the workflow's Edit workflow dialog and set the two fields that become the tool's contract for the agent:

• Workflow name - verb-first and task-shaped: getOrderStatus, getBikeDetails, bookAppointment. The agent references it by this name (e.g. @getOrderStatus).
• When should the AI use this workflow? - the description the agent reads to decide whether to call it. This is the highest-leverage field on the page. Say what the workflow returns and exactly when to call it (and when not):

✅ "Returns an order's current shipment status by order ID - state (in_transit / delivered), tracking number, and ETA. Use it when the user asks about an order they've already placed; not for new orders or returns."

❌ "Order tool." / "Call this when order data is needed."

The studio warns you about this in the field itself: vague descriptions cause the workflow to be skipped or run at the wrong time. See why the description is the most important field.

There's no separate input/output schema to author. The workflow's input variables are the arguments the agent extracts and fills, and its Output node is what the agent reads back. So:

• Name input variables clearly and describe them. "The customer's order ID" beats a bare orderId - the agent reads the variable to know what to extract.
• Keep the input list short. Every input is one more thing the agent has to get right.
• Return exactly what the agent needs from the Output node, in a clear shape - nothing more.

Step 3: Attach it to an agent

On the agent's profile, under Reasoning & Actions → Tools, click + Add tool and pick your workflow. That's the whole attach step - the agent can now call it, deciding when from the "When should the AI use this workflow?" text you wrote.

Attach the same workflow to as many agents as need it - tools are shared across the bot. Attaching a workflow to a specific agent also signals "this belongs to that agent's job," which helps routing send the right topics there.

Step 4: Test it

Before you rely on the tool:

1. Run the workflow in the flow editor with sample inputs and confirm the Output node returns what you expect - wrong field, missing data, or an unexpected shape is much easier to catch here than in a live chat.
2. Open the agent's Playground and confirm the agent calls the workflow at the right moment and reads its result correctly. Use View trace on the reply to see the call, the arguments it passed, and the data that came back.

Step 5 (optional): Make it deterministic with Routing Logic

If this workflow must fire for certain user messages (not "the LLM might call it"), add a Routing Logic rule. Example:

"If the user asks about an order's status, you must call the getOrderStatus tool before composing a reply. Do not answer from memory."

See Routing Logic.

Rich media workflows

A rich media workflow returns a visual reply - cards, carousels, quick replies, or widgets - that the agent shows directly in the chat, instead of data the agent reads. Create one with Create → Rich media workflow on the Workflows page; they live under the Rich media workflows tab.

You build, name, describe ("When should the AI use this workflow?"), and attach a rich media workflow exactly like a regular one (Steps 1-3) - the only difference is that it returns rich media. Pick the card type that matches your data; the editor's "View format" hint shows the exact JSON shape (both array-of-cards and single-object shapes are supported):

Card type	What it renders
Default card	Generic card (title, subtitle, image, buttons). Accepts an array of card objects. The default when you turn on Cards.
Transaction Status	Single transaction status card (success / failure / pending icon, amount, ref).
Order Tracker	Multi-step delivery / order timeline.
Contact Card	Name, phone, email, optional avatar - typically "your account manager is…" patterns.
Payment Receipt	Itemised receipt with totals and merchant info.
Account Details	Compact account summary card.
List	A vertical list of items with title / subtitle / optional action - different shape from a carousel of Default cards.
Slider	Range / value slider card for numeric input.
Product Card	E-commerce product (image, name, price, CTA).
Payment List With Button / Without Button	Itemised payment list with or without the pay-CTA at the bottom.
Transaction List With Multi Select / Single Select	A list of transactions the user can pick from.

Pick Default card for a standard carousel; pick a specialised type when its native shape matches your data and you want type-specific styling and validation. Leaving the card type unset is equivalent to Default card.

How the agent uses it:

• It's a tool call, not a description. Reference it in instructions by name, as a call - "Call @display_cart to show the cart", not "display the cart" - otherwise the model narrates the intent instead of rendering the media. See Referencing tools in prompts.
• For custom interactive UI beyond the built-in card types (forms, multi-step pickers, calculators), build a widget and return it from a rich media workflow.

Best practices

• One workflow, one tool. Don't build a single mega-workflow that branches on a "mode" argument - the LLM will pick the wrong mode. Build separate, focused workflows.
• Keep workflows fast. A tool call adds latency to the conversation. Aim for under ~2 seconds end-to-end; cache where you can.
• Always handle the Failure path. Make sure the workflow has a Failure output and that its payload tells the agent what went wrong, so the agent can recover or apologise gracefully instead of stalling.
• Write "When should the AI use this workflow?" for the model, not for yourself. Answer "what does it return, and when should you call it?" in plain language. Someone will tweak this bot in six months - make it self-explanatory.
• Name input variables clearly. They are the tool's input contract; clear names and descriptions are what let the agent fill them correctly.

Common pitfalls

Symptom	Likely cause
Agent calls the workflow with missing/empty inputs	Input variables aren't clearly named or described, or the "When should the AI use this workflow?" text doesn't make the required inputs obvious.
Agent never calls the workflow	The description doesn't match how users actually phrase things. Reword it, or add a Routing Logic rule.
Workflow fires but the agent ignores the result	The Output node doesn't return the data the agent needs, or returns it in a confusing shape.
Workflow fires twice in one turn	Two workflows' descriptions overlap. Sharpen each so its trigger is distinct.

Legacy reference

The legacy Call workflow doc covers similar ground for legacy-platform bots. On Nexus you attach a workflow directly as a tool as shown above; the underlying concept (a workflow the agent can call) is unchanged.