Workflow tool

The Workflow tool is how your v3 agent calls a workflow you've already built in the workflow editor. It's the most common tool type and the one you'll reach for whenever the agent needs to do something multi-step: hit an API, branch on data, collect structured input, run business logic.

When to use a Workflow tool

Use a workflow tool when:

• You need to hit an external API (order lookup, CRM update, payment).
• The action takes multiple steps with branching logic.
• You want the LLM to decide when to do the action, but the action itself is deterministic.
• You need to reuse the same logic from multiple agents.

Don't use a workflow tool when:

• The action is a single API call with no branching — that's coming soon as a Webhook tool, but for now wrap it in a one-step workflow.
• You just want to look something up in your KB — use the Knowledge Base tool.
• You want to hand off to a human — use Escalation tools.

Step 1: Build the workflow first

Before you can connect it as a tool, the workflow must exist. In Studio → Build → Flows, build the workflow you want the agent to be able to call. A workflow used as a tool typically:

• Receives input variables at the start (these become the tool's input arguments).
• Does whatever it needs to do (API calls, conditional branches, etc.).
• Ends with an Output node that returns a value (Success/Failure + the data the agent should read).

Any workflow can be exposed as a tool — there's no special "agent-callable" flag. But workflows designed 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, rich-media (cards, quick replies), and anything the agent needs to read downstream.
• 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: Open the Tools page

In your bot, go to AI Agent → Tools. Click Add Tool. Pick Workflow from the catalog.

The configuration drawer opens.

Step 3: Fill in name and description

Give your tool:

• A name that reads as a verb-first action: getOrderStatus, updateShippingAddress, bookAppointment.
• A description that tells the LLM exactly when to use it.

Good description:

"Look up the current shipment status for an order by order ID. Returns the shipment state (in_transit, delivered, etc.), tracking number, and estimated delivery date. Use this when the user asks about an order they've already placed."

Bad description:

"Order tool."

The LLM uses this description to decide whether to call your tool. Specific descriptions = reliable calls.

Step 4: Pick the target workflow

Switch to the Actions tab. You'll see a dropdown listing every workflow in this bot.

Pick the workflow you want to connect. This field is required — you can't save without it.

If you rename the workflow later, the tool keeps working — the link is by slug, not name.

Step 5: Define the input schema

The input schema tells the LLM what arguments to extract from the conversation when it calls your tool. This is JSON Schema:

{
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "description": "The customer's order ID, typically a 10-character alphanumeric string."
    }
  },
  "required": ["orderId"]
}

Best practices for input schema:

• Add a description to every property. The LLM reads these to know what to extract. "The customer's order ID" beats just naming the field orderId.
• Mark required inputs explicitly. Without required, the LLM may call the tool with missing arguments.
• Use enum when there's a fixed set. "status: pending | shipped | delivered" prevents the LLM from inventing values.
• Keep it small. Every input is one more thing the LLM has to extract correctly. Cut what's not strictly needed.
• Match field names to your workflow inputs. When the tool fires, these arguments are passed straight into the workflow's input variables.

Step 6: Define the output schema (optional but recommended)

The output schema describes what the workflow returns. The agent reads these values to compose its reply or to feed downstream tools.

{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "trackingNumber": { "type": "string" },
    "estimatedDelivery": { "type": "string" }
  }
}

The LLM uses this schema to interpret the response. Without it, your agent may misread the workflow's output.

Rich-media output: pick a card type

If your workflow emits cards (carousel of products, transaction list, order tracker, etc.), the SkillOutput node inside the workflow editor lets you pick a card type that shapes the expected variable format. The "View format" hint below the dropdown updates to show the exact JSON shape for the type you pick — both array-of-cards and single-object shapes are supported for the specialised types.

Available card sub-types:

Card type	What it renders
Default card	Generic card (title, subtitle, image, buttons). Accepts an array of card objects. The default selection 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 used for "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 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 when you just want a standard carousel; pick a specialised type when its native shape matches your data better and you want the renderer to apply type-specific styling and validation.

Leaving the card type unset is equivalent to Default card for backward compatibility — existing workflows continue to render as carousels.

Step 7: Add mocks (optional but useful)

The Mocks tab lets you stub the workflow's response while you're building. Drop in a sample success payload, and the Test tab will use it instead of firing the real workflow.

This is genuinely useful when:

• The real workflow hits a paid API or production data and you don't want test runs to count.
• The workflow isn't finished yet and you want to design the agent in parallel.
• You want to test the agent's handling of an edge-case response (e.g. a 404 or an empty result) without setting up real data.

Step 8: Test before saving

Switch to the Test tab. Provide sample input arguments. Click Run.

You should see:

• The exact request that was sent.
• The response (or mock).
• The parsed output the agent will see.

If something looks off — wrong field, missing data, unexpected type — fix it now. It's much easier to debug here than from a live conversation.

Step 9: Save

Click Save. The tool now appears on the Tools list. Any agent in this bot can use it automatically.

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

If this tool 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.

Best practices

• One workflow, one tool. Don't expose a single mega-workflow that branches on a "mode" argument. The LLM will pick the wrong mode. Build separate 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 Failure outputs. Make sure your workflow has a Failure path defined and that the failure payload tells the agent what went wrong (so it can apologize gracefully or fall back).
• Use mocks during development. They keep you out of production data and make tests reproducible.
• Document the tool in its description, not in your head. Someone else will tweak this bot in six months. Make the description self-explanatory.

Common pitfalls

Symptom	Likely cause
LLM calls the tool with empty arguments	Description doesn't make required inputs obvious. Tighten the description and mark fields required in schema.
LLM never calls the tool	Description doesn't match user phrasing. Add a Routing Logic rule, or rephrase the description with words your users actually use.
Tool fires but agent ignores the result	Output schema is missing or wrong. The LLM doesn't know how to read the response.
Tool fires twice in one turn	Two tool descriptions overlap. Sharpen them so each tool has a clear, distinct trigger.

Legacy reference

The legacy Call workflow doc covers similar ground for v2 bots. v3 uses the Tools UI shown above; the underlying concept (a workflow callable by the agent) is unchanged.