Workflows and Agents

A workflow is the runtime definition of your assistant. It describes where messages and events enter, which AI agent handles them, which tools that agent may use, and how the run ends. Every conversation your chatbot has, every scheduled data job, and every channel reply is a workflow execution.

You build and manage workflows on the Workflow page in the studio. This guide covers the whole page: the visual designer, agent configuration and budgets, the AI Assistant, workflow settings, schedules, the Setup tab, and YAML export and import for advanced users.

What a workflow is made of

A workflow is a graph of states. Execution starts at one state and follows labeled transitions until it reaches an end state.

Building block	What it does
Trigger states	Entry points. A channel trigger (Instagram, Telegram, email, and so on) starts a run when a message arrives. Other triggers include the Conversation API (studio and portal chat), webhooks, HTTPS listeners, schedules, and customer signups.
Agent states	The AI worker. An agent runs a reason-and-act loop: it reads the conversation, calls tools, and produces an answer, all within a budget of turns, tokens, and time.
Tool nodes	Capabilities you attach to an agent, such as knowledge base search, calendar booking, or Square invoicing. See the Agent tool reference.
Step and output nodes	Deterministic steps that run a single handler, and output nodes that deliver a result to a channel or an API caller.
Control flow	If/Else, Switch, Loop, While, Fork, Merge, Delay, Callback, Guardrail, and Saga nodes for branching and orchestration.
Succeed and Fail	Terminal states. Succeed marks the run completed; Fail marks it failed and records an error message.

A typical chatbot workflow is short: a channel trigger, one agent with tools, and a Succeed and Fail pair. Data pipelines instead chain a schedule trigger into data nodes with no agent at all (see Collections).

The Workflow page

Open Workflow in the navigation. The page has one tab strip:

Tab	What it shows
Workflow recipes	A gallery of prebuilt workflow templates and starter bundles. This is the default landing view. See Recipes.
Connectors	Connect and manage external systems. See Connectors.
Workflow	The visual designer canvas for the selected workflow.
Tasks	Reusable conversational tasks assigned to customers.
Setup	The organization's front-desk wiring: default workflows, follow-up cadence, and onboarding journey tasks. See The Setup tab.

In the designer view, a panel on the right lists the project's workflows. Click a workflow to open it, use New workflow to create an empty one, and use the trash button to delete one. The workflow marked Default is the one chat surfaces fall back to when nothing else is selected.

The toolbar above the canvas has five buttons:

• Wizard: a guided, checkbox-based setup that builds a front desk workflow from your choices of channels and tools, then walks you through connecting the required accounts and knowledge base.
• Export: downloads the current workflow as a .yaml file. See Workflow YAML.
• Import: creates a new workflow from a YAML file, validated on upload.
• Edit Workflow: opens the Workflow Settings modal (described below).
• Save workflow: persists your changes. Canvas edits are drafts until you save. If you switch away with unsaved edits, a dialog asks whether to save or discard them.

The designer canvas

The canvas is an infinite plane, similar to a whiteboard tool like Miro. Your workflow can grow in any direction; you move the view, not the page.

Moving around

• Pan: click and drag any empty part of the background. The middle mouse button pans from anywhere, even over a node.
• Mouse wheel and trackpad: scrolling pans the plane in any direction.
• Zoom: hold Ctrl (Cmd on Mac) while scrolling to zoom toward the cursor. The bottom-right control cluster also has Zoom out and Zoom in buttons with the current zoom percentage between them. Zoom ranges from 30% to 200%.
• Center workflow: the crosshair button in the bottom-right cluster pans the view so the whole workflow sits in the middle. The canvas also opens with the workflow centered.

The palette

A floating toolbox on the left edge holds every node type, grouped behind icon buttons. Click a group icon to open its list, then click an item to drop that node at the center of your current view.

