Workflow Automation | VexAI Docs

Overview

VexAI's workflow engine lets you create complex automation without writing code. Workflows are graph-based: a collection of nodes connected by edges, forming a directed acyclic graph (DAG). Execution flows from trigger nodes through conditions, actions, and transforms until it reaches terminal nodes.

ℹ️ What's a DAG?

A directed acyclic graph is a structure where nodes are connected by one-way edges and there are no loops. This ensures workflows always terminate and execution order is deterministic.

How Workflows Work

Graph-based: nodes connected by edges form the execution pipeline
Template rendering: use {{variable}} syntax (Handlebars-like) to inject runtime values
Typed nodes: each node has a type, configuration object, and connections to other nodes
Traversal: execution starts at a trigger node and traverses the graph to terminal nodes

{
  "nodes": [
    { "id": "trigger", "type": "discord_event", "config": { "event": "memberAdd" } },
    { "id": "greet",   "type": "send_message",  "config": {
      "channel": "{{trigger.guild.systemChannelId}}",
      "content": "Welcome {{trigger.user.username}}! 🎉"
    }}
  ],
  "edges": [
    { "from": "trigger", "to": "greet" }
  ]
}

Node Types (30+ across 5 categories)

🎯 Trigger Nodes

What starts the workflow:

Node	Description
`discord_event`	Triggered by Discord events (message, reaction, member join, etc.)
`command`	Triggered by a custom command
`reaction_role`	Triggered by reaction role events
`webhook`	Triggered by inbound webhook
`schedule`	Triggered on a cron schedule
`manual`	Triggered manually via tool call

🔀 Condition Nodes

Branching logic that controls execution flow:

Node	Description
`if`	Conditional branch (true/false)
`switch`	Multi-way branch based on value
`cooldown`	Rate limit check
`permission`	Permission check
`time_window`	Only proceed during a specified time range

⚡ Action Nodes

Nodes that do things:

Node	Description
`send_message`	Send a message to a channel
`ai_generate`	Generate text via LLM
`tool_call`	Execute any VexAI tool
`assign_role`	Add or remove a role
`create_thread`	Create a thread
`dm_user`	Send a DM
`http_request`	Make an HTTP request
`sub_agent`	Spawn a sub-agent
`delay`	Wait for a duration
`log`	Log to workflow history

🔄 Transform Nodes

Reshape and process data between steps:

Node	Description
`template`	Render a template string
`json_extract`	Extract fields from JSON
`ai_extract`	Use LLM to extract structured data
`merge`	Merge multiple inputs
`map`	Transform each item in an array

🎛️ Control Nodes

Manage execution flow:

Node	Description
`parallel`	Execute branches in parallel
`join`	Wait for parallel branches to complete
`loop`	Repeat a section
`error_handler`	Catch and handle errors

Template Rendering

Workflows use a {{variable}} syntax (Handlebars-like) for inserting runtime values into node configurations. You can access trigger data, previous node outputs, and execution context.

# Access trigger data
Hello {{trigger.user.username}}, welcome to {{trigger.guild.name}}!

# Access previous node output
The AI generated: {{nodes.ai_step.output}}

# Access context
Current time: {{context.timestamp}}

💡 Template scope

Every node's output is available to downstream nodes via {{nodes.<nodeId>.output}}. Trigger data is always available at {{trigger.*}}.

Execution Limits

Workflows operate under hard limits to prevent runaway execution:

Limit	Value	Description
Timeout	`2 minutes`	Maximum wall-clock time per workflow run
Node cap	`100 nodes`	Maximum number of nodes executed in a single run

🚨 Hard limits

Workflows that exceed the 2-minute timeout or 100-node cap are terminated immediately. Design workflows to complete well within these bounds. Use the workflow_run_history tool to identify bottlenecks.

Run Logging

Every workflow execution produces a full history log with node-by-node detail:

Node status: success, failure, or skipped for each node
Results: output data from every executed node
Duration tracking: how long each node and the total run took
Queryable: use the workflow_run_history tool to inspect past runs

{
  "run_id": "wfr_a1b2c3",
  "workflow": "welcome-new-members",
  "status": "completed",
  "duration_ms": 1240,
  "nodes": [
    { "id": "trigger", "status": "success", "duration_ms": 2 },
    { "id": "greet",   "status": "success", "duration_ms": 856 },
    { "id": "role",    "status": "success", "duration_ms": 382 }
  ]
}

ℹ️ Debugging workflows

When a workflow fails, the run log shows exactly which node failed and why. Check the node's output field for error details.

Managing Workflows

Enabling Workflows

Workflows are toggled at the server level. Enable them with either method:

# Via slash command
/workflows

# Via config tool
/config set workflows.enabled true

Tools

Full workflow lifecycle management through VexAI's tool system:

Tool	Description
`create_workflow`	Create a new workflow definition
`list_workflows`	List all workflows
`get_workflow`	Get a specific workflow's details
`update_workflow`	Modify an existing workflow
`delete_workflow`	Delete a workflow
`toggle_workflow`	Enable or disable a workflow
`trigger_workflow`	Manually trigger a workflow
`workflow_run_history`	Query execution history and logs
`workflow_templates`	Browse pre-built workflow templates

💡 Templates

Use workflow_templates to browse ready-made workflows for common tasks like welcome messages, auto-moderation, and scheduled announcements. Templates can be customized after creation.