> For the complete documentation index, see [llms.txt](https://docs.helvia.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helvia.ai/build/workflows.md).

# Workflows

Workflows are the building blocks of your agent. Each workflow is a visual graph that defines how your agent processes input and responds to users — step by step, node by node. An agent can contain many workflows, each responsible for a different part of its functionality. Think of them as modular pieces of logic you compose together.

Navigate to **Designer > AI Workflows** to build, configure, and manage your workflows and everything connected to them.

### What Is a Workflow

A workflow is a directed graph made up of two elements:

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-circle-nodes">:circle-nodes:</i></h4><h4>Nodes</h4></td><td>Building blocks that each perform a discrete action or logic step</td></tr><tr><td><h4><i class="fa-arrow-right-long">:arrow-right-long:</i></h4><h4>Edges</h4></td><td>The connections between nodes that define the execution sequence</td></tr></tbody></table>

Your agent executes the graph step by step, starting from the Start node and chaining through each connected node. A workflow ends when it reaches a node with no outgoing edge or a Redirect node that transfers execution to another workflow.

<div data-with-frame="true"><figure><img src="/files/hDa3tcUmBZofo8BwPPnv" alt=""><figcaption></figcaption></figure></div>

#### Types of Workflows

When you create a new workflow, you select one of four types. Each type comes with a preconfigured template and may enable specialized nodes.

{% tabs %}
{% tab title="Generic" %}
The standard workflow type. Build custom conversation logic using any combination of message, prompt, action, and logic nodes.
{% endtab %}

{% tab title="Survey" %}
Designed to collect structured information from users step by step. Use for surveys, applications, or any scenario requiring sequential data collection.
{% endtab %}

{% tab title="User Feedback" %}
Collects user feedback about the conversation. Keep the default tags so results appear in Observatory analytics.
{% endtab %}

{% tab title="LiveChat" %}
Facilitates handoff to a human agent for real-time communication. Activate LiveChat from **Designer > Plugins** before use.
{% endtab %}
{% endtabs %}

### Creating a Workflow

{% stepper %}
{% step %}

#### Navigate to the Workflows Hub

Go to **Designer > AI Workflows > Flows**
{% endstep %}

{% step %}

#### Add a New Workflow

Click the **Add Flow** button
{% endstep %}

{% step %}

#### Configure the Workflow

Enter a descriptive name (e.g., `Order Tracking` or `Greeting`) and select the workflow type.
{% endstep %}

{% step %}

#### Create the Workflow

Select **Create flow**. The new workflow is added to the agent and you can now start building your logic in the canvas.
{% endstep %}
{% endstepper %}

### Managing a Workflow

You can manage a workflow using the Action column buttons.

<table><thead><tr><th width="96.5">Icon</th><th width="144">Function</th><th>Description</th></tr></thead><tbody><tr><td><i class="fa-pen">:pen:</i></td><td>Edit</td><td>Open the workflow on the canvas</td></tr><tr><td><i class="fa-trash-can">:trash-can:</i></td><td>Delete</td><td>Permanently remove the workflow</td></tr><tr><td><i class="fa-copy">:copy:</i></td><td>Clone</td><td>Duplicate the workflow into the same or a different agent</td></tr><tr><td><i class="fa-eye">:eye:</i></td><td>Preview</td><td>Run the workflow in isolation</td></tr><tr><td><i class="fa-star" style="color:$warning;">:star:</i></td><td>Favourite</td><td>Set this workflow as the default for the flow preview</td></tr></tbody></table>

{% hint style="danger" %}
Deleting a workflow is permanent. Make sure you no longer need it before you select **Delete**.&#x20;
{% endhint %}

### Editing a Workflow

Use the [Canvas](/build/canvas.md) to design your workflow visually. Simply drag and drop nodes, then connect them to define the execution path. To edit a workflow, either select it in **Designer > AI Workflows > Flows** or click the respective edit action button.

The canvas enforces various rules to keep your workflows valid. For example:

* Every node must be connected; you cannot leave detached nodes in the workflow
* Only valid connections between compatible node types are allowed
* A node cannot have multiple outgoing edges to different children (unless using a control flow node)

{% hint style="info" %}
If you try to exit the canvas with errors, you get a warning highlighting the issues. You need to fix all errors before saving a workflow.
{% endhint %}

### The Workflow Lifecycle

Each workflow executes according to the visual path established in the graph.

{% stepper %}
{% step %}

#### Start node

Whenever a workflow is triggered the execution flow begins from the Start node. There is only one Start node per workflow, it cannot be removed and it is automatically created for every new workflow.
{% endstep %}

{% step %}

#### Step-by-Step Execution

The workflow chains through nodes one at a time, following the edge direction. At each step, the next node is determined by the outcome of the current one. If a node branches into multiple outgoing paths, the workflow follows a single path based on the result. The result is an execution flow that adapts to each conversation rather than following a fixed sequence.
{% endstep %}

{% step %}

#### End or Redirect

The workflow concludes automatically upon reaching either a node with no further outgoing paths or a Redirect node, which hands off the execution to another workflow.
{% endstep %}
{% endstepper %}

A single agent response can span multiple workflows chained through Redirect nodes. The response completes when the last workflow in the chain reaches a terminal node.

### How the Agent Picks a Workflow

Every agent comes with built-in triggers that decide which workflow runs at a given moment:&#x20;

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-type="content-ref"></th></tr></thead><tbody><tr><td><h4>Start Workflow</h4></td><td>The initial workflow triggered the moment a user begins a new conversation.</td><td></td></tr><tr><td><h4>Default Workflow</h4></td><td>The main workflow that triggers automatically whenever a new message pops up from a user in the chat interface.</td><td></td></tr><tr><td><h4>Interrupts</h4></td><td>Keyword rules that redirect to a target workflow as soon as a user message matches</td><td></td></tr></tbody></table>

Each one targets a workflow you have built, but they differ in what triggers them, where they apply, and where you configure them:

<table data-search="false"><thead><tr><th></th><th>Start Workflow</th><th>Default Workflow</th><th>Interrupts</th></tr></thead><tbody><tr><td><strong>Purpose</strong></td><td>Greets the user when a conversation begins</td><td>Responds to any new user message</td><td>Redirects the conversation when a keyword matches</td></tr><tr><td><strong>Trigger</strong></td><td>Conversation opens (before any user input)</td><td>User input</td><td>User message matches an Interrupt keyword</td></tr><tr><td><strong>Scope</strong></td><td>Per deployment</td><td>Global (applies to all deployments)</td><td>Agent-wide</td></tr><tr><td><strong>Where to set</strong></td><td>Deployment settings</td><td><strong>Designer > AI Workflows > Default Flow</strong></td><td><strong>Designer > AI Workflows > Interrupts</strong></td></tr><tr><td><strong>Availability</strong></td><td>Depends on the channel</td><td>All channels</td><td>Modern agents only</td></tr></tbody></table>

### Start Workflow

The start workflow is the initial workflow triggered the moment a user begins a new conversation. It defines the agent's first impression, allowing you to establish context or gather information before the main logic takes over.

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-message-lines">:message-lines:</i> </h4><h4>Keep It Short</h4></td><td>Orient the user in 1–2 messages, not overwhelm them with information</td></tr><tr><td><h4><i class="fa-mobile-screen">:mobile-screen:</i> </h4><h4>Match the Channel</h4></td><td>A Webchat start workflow can be more visual, while a Viber start workflow should stay text-focused</td></tr><tr><td><h4><i class="fa-tag">:tag:</i></h4><h4>Descriptive Name</h4></td><td>Use names like <code>Welcome - EN</code> or <code>Onboarding - Support</code> so they are easy to identify</td></tr></tbody></table>

#### Understanding the Start Workflow

This workflow is triggered when the user first accesses the agent, such as when they open a webchat interface in their browser. Because this workflow can be any flow you have built, it offers a high degree of flexibility for personalizing the user experience.

Common uses for a start workflow include:

* Send a personalized welcome message
* Set specific variables to track user context
* Ask for initial feedback or user preferences
* Introduces the agent's capabilities

{% hint style="info" %}
The start workflow is set per deployment, not globally. Different deployments can trigger different workflows, even on the same channel.
{% endhint %}

#### Channel Availability

The availability of the start workflow varies depending on the specific channel you choose for deployment. Some channels do not support the concept of a 'new conversation' session, while others restrict introductory messages to a one-time initial interaction.

<table data-search="false"><thead><tr><th width="206">Channel</th><th width="216.75">Start Workflow Available</th></tr></thead><tbody><tr><td><i class="fa-globe">:globe:</i>  Webchat</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span> Yes</td></tr><tr><td><i class="fa-code">:code:</i>  API</td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr><tr><td><i class="fa-user-group">:user-group:</i>  Microsoft Teams</td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr><tr><td><i class="fa-slack">:slack:</i>  Slack</td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr><tr><td><i class="fa-whatsapp">:whatsapp:</i>  WhatsApp</td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr><tr><td><i class="fa-viber">:viber:</i>  Viber</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span> Yes</td></tr><tr><td><i class="fa-facebook-messenger">:facebook-messenger:</i>  Messenger</td><td><span data-gb-custom-inline data-tag="emoji" data-code="2705">✅</span> Yes</td></tr><tr><td><i class="fa-instagram">:instagram:</i>  Instagram </td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr><tr><td><i class="fa-unity">:unity:</i>  Unity </td><td><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span> No</td></tr></tbody></table>

#### Configure a Start Workflow

You choose the start workflow when you create a deployment in Designer. If you need to update the initial experience, you can change the assigned workflow at any time from the deployment configuration settings.

{% stepper %}
{% step %}

#### Create a Workflow

Go to **Designer > AI Workflows > Flows** and build the workflow you want to use as the start flow. A common pattern is a welcome message followed by quick-reply options.
{% endstep %}

{% step %}

#### Open the Deployment

Go to **Designer > Deployments** and select the deployment you want to configure or create a new one.
{% endstep %}

{% step %}

#### Select the Workflow

<div data-with-frame="true"><figure><img src="/files/w8E9Mj05kfs7dxZI6uAg" alt=""><figcaption></figcaption></figure></div>

Find the **Flow** dropdown (location and name may vary by channel) and select your workflow.
{% endstep %}

{% step %}

#### Save

Click **Save Changes** (or **Create Deployment** if creating a new one).
{% endstep %}
{% endstepper %}

### Default Workflow

The default workflow is the main starting point of your agent. It is the central sequence that triggers automatically whenever a new message is sent to the agent, ensuring a responsive interaction for every user query.

To configure the default workflow, go to **Designer > AI Workflows > Default Flow**.&#x20;

<table data-card-size="large" data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th></tr></thead><tbody><tr><td><h4><i class="fa-shuffle">:shuffle:</i> </h4><h4>Don't Forget the Redirect</h4></td><td>Ensure the workflow ends with a Redirect; without this, the Agent AI won't trigger to process the user's response</td></tr><tr><td><h4><i class="fa-brackets-curly">:brackets-curly:</i> </h4><h4>Leverage Variables</h4></td><td>Use variables like <code>{{user.LastName}}</code> or <code>{{session_topic}}</code> within your response to prove the agent is "listening" rather than just reciting a script</td></tr><tr><td><h4><i class="fa-power-off">:power-off:</i> </h4><h4>Offline Switch</h4></td><td>Use a custom message with a static notification to inform users if and when the agent is available or is undergoing maintenance</td></tr><tr><td><h4><i class="fa-compress">:compress:</i> </h4><h4>Optimize for Brevity</h4></td><td>The default workflow should be concise. Let the agent decide how it wants to answer</td></tr></tbody></table>

#### Understanding the Default Workflow

When a user sends a message, the default workflow is responsible for handling the agent's response. It is defined as a chain of responses that are executed sequentially and you can configure each response separately by selecting one of the four types.

{% tabs %}
{% tab title="Message" %}
Display customized messages to your users with full support for rich formatting, including emojis and lists. You can personalize the response by including agent-specific variables such as user metadata or the current date and time.&#x20;

For granular control, you can enable or disable thumb ratings for specific messages, allowing you to override your global agent settings.
{% endtab %}

{% tab title="Redirect" %}
Redirect the control to the selected workflow. This is typically your main workflow that orchestrates your agent behavior. You can only redirect to Generic, LiveChat or Survey type workflows.

{% hint style="info" %}
This is only available as the last response item in your default workflow sequence
{% endhint %}
{% endtab %}

{% tab title="Feedback" %}
Redirect the control to the selected User Feedback workflow. For any other type of workflow, use the Redirect response. You can set the probability to ask for feedback (0-100%).
{% endtab %}

{% tab title="Variable" %}
Define variables to manage your agent’s behavior. Select an existing variable or create a new one by typing the name and then assign a new value for the variable.&#x20;

You can also choose how the data is stored: as a session variable for the current conversation or as a contact variable for long-term storage.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
There is only one default workflow allowed for each agent to maintain a clear and consistent logic path.
{% endhint %}

#### Build a Default Workflow

{% stepper %}
{% step %}

#### Navigate to the Default Flow Page

Go to **Designer > AI Workflows > Default Flow**.
{% endstep %}

{% step %}

#### Select the Language

Use the language dropdown to choose which language you are configuring.&#x20;

{% hint style="info" %}
Each language has its own independent Default Flow
{% endhint %}
{% endstep %}

{% step %}

#### Add a Response

Select **Add Agent Response** above or below the chain. Select the response type (Message, Redirect, Feedback, or Variable) and fill in the fields.
{% endstep %}

{% step %}

#### Chain Additional Responses

Click **Add Agent Response** again to append more responses. They execute top-to-bottom in the order shown.
{% endstep %}

{% step %}

#### Remove Responses

Select the <i class="fa-trash-can">:trash-can:</i> icon next to any response block to remove it from the chain. The remaining responses shift up automatically.

{% hint style="danger" %}
&#x20;Deleting a response is immediate. There is no confirmation dialog.
{% endhint %}
{% endstep %}

{% step %}

#### Save

Changes save automatically as you edit each response block.
{% endstep %}
{% endstepper %}

### Interrupts

An Interrupt redirects the conversation to a target workflow when a user message matches a trigger keyword. Use them for global escape phrases like `cancel`, `start over`, or `talk to a human` that should work no matter where the user is in a conversation.

To configure interrupts, go to **Designer > AI Workflows > Interrupts**.

{% hint style="info" %}
Interrupts are available on modern agents only.
{% endhint %}

#### How Interrupts Work

You define an Interrupt by pairing one target workflow with a list of trigger keywords. When a user message arrives, the agent compares it against every keyword in every Interrupt before any other LLM step runs. If a keyword matches, the conversation jumps to that Interrupt's target workflow.

Matching is controlled by two agent-level settings that apply to every Interrupt: a similarity algorithm and a threshold.

{% tabs %}
{% tab title="Exact Match" %}
The user message must equal a keyword exactly. The threshold is ignored. Best for short, unambiguous commands like `cancel` or `stop`.
{% endtab %}

{% tab title="Jaro Winkler" %}
A fuzzy similarity algorithm tuned for short strings and common prefixes. Use the threshold to tolerate typos and minor variations (`1` is exact, `0` accepts anything).
{% endtab %}

{% tab title="Damerau Levenshtein" %}
A fuzzy similarity algorithm that counts character edits and transpositions. Use the threshold for tolerant matching of phrases or longer keywords (`1` is exact, `0` accepts anything).
{% endtab %}
{% endtabs %}

Toggle **Enable Interrupts** off to suspend matching across the whole agent without losing the keyword lists.&#x20;

<div data-with-frame="true"><figure><img src="/files/6urNpFVTKMoD6780EXqK" alt="" width="341"><figcaption></figcaption></figure></div>

A few rules to keep in mind:

* Each workflow can be the target of only one Interrupt
* A keyword can appear in only one Interrupt; duplicates are rejected on save
* Deleting a workflow automatically removes any Interrupt that targeted it

#### Create an Interrupt

{% stepper %}
{% step %}

#### Open the Interrupts Page

Go to **Designer > AI Workflows > Interrupts** and select **Create Interrupt**.
{% endstep %}

{% step %}

#### Pick a Target Workflow

Use the **Select Flow** dropdown to choose the workflow this Interrupt redirects to. Workflows that already have an Interrupt are not included here.
{% endstep %}

{% step %}

#### Add Keywords

Type a keyword and select **Add Keyword**, or use **Import from CSV** to load a batch from a file. Imported lists are deduplicated automatically against the keywords already in use by other Interrupts.

<details>

<summary><strong>CSV format</strong></summary>

The file must have a header row with a single column named `keywords` and one keyword per row:

```csv
keywords
cancel
start over
talk to a human
```

Duplicates within the current Interrupt are removed silently. Keywords already used by other Interrupts trigger a warning and are skipped.

</details>
{% endstep %}

{% step %}

#### Save

Select **Save Changes**. The Interrupt is now active for any conversation handled by the agent.
{% endstep %}
{% endstepper %}

#### Manage an Interrupt

Each row in the Interrupts table has edit and delete actions. Edit lets you change the target workflow or update the keyword list. Delete removes the Interrupt entirely. Inside the editor, **Delete All** clears the keyword list without removing the Interrupt itself.

### Workflows as Nodes

The Redirect node allows you to trigger a workflow from within another workflow, effectively turning complex sequences into modular "building blocks." This architectural approach is essential for building scalable and maintainable agents.

For example, imagine you have a main routing workflow that acts as a switchboard. Instead of building every single response in one place, you use Redirect nodes to send the user to specialized flows:

* Main Workflow $$→$$ User asks about a package $$→$$ Redirect to Order Tracking Flow
* Main Workflow $$→$$ User asks to return an item $$→$$ Redirect to Returns & Refunds Flow
* Main Workflow $$→$$ User requests a human $$→$$ Redirect to Live Support Flow

### Best Practices

* **Keep workflows focused:** each workflow should handle one task or conversation path, not the entire agent logic
* **Name descriptively:** use names like `Order Tracking` or `Password Reset` instead of `Flow 1` or `Test`
* **Set a default workflow:** always configure a default workflow to handle unrecognized input gracefully
* **Match the channel:** a Webchat starting workflow can be more visual, while a Viber starting workflow should stay text-focused
* **Document your workflow:** Sticky notes are available in the canvas sidebar. They are useful for documenting and organizing a workflow and facilitating collaboration between team members.&#x20;

{% hint style="success" %}
You now understand how to create, manage, and connect workflows to build your agent's conversational logic.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.helvia.ai/build/workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.