Core Concepts

A workflow is a state machine. It defines a set of states connected by transitions, with guards controlling when transitions fire. As the workflow executes, it accumulates gathered data that subsequent states can reference. Each execution of a workflow is tracked as a workflow run.

Workflow Runs

A workflow run represents a single execution of a workflow within a conversation. Runs track the current state, gathered data, transition history, and completion result independently. A conversation can have multiple runs – queued, active, completed, or abandoned – which enables multi-intent handling and workflow switching without losing history.

Run lifecycle:

When a conversation starts, the agent detects intent from the user’s opening message and creates one or more pending runs. The first run is activated immediately. When it completes, the next pending run (if any) is activated automatically. If the user’s first message matches multiple workflows, all matching runs are queued and executed in sequence.

States

States are the phases of your workflow. Each state has a name, optional instructions for the assistant, and a type that determines its behavior.

Transitions

Transitions are directed edges between states. Each transition has a source state, a target state, and one or more guards. When all guards on a transition evaluate to true, the workflow advances to the target state.

A state can have multiple outgoing transitions. The engine evaluates them in order and takes the first one whose guards pass. If no transition fires, the workflow remains in the current state.

Named Output Ports

Some state types have named output ports – predefined exit points that determine which transition the workflow follows when the state completes. Instead of configuring guards on outgoing transitions, you connect each port to a target state directly. The workflow engine routes execution to the correct target based on which port fires.

Port-based transitions require no guard configuration. The state itself decides which port to activate based on its outcome. In the visual editor, ports appear as colored labels on the node, and you drag connections from a specific port to the target state.

Output State

An Output state renders a template and delivers the result to a target. Use it for sending confirmation messages, notification emails, webhook payloads, or any formatted content that doesn’t require further interaction.

Configuration:

After delivery, the state exits through the done port.

Parse State

A Parse state uses an LLM to extract structured fields from a source text. Define the fields you need and the engine prompts the LLM to fill them from the source. This is useful for pulling structured data out of freeform user messages, email bodies, or any text stored in gathered data.

Configuration:

Ports:

• complete – All required fields were successfully extracted. The extracted values are stored in gathered data under their respective field names.
• incomplete – One or more required fields could not be extracted. Partial results are still stored. Connect this port back to a Conversation state to ask the user for the missing information, then loop back to the Parse state.

Approval State

An Approval state sends an approval request to one or more approvers and waits for a response. Unlike the approval gate feature (which is a modifier on any state), the Approval state is a dedicated state type with email-native approval, response classification, and escalation support.

Configuration:

Ports:

• approved – The approver approved the request.
• rejected – The approver rejected the request.
• discussion – The approver replied with a question or comment rather than a clear approval or rejection. Connect this port to a Conversation state to handle the discussion, then loop back to the Approval state.
• timeout – The approval timed out after all escalation attempts were exhausted.

Wait State

A Wait state pauses the workflow until an external event occurs. Use it when the workflow needs to wait for an email reply, a webhook callback, or a timer to expire before continuing.

Configuration:

Ports (default):

• received – The expected event arrived within the timeout window.
• timeout – The timeout period elapsed without receiving the expected event.

Ports (with classification enabled):

When classify.enabled is true, the received port is replaced by the custom ports defined in classify.classification_ports. The incoming response is classified by the LLM using the provided hints, and the workflow exits through the matching custom port. The timeout port remains available.

Error Handling

Each state can define an error boundary that controls what happens when the state encounters an error during execution. This provides per-state error handling without requiring manual intervention.

Configuration:

When on_error is set to port or retry_then_port, the state gains an additional error output port. Connect this port to a recovery state (e.g., a Conversation state that informs the user, or an Output state that sends an error notification).

{
  "on_error": "retry_then_port",
  "retry_policy": {
    "max_attempts": 3,
    "backoff_seconds": 10
  }
}

Guards

Guards are conditions attached to transitions. They control when the workflow moves forward.

Gathered Data

As the workflow executes, the assistant collects key-value data using the record_data tool. This data persists across states and is available to:

• Guard conditions – e.g., transition when budget is greater than 10000
• State instructions – reference gathered data in prompts using {gathered.field_key}
• Task templates – resolve participant lists from gathered data
• Operations – template interpolation using {gathered_data.field_key} with dot-path notation for nested values
• Downstream states – any later state can read what earlier states recorded

Gathered data is stored on the workflow run and visible in the workflow progress panel.

Reducers

By default, recording a value to an existing key overwrites it. A state schema on the workflow lets you define alternative merge strategies (reducers) for specific keys. This is useful when multiple states contribute to the same field.

Define reducers in the workflow’s state_schema:

{
  "emails": {
    "type": "list",
    "reducer": "append",
    "description": "Email addresses collected across states"
  },
  "approval_count": {
    "type": "number",
    "reducer": "increment"
  },
  "preferences": {
    "type": "dict",
    "reducer": "merge_dict"
  }
}

Valid types are string, number, list, dict, boolean, and any.

Global Tools

Global tools are tools available in every state of the workflow, regardless of the state’s own tool configuration. Use these for capabilities that should always be accessible – for example, record_data is typically a global tool so the assistant can collect information in any state.

Configure global tools in the workflow editor’s settings panel.

Operations

Logic states execute a sequence of deterministic operations without involving the LLM. Operations run in order and can read from and write to gathered data using template interpolation ({gathered_data.key.path}).

Operations are configured in the state definition’s operations list. Each entry has a type and a config object specific to that operation type.

Approval Gates

Any state can require human approval before its outgoing transition fires. Set require_human_approval: true on the state definition to enable this.

When the workflow reaches an approval gate:

1. The workflow pauses and sends an approval request to the configured approval_contacts
2. The conversation enters a waiting state until an approver acts
3. Approvers review the request via a dedicated approval page (/workflows/approve/<conversation_id>)
4. On approval, the workflow resumes and fires the pending transition
5. On rejection, the workflow records the rejection reason and the rejector

Approval contacts use the same recipient syntax as the send_notification operation – static email addresses, gathered data references, or conversation_contact.

Retry Policies

States can define a retry policy that controls how many times the state can be retried if an action fails. The assistant uses the retry_state tool to request a retry, and the engine enforces the configured limits.

{
  "retry": {
    "max_attempts": 3,
    "backoff_seconds": 5
  }
}

When the retry budget is exhausted, the retry_state tool returns an error and the workflow remains in the current state for manual intervention or an alternative transition.

Workflow Switching

When an assistant has multiple workflows, the agent can switch between them mid-conversation using the switch_workflow tool. This is useful when a user starts a conversation about one topic but shifts to another.

When a switch happens:

• The current workflow run is marked as abandoned and recorded in the history
• A new workflow run is created and activated with the target workflow’s starting state
• Previously gathered data is preserved and carried over to the new run
• The conversation continues seamlessly

The agent sees all available workflows in its system prompt and decides whether to switch based on the conversation context. Switching is only available when the assistant has more than one workflow attached.

Terminal States

A terminal state is any state with no outgoing transitions. When the workflow reaches a terminal state, the process is complete. The assistant delivers any final response defined in the terminal state’s instructions and the workflow is marked as finished.