Group	Nodes
Task Nodes	Agent (Reason-Act), Step (Deterministic), Tool Call, Customer Task
Triggers & Listeners	Customer Signup Trigger, Conversation API Trigger, HTTPS Listener, Webhook Trigger, Schedule Trigger, Message Bus Listener, Callback Trigger, plus a trigger entry for each connected channel plugin
Data & Memory	Data Sync (source to collection), Collection (read / write), Vault (agent notes)
Tools & Connectors	Knowledge Base, Deep Research, MCP Server Connector, MQ Subscriber, Message Bus Publisher, plus tools from your connected providers
Control Flow	If / Else, Switch (N-Way), Loop (For Each), While Loop, Fork (Parallel), Merge (Join), Delay, Callback (Wait), Guardrail, Saga
Output & End States	Output (Deliver), Human In The Loop, Succeed, Fail

Below the groups sits the organize button (a sparkles icon labeled "Auto-layout nodes"). It arranges the whole graph into tidy left-to-right layers based on the connections, so you never have to untangle a crowded diagram by hand.

Connecting nodes

Every node has one input handle on its left edge and one or more labeled output handles on its right edge. The labels are the transitions that node type supports:

Node type	Output handles
Task, Step, Output	next, catch
Agent	next, catch, plus a tool handle on the bottom edge
If / Else	then, else
Switch	case1, case2, default
While	body, next
Human In The Loop	approve, reject
Guardrail	pass, fail
Callback (Wait)	next, timeout
Fork	out, merge, next
Succeed, Fail	none (terminal)

To connect two nodes:

1. Press and hold an output handle on the source node. A dashed preview line follows your cursor.
2. Drag onto the target node and release. The transition is created and its label is drawn on the edge.

Click an edge to select it, then press Delete or Backspace, or use the Delete selected link button that appears in the bottom-right cluster. Dragging a new connection from a single-target handle (such as next) replaces the previous one automatically.

The success and fail branches on agents

Agent nodes carry a built-in success or fail condition:

• The next transition is taken only when the agent finishes its work and produces a final answer. The canvas draws this edge in green, labeled on success, when it points at a Succeed node.
• The catch transition is the error path. It is taken when the agent runs out of turns or time, never produces an answer, or hits an error. The canvas draws it as a rose dashed edge labeled on fail.

Point the catch handle at a Fail node to make an unhandled conversation end as a visibly failed run, with the Fail node's error message recorded. You can also route catch to any other state, for example a step that files a note or alerts a human. If an agent has no catch transition and fails, the whole run fails with the underlying error.

