Workflows — Visual DAG Builder

A Workflow is a directed acyclic graph (DAG) of nodes that defines exactly how a multi-step AI process should execute. Build it visually, describe it in plain English and let AI generate it, or define it via the API.

Scenario: An HR team automates candidate screening. The workflow ingests a CV → extracts skills → scores the candidate against the job requirements → routes high-scorers to a human reviewer → sends offer letters automatically.

Node types

Node	Purpose
start	Entry point. Every workflow has exactly one start node.
agent	Run an AI agent with a specific goal. Output is available to downstream nodes.
llm	Direct LLM call without a full agent. Supports four operations: `text_complete`, `extract`, `embed`, and `search`. See LlmNode operations below.
conditional	Two-way branch: evaluates an expression and routes to true or false path.
switch	Multi-way branch: matches a value against multiple cases, routes to matching edge.
human_task	Pauses the workflow and waits for a human to complete a form. SLA timer enforced.
dynamic_fork	Fan-out: iterates over a list and runs downstream nodes once per item in parallel. When the target is a `sub_workflow` node, each branch executes as a separate sub-workflow run; all branches fan back in via a `merge` node before execution continues.
do_while	Loop: repeats a sub-graph until an exit condition is met.
merge	Fan-in: waits for all parallel branches to complete and merges their outputs into a single structured result.
crew	Run a multi-agent Crew. The crew executes and its synthesised result is available to downstream nodes.
sub_workflow	Embed another workflow as a reusable sub-graph. The sub-workflow runs as a nested experiment.
http_request	Make an HTTP request to an external API. Response body and status code are available to downstream nodes.
time_gate	Pause execution until a specified time or duration elapses, then continue with the original data.
knowledge_retrieval	Semantic search over the team's memory and knowledge base. Returns top-k relevant chunks as structured output.
parameter_extractor	Extract named parameters from unstructured text using LLM-assisted parsing. Outputs a structured JSON object.
variable_aggregator	Collect outputs from multiple upstream nodes and merge them into a single aggregated result.
template_transform	Render a Blade/Twig template with upstream variables to produce formatted text output.
annotation	Non-executing sticky note attached to the canvas. Use for design comments, TODOs, or reviewer guidance — skipped at runtime.
iteration	Flowise-style iteration block: runs an inner sub-graph once per item in an input collection with accumulated state. A simpler alternative to `dynamic_fork` + `merge` when you want strictly sequential per-item execution.
workflow_ref	Alias of `sub_workflow` using Flowise naming. Embeds a reusable child workflow as a single node.
end	Terminal node. Triggers artifact collection and marks the experiment complete.

LlmNode operations

An llm node is configured with an operation field that selects one of four modes:

Operation	What it does
text_complete	Default. Sends a prompt and stores the text response as node output.
extract	Structured extraction. Requires `output_schema` (JSON Schema). Returns a typed JSON object.
embed	Generates a float[] embedding vector from the input text. Stored as node output for downstream similarity search.
search	Semantic memory search. Runs a cosine-similarity query against the team's memory store and returns top-k results.

Node config examples:

json

// extract — pull structured data from unstructured text
{
  "operation": "extract",
  "model": "claude-sonnet-4-5",
  "prompt_template": "Extract candidate details from: {{input.cv_text}}",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "skills": { "type": "array", "items": { "type": "string" } },
      "years_experience": { "type": "integer" }
    },
    "required": ["name", "skills"]
  }
}

json

// embed — generate a vector for similarity search
{
  "operation": "embed",
  "text_template": "{{output.summary}}",
  "embed_provider": "openai",
  "embed_model": "text-embedding-3-small"
}

json

// search — retrieve relevant memory entries
{
  "operation": "search",
  "query_template": "{{input.candidate_skills}}",
  "search_k": 5
}

Conditional expressions

Conditional and switch nodes evaluate expressions against the current step's output. Use {{variable}} syntax to reference upstream node output:

text

{{output.score}} > 80


{{output.summary}} is not empty


{{output.level}}

Human Task nodes

When the workflow reaches a human_task node, FleetQ creates an ApprovalRequest and pauses execution. A notification is sent to the designated reviewer, who fills in a form (defined as a JSON schema on the node).

Human Task nodes enforce an SLA timer. If the reviewer doesn't act within the configured duration, the task is automatically escalated (to a fallback reviewer) or expired (and the experiment fails gracefully).

Saga pattern (compensation on failure)

Every workflow node can declare a compensation node — a rollback step that runs automatically if the node fails mid-execution. This implements the Saga pattern for distributed transactions.

Set compensation_node_id on any node when saving the graph. On failure, RunCompensationChainAction walks the executed nodes in reverse order and runs each compensation node in sequence.

json

// PUT /api/v1/workflows/WORKFLOW_ID/graph
{
  "nodes": [
    {
      "id": "node-charge",
      "type": "agent",
      "label": "Charge customer",
      "compensation_node_id": "node-refund"
    },
    {
      "id": "node-refund",
      "type": "agent",
      "label": "Refund customer",
      "config": { "goal": "Reverse the charge for order {{input.order_id}}" }
    }
  ]
}

Compensation nodes are skipped if the original node never ran (e.g. it was never reached). Only nodes that successfully started execution are compensated.

Workflow Gateway — expose workflows as MCP tools

The Workflow Gateway publishes any active workflow as a named MCP tool, making it callable by agents, the platform assistant, and external MCP clients.

MCP tool	Purpose
workflow_enable_gateway	Publish a workflow as a named MCP tool. Requires `tool_name` (snake_case, 3–64 chars) and optional `mcp_execution_mode`.
workflow_disable_gateway	Remove the MCP tool registration for a workflow.
workflow_list_gateway_tools	List all workflows currently exposed as MCP tools.

Execution modes:

Mode	Behaviour
async	Default. The MCP tool call returns immediately with an experiment ID; execution runs in the background.
sync	The MCP tool call blocks until the workflow completes and returns the final output.

json

// Enable gateway via MCP (tool: workflow_enable_gateway)
{
  "workflow_id": "wf_01jq...",
  "tool_name": "screen_candidate",
  "mcp_execution_mode": "async"
}

Generate workflows from text

Describe your workflow in plain English, and FleetQ uses Claude to generate the DAG for you. Generation is available via the visual builder UI (the ✨ button on the canvas) or through the workflow_generate MCP tool:

json

// MCP tool: workflow_generate
{
  "workflow_id": "wf_01jq...",
  "prompt": "Ingest a job application, extract candidate skills, score fit against the role, then send a human review request if score > 70"
}

Observability — LangFuse & LangSmith

Every workflow can be instrumented with an external LLM observability provider. Attach credentials for LangFuse or LangSmith per workflow (or globally per team), and FleetQ will stream traces, spans, and generations to that provider in real time. Use it to debug failing runs, compare cost/latency across workflow revisions, and build dashboards across all AI activity in your organisation.

Provider	What gets sent
LangFuse	Trace per experiment, span per node, generation per LLM call. Token counts, latency, cost, prompt/response bodies, and workflow metadata are included.
LangSmith	Run tree with the workflow as root and nodes as children. Inputs, outputs, and errors are attached.

Combine observability with the Flow Evaluation Suite for a closed loop: run an evaluation, inspect per-row traces in LangFuse/LangSmith, fix the failing node, re-run the evaluation, and compare deltas side-by-side.

Estimating cost before you run

Before activating a workflow, check the projected cost:

bash

GET https://fleetq.169.58.89.204.sslip.io/api/v1/workflows/WORKFLOW_ID/cost

Returns token estimates per node, total credit estimate, and a breakdown by provider.