Tool connections (the purple dashed edges from the agent's bottom tool handle) are not execution steps. They attach capabilities the agent may call at its own discretion. See the Agent tool reference.

Editing a node

Each node card shows its name, a type badge, and badges for Entry (a callable entry point) and Start (the default start state). Hover a node for two buttons in its corner:

• The gear opens the right editor for that node: the Node Settings inspector for most nodes, the agent profile modal for agent nodes, and the schedule editor for Schedule Trigger nodes.
• The trash deletes the node and its connections.

The Node Settings inspector lets you rename the node, mark it as the default start state, mark trigger nodes as callable entry points, and configure type-specific settings such as the connector instance, the knowledge base and folders to search, delay durations, and branch conditions.

Agent profiles and budgets

Clicking the gear on an agent node opens the Configure agent settings modal, with two tabs.

Profile holds the agent's persona:

• Agent name and Goal.
• Identity: who the agent is. This persona is injected at the start of every conversation.
• Response guidelines: formatting, style, and behavioral constraints applied to every response.
• Response recipe: a preset tone (Conversational Concierge, Consultative Sales, Scheduling Concierge, Empathetic Support, Formal Professional, Technical Specialist, or Grounded Knowledge Mode) that fills in a matching system prompt.
• System prompt: the full instructions. Edit freely, or click Use recipe prompt to reset to the selected recipe.
• Effort Level: five presets (Minimal through Maximum) that set the budget fields in one click.
• Connected Tools: a read-only list of the tools attached through the diagram.

Budget controls how much work one execution may spend:

Field	Meaning	Default when unset
Max turns	Reason-and-act loop iterations before the agent must produce a final answer (1 to 50)	5
Max tokens	Output tokens the agent can generate across all turns (256 to 128,000)	16,384
Timeout (ms)	Wall-clock time before the agent is stopped (5 seconds to 10 minutes)	120,000 (2 minutes)

The effort presets map to these values, from Minimal (3 turns, 4K tokens, 30 seconds) to Maximum (50 turns, 64K tokens, 10 minutes).

When a budget runs out, the agent stops with a reason (out of turns, timed out, or no answer produced) and the run takes the catch transition, the fail branch described above. Budgets protect you from runaway conversations and runaway costs; see Billing and Credits.

The AI Assistant

You do not have to build workflows by hand. The round blue button in the bottom-left corner of the canvas opens the AI Assistant, a full-height panel over the canvas.

1. Type what you want in plain language, for example "add a fail branch that files a note when the agent can't answer" or "add Telegram as a second channel".
2. Press Enter to send (Shift+Enter inserts a newline). While the assistant works, its reply shows a progress plan with step-by-step checkmarks.
3. The change is applied directly to the workflow on the canvas, and the reply includes a What changed log listing each edit, tagged as added, removed, or modified, with the affected node or setting named.

The panel shows the workflow's entire conversation history, not just the current session: every past request, reply, and change log is persisted with the workflow, so you can always trace how the workflow got its current shape. If a requested change needs a connector that is not set up yet, the setup wizard opens so you can bind one.

Workflow Settings (Edit Workflow)

The Edit Workflow button opens the Workflow Settings modal. It gathers the workflow-level options in one place:

• Workflow name, plus the read-only Workflow ID (useful for API calls; see API and Integrations).
• Default workflow for this project: chat surfaces fall back to the default workflow when nothing is selected. Only one workflow per project can be the default; checking it here clears the flag on the others.
• Narrative: the business story behind the workflow, saved with its definition.
• Channels: checkboxes for where customers reach this workflow. Web enables the embeddable chat iframe (the snippet lives under Integrations). Below it, every messaging, email, or social connector in the project appears as its own checkbox. Checking a channel writes a trigger node into the diagram and hands the agent that channel's reply tool, so the agent can answer on the same channel the message came from. Unchecking removes them again.
• Tools: checkboxes for the agent's capabilities. The core tools are Knowledge base search, Deep research, Book appointments, Quotes & invoices, Invoice status, Customer lookup, Customer creation, Knowledge notes, Follow-ups, and Send customer task. Connected tool providers, such as Google Calendar or Google Sheets, appear as additional checkboxes. Tools attach to the agent node, so the workflow needs an agent before you can check them.
• Customer access: by default, portal customers see this workflow only when they are assigned to it (manage assignments on the workspace Customers page). Check Available to every portal customer to let first-time and unassigned customers chat with it without waiting to be assigned.
• Starter Prompts: up to four suggestion cards shown when users open the chatbot. Leave a field empty to keep its default.
• Chat memory folder: the knowledge base folder where this chatbot files its conversation abstracts and memory notes. The folder is created in the project's default knowledge base if it does not exist. Leave it empty to keep the folder set by a Vault node on the canvas, or the built-in "Vault" folder. See Knowledge Base.

Click Save changes to apply. Channel and tool changes rewrite the diagram immediately.

Schedules

Workflows can run on a clock instead of waiting for a message.

1. Add a Schedule Trigger from the Triggers & Listeners palette group. A schedule is created for it automatically.
2. Click the node's gear to open the Schedule Trigger editor.
3. Choose a Mode:
   • Interval: run every N minutes.
   • Daily: run at a specific time of day.
   • Cron: a cron expression for anything else, such as weekdays only.
4. Set the Timezone (for example America/New_York), an optional Trigger message passed into the run as its input, and the Enabled checkbox.
5. Click Done, then save the workflow.

Remove schedule config deletes the schedule; deleting the trigger node removes its schedule too. A workflow can hold several schedule triggers, each starting a different entry state on its own cadence. The data recipes are built exactly this way; see Recipes.

The Setup tab

The Setup tab holds the organization's front-desk wiring: which workflows handle new business by default, how quickly quiet leads, waiting quotes, and unpaid invoices get chased, and which onboarding tasks agents send to new customers. The Faberiq starter bundle fills all of it in on install, wherever you have not already chosen values.

Default workflows

Two selects name the default front desk workflow and the default follow-up workflow for the organization.

Follow-up cadence

An enable/disable toggle plus per-stage timing controls when a contact is due a follow-up:

Setting	Meaning	Default
Lead follow-up after (days)	Days a lead stays quiet before it gets a nudge	3
Quote follow-up after (days)	Days a sent quote waits before it is followed up	3
Invoice follow-up after (days)	Days an invoice stays unpaid before a payment reminder	5
Max follow-ups per run	Cap on candidates handled in one run	25

Customers whose journey is marked Completed or Lost on their customer page are never contacted. The cadence feeds the followups.list tool the Follow-up Agent recipe runs on; see the Agent tool reference.

Onboarding journey tasks

Every published task appears here with an on/off toggle for agents. Enabled tasks are ordered, and agents send them in that order during onboarding, so this is where you control whether, say, the NDA or Terms & Conditions step is part of the standard flow. Agents read the list through the frontdesk.config tool and hand tasks out with customer.task.send.

Workflow YAML: Export and Import (advanced)

The Export button in the designer toolbar downloads the current workflow as a .yaml file, and Import creates a new workflow from a YAML file, validated on upload (an invalid document is rejected with the parse error). The format is the same workflow: document that recipes use, so an exported file can be re-imported later, shared with another project, or kept as a backup.

The important parts of the document:

workflow:
  name: "My workflow"
  narrative: "What this workflow is for."
  agents:
    - id: "agent-front-desk"
      name: "Front Desk"
      systemPrompt: "..."
  connections: []
  schedules:
    - id: schedule_1
      enabled: true
      mode: interval
      everyMinutes: 30
      entryState: schedule_trigger_1
  execution:
    startAt: "Receive_Message"
    states:
      Receive_Message:
        type: "task"
        uiKind: "messaging_connector"
        connectorId: "instagram_messenger"
        skillId: "messaging.receive"
        entryPoint: true
        next: "Front_Desk"
      Front_Desk:
        type: "agent"
        agentId: "agent-front-desk"
        tools: ["knowledge_base.search", "customer.create"]
        budget: { maxTurns: 16, maxTokens: 24576, timeoutMs: 180000 }
        next: "Success"
        catch: { next: "Failed" }
      Success:
        type: "succeed"
      Failed:
        type: "fail"
        error: "Front desk agent was unable to handle the message."

Key rules:

• execution.startAt names the default start state. Any trigger state with entryPoint: true is also callable directly, so one workflow can have several entry points (for example, one per channel).
• Each state names its follow-up with next (or then and else, approve and reject, and so on for control nodes). end: true marks a state as terminal without a Succeed node.
• catch: { next: "SomeState" } is the error transition, the same one the canvas draws as the rose "on fail" edge.
• An agent state's tools list holds core tool ids as strings, and connector tools as objects with provider, skillIds, and connectorId.

danger

Keep state names consistent when editing a file by hand: a typo in a next target breaks the transition (the designer highlights broken edges in red). Prefer the designer or the AI Assistant unless you need something the canvas does not expose.

Next steps

• Install a working example and take it apart: Recipes.
• Learn what every tool can do and what each one requires: Agent tool reference.
• Connect the channels and accounts your workflow needs: Connectors.
• Give your agent something to know: Knowledge Base.