Workflows

Workflows orchestrate multi-step operations with LLM reasoning, parallel execution, and complex data transformations.

Workflow Structure

json

{
  "id": "analyze-ticket",
  "name": "Analyze JIRA Ticket",
  "workflows": [{
    "name": "main",
    "steps": [
      {
        "id": "fetch",
        "action": "jira.getIssue",
        "params": { "issueKey": "&#123;&#123;input.ticketId&#125;&#125;" }
      },
      {
        "id": "analyze",
        "action": "llm",
        "params": {
          "prompt": "Analyze: &#123;&#123;steps.fetch.result&#125;&#125;",
          "model": "claude-sonnet-4-20250514"
        }
      }
    ]
  }],
  "tools": [
    { "name": "llm", "type": "llm_call" },
    { "name": "jira.getIssue", "type": "api_call", "endpoint": "..." }
  ]
}

Tool Types

llm_call

LLM inference with configurable providers.

json

{
  "name": "generate",
  "type": "llm_call",
  "params": {
    "temperature": 0.7,
    "maxTokens": 4000,
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Step usage:

json

{
  "id": "analyze",
  "action": "generate",
  "params": {
    "prompt": "Analyze: &#123;&#123;steps.fetch.result&#125;&#125;",
    "temperature": 0.3
  }
}

Supported providers: anthropic, openai, google, lmstudio, ollama-cli, claude-cli.

api_call

External API requests.

json

{
  "name": "fetchData",
  "type": "api_call",
  "endpoint": "https://api.example.com/data",
  "method": "POST",
  "params": {
    "headers": { "Authorization": "Bearer &#123;&#123;env.API_KEY&#125;&#125;" }
  }
}

mcp_tool

Model Context Protocol tools.

json

{
  "name": "filesystem",
  "type": "mcp_tool",
  "params": {
    "mcpServer": "filesystem",
    "toolName": "read_file"
  }
}

shell_command

Execute shell commands with CLI provider support.

json

{
  "name": "runScript",
  "type": "shell_command",
  "params": {
    "command": "node scripts/process.js",
    "cwd": "/app",
    "timeout": 30000
  }
}

CLI-based LLM providers:

json

{
  "id": "claude-analyze",
  "action": "shell",
  "params": {
    "command": "claude --print '&#123;&#123;steps.data.result&#125;&#125;' --output-format json",
    "cliProvider": "claude",
    "parseJSON": true
  }
}

git_command

Git operations.

json

{
  "name": "gitStatus",
  "type": "git_command",
  "params": {
    "command": "git status --porcelain",
    "cwd": "/repo"
  }
}

storage

File storage operations (R2, Supabase Storage).

json

{
  "id": "upload",
  "action": "storage",
  "params": {
    "operation": "upload",
    "bucket": "documents",
    "path": "reports/&#123;&#123;input.reportId&#125;&#125;.pdf",
    "data": "&#123;&#123;steps.generate.result&#125;&#125;"
  }
}

Operations: get, put, list, delete, signedUrl, publicUrl.

database

Database operations (Firestore, Supabase).

json

{
  "id": "save",
  "action": "database",
  "params": {
    "provider": "firestore",
    "operation": "insert",
    "collection": "reports",
    "data": "&#123;&#123;steps.analyze.result&#125;&#125;"
  }
}

Operations: get, query, insert, update, upsert, delete.

Multi-Provider Database Workflows

Override the default database provider per step using the provider field:

json

{
  "workflows": [{
    "name": "cross-db-sync",
    "steps": [
      {
        "id": "fetch-users",
        "action": "database",
        "params": {
          "provider": "supabase",
          "operation": "query",
          "collection": "users",
          "where": [{ "field": "active", "operator": "eq", "value": true }]
        }
      },
      {
        "id": "log-audit",
        "action": "database",
        "params": {
          "provider": "firebase",
          "operation": "insert",
          "collection": "audit_log",
          "data": {
            "action": "user_sync",
            "count": "&#123;&#123;steps.fetch-users.result.length&#125;&#125;"
          }
        }
      }
    ]
  }]
}

Supported providers: supabase, firebase, sqlite.

Field	Type	Required	Description
`provider`	`supabase\|firebase\|sqlite`	No	Override default provider
`operation`	`get\|query\|insert\|update\|upsert\|delete`	Yes	Database operation
`collection` / `table`	`string`	Yes	Table/collection name
`data`	`object`	For insert/update	Data to write
`where` / `filters`	`array`	For queries	Query filters
`orderBy`	`string`	No	Sort order
`limit`	`number`	No	Max results

notification

Multi-channel notifications.

json

{
  "id": "notify",
  "action": "notification",
  "params": {
    "channels": ["push", "email"],
    "title": "Report Ready",
    "body": "Your report is ready: &#123;&#123;steps.upload.result.url&#125;&#125;",
    "userId": "&#123;&#123;input.userId&#125;&#125;"
  }
}

workflow

Nested workflow execution.

json

{
  "id": "nested",
  "action": "nested-workflow",
  "params": {
    "config": {
      "id": "sub-workflow",
      "workflows": [...]
    }
  }
}

rag

Vector search with RAG modes.

json

{
  "id": "search",
  "action": "rag",
  "input": {
    "query": "&#123;&#123;input.question&#125;&#125;",
    "mode": "single",
    "limit": 5
  }
}

Modes: single, accumulate, iterative.

cache

Cache operations.

json

{
  "id": "invalidate",
  "action": "cache",
  "params": {
    "operation": "invalidate",
    "pattern": "reports:*"
  }
}

Operations: get, set, delete, invalidate.

Parallel Execution

Using `parallel: true`

Steps with parallel: true run concurrently.

json

{
  "workflows": [{
    "name": "parallel-fetch",
    "steps": [
      {
        "id": "fetch-users",
        "action": "api.getUsers",
        "parallel": true
      },
      {
        "id": "fetch-orders",
        "action": "api.getOrders",
        "parallel": true
      },
      {
        "id": "combine",
        "action": "transform",
        "dependsOn": ["fetch-users", "fetch-orders"],
        "params": {
          "users": "&#123;&#123;steps.fetch-users.result&#125;&#125;",
          "orders": "&#123;&#123;steps.fetch-orders.result&#125;&#125;"
        }
      }
    ]
  }]
}

Using `dependsOn`

Define step dependencies for DAG-based execution.

json

{
  "steps": [
    { "id": "A", "action": "step-a" },
    { "id": "B", "action": "step-b" },
    { "id": "C", "action": "step-c", "dependsOn": ["A"] },
    { "id": "D", "action": "step-d", "dependsOn": ["A", "B"] },
    { "id": "E", "action": "step-e", "dependsOn": ["C", "D"] }
  ]
}

Execution order: A and B run in parallel → C waits for A, D waits for A+B → E waits for C+D.

Early Return (Background Execution)

Return immediately to the client while workflow continues in background. Useful for long-running operations where you want quick acknowledgment.

Using `earlyReturn: true`

json

{
  "steps": [
    {
      "id": "delete-files",
      "action": "r2",
      "earlyReturn": true,
      "params": { "operation": "deleteByPrefix", "prefix": "&#123;&#123;input.tenantId&#125;&#125;/projects/&#123;&#123;input.projectId&#125;&#125;/" }
    },
    { "id": "cleanup-db", "action": "database", "params": { "operation": "delete", "collection": "projects", "id": "&#123;&#123;input.projectId&#125;&#125;" } },
    { "id": "invalidate-cache", "action": "cache", "dependsOn": ["cleanup-db"], "params": { "operation": "invalidate", "pattern": "projects:*" } }
  ]
}

When the workflow encounters a step with earlyReturn: true, it returns immediately:

json

{
  "status": "accepted",
  "executionId": "exec-123",
  "channel": "workflow:exec-123",
  "message": "Workflow started in background"
}

All steps (including the earlyReturn step) continue executing in the background.

WebSocket Progress

Subscribe to the channel for real-time progress:

typescript

bf.workflows.subscribe('exec-123', {
  onProgress: (e) => console.log(`${e.stepId}: ${e.status}`),
  onComplete: (r) => console.log('All steps done'),
  onError: (e) => console.error('Workflow failed:', e)
});

Events:

step_started - Step begins execution
step_completed - Step succeeds
step_failed - Step fails
workflow_completed - All steps done
workflow_failed - Workflow failed

Polling Status

bash

GET /agent/workflow/{executionId}/status

Response:

json

{
  "executionId": "exec-123",
  "workflowId": "project-delete",
  "status": "running",
  "completedSteps": ["delete-files", "cleanup-db"],
  "pendingSteps": ["invalidate-cache"]
}

SDK Usage

typescript

const result = await bf.workflows.execute(config);

if (result.status === 'accepted') {
  // Workflow running in background
  console.log('Started:', result.executionId);

  // Poll for status
  const status = await bf.workflows.getStatus(result.executionId);
  console.log('Progress:', status.completedSteps.length, '/', status.completedSteps.length + status.pendingSteps.length);
}

Queue as Job

For persistent, distributed background execution, add queueAsJob: true to the early return step. This queues the workflow continuation as a job instead of running it immediately in-process.

json

{
  "id": "delete-r2-files",
  "action": "r2",
  "earlyReturn": true,
  "queueAsJob": true,
  "params": { "operation": "deleteByPrefix", "prefix": "projects/&#123;&#123;projectId&#125;&#125;" }
}

When queueAsJob is enabled:

The workflow is queued to the workflows queue
Returns a jobId in the response for tracking
Execution is handled by a dedicated job worker
Survives server restarts (if using Redis/BullMQ queue)

Response with queueAsJob:

json

{
  "status": "accepted",
  "executionId": "exec-123",
  "channel": "workflow:exec-123",
  "jobId": "workflows:1234567890:abc",
  "message": "Workflow queued for execution"
}

Use queueAsJob when:

You need persistence across server restarts
Running in a distributed environment
Want job-level retry/failure handling
Need to limit concurrent background executions

Parallel JIRA Ticket Analysis

json

{
  "id": "multi-ticket-analysis",
  "name": "Analyze Multiple Tickets",
  "workflows": [{
    "name": "parallel-analysis",
    "steps": [
      {
        "id": "ticket1",
        "action": "jira.getIssue",
        "parallel": true,
        "params": { "issueKey": "PROJ-101" }
      },
      {
        "id": "ticket2",
        "action": "jira.getIssue",
        "parallel": true,
        "params": { "issueKey": "PROJ-102" }
      },
      {
        "id": "ticket3",
        "action": "jira.getIssue",
        "parallel": true,
        "params": { "issueKey": "PROJ-103" }
      },
      {
        "id": "analyze-all",
        "action": "llm",
        "dependsOn": ["ticket1", "ticket2", "ticket3"],
        "params": {
          "prompt": "Analyze these tickets and find common themes:\n&#123;&#123;steps.ticket1.result | json&#125;&#125;\n&#123;&#123;steps.ticket2.result | json&#125;&#125;\n&#123;&#123;steps.ticket3.result | json&#125;&#125;"
        }
      }
    ]
  }]
}

Conditional Execution

Step Conditions

json

{
  "id": "send-alert",
  "action": "slack.sendMessage",
  "conditions": {
    "steps.analyze.result.severity": "high"
  },
  "params": {
    "channel": "#alerts",
    "text": "High severity issue detected"
  }
}

Condition Operators

json

{
  "conditions": {
    "steps.count.result": { "$gt": 100 },
    "steps.status.result": { "$in": ["active", "pending"] },
    "steps.data.result.enabled": { "$eq": true }
  }
}

Operator	Description
`$eq`	Equal
`$ne`	Not equal
`$gt`	Greater than
`$gte`	Greater than or equal
`$lt`	Less than
`$lte`	Less than or equal
`$in`	In array
`$exists`	Field exists

Expression Conditions

json

{
  "conditions": {
    "if": "&#123;&#123;steps.analyze.result.score&#125;&#125; > 80"
  }
}

Template Variables

Basic Variables

Variable	Description
`{{input.field}}`	Workflow input
`{{steps.stepId.result}}`	Step result
`{{steps.stepId.output}}`	Step output
`{{steps.stepId.stdout}}`	Shell command stdout
`{{env.VAR}}`	Environment variable
`{{secret:KEY}}`	Tenant secret

Template Filters

json

{
  "prompt": "Data: &#123;&#123;steps.fetch.result | json&#125;&#125;"
}

Filter	Description
`json`	JSON stringify
`default: 'value'`	Default if undefined

Conditional Templates

json

{
  "prompt": "&#123;&#123;#if steps.data.result&#125;&#125;Has data: &#123;&#123;steps.data.result&#125;&#125;&#123;&#123;else&#125;&#125;No data&#123;&#123;/if&#125;&#125;"
}

Pause and Resume

Pause Points

json

{
  "id": "approval",
  "action": "analyze",
  "pausePoint": {
    "message": "Review analysis before proceeding",
    "requireApproval": true,
    "notify": {
      "enabled": true,
      "userId": "&#123;&#123;input.approver&#125;&#125;",
      "channels": ["push", "email"]
    }
  }
}

Resume Execution

bash

POST /agent/workflow/resume
Content-Type: application/json

{
  "executionId": "exec-123",
  "continueExecution": true,
  "userInput": { "approved": true }
}

Cancel Execution

bash

POST /agent/workflow/cancel
Content-Type: application/json

{
  "executionId": "exec-123"
}

Execute Workflow

Run Inline Workflow

bash

POST /agent/workflow
Content-Type: application/json

{
  "workflow": {
    "id": "my-workflow",
    "workflows": [{ "name": "main", "steps": [...] }],
    "tools": [...]
  },
  "input": { "ticketId": "PROJ-123" }
}

Run Saved Workflow

bash

POST /agent/workflow/run
Content-Type: application/json

{
  "workflowId": "analyze-ticket",
  "input": { "ticketId": "PROJ-123" }
}

Plan Only (Dry Run)

bash

POST /agent/workflow
Content-Type: application/json

{
  "workflow": { ... },
  "planOnly": true
}

WebSocket Progress

json

{
  "broadcast": true
}

Connect to ws://server/workflow:exec-123 to receive progress updates.

Workflow Status

bash

GET /agent/workflow/status?workflowId=abc123

Response:

json

{
  "workflowId": "abc123",
  "status": "completed",
  "executionId": "exec-456",
  "duration": 1234,
  "steps": [
    { "id": "fetch", "status": "success", "output": {...} },
    { "id": "analyze", "status": "success", "output": {...} }
  ]
}

Error Handling

json

{
  "id": "risky-step",
  "action": "external-api",
  "onError": {
    "action": "continue",
    "fallback": {
      "id": "fallback-step",
      "action": "llm",
      "params": { "prompt": "Generate fallback response" }
    }
  }
}

Advanced Examples

Multi-Agent Orchestration

json

{
  "id": "multi-agent",
  "name": "Multi-Agent Analysis",
  "agent": {
    "llm_prompt": "You are analyzing code and providing recommendations."
  },
  "workflows": [{
    "name": "orchestration",
    "steps": [
      {
        "id": "code-review",
        "action": "llm",
        "parallel": true,
        "params": { "prompt": "Review code quality: &#123;&#123;input.code&#125;&#125;" }
      },
      {
        "id": "security-scan",
        "action": "llm",
        "parallel": true,
        "params": { "prompt": "Identify security issues: &#123;&#123;input.code&#125;&#125;" }
      },
      {
        "id": "performance-check",
        "action": "llm",
        "parallel": true,
        "params": { "prompt": "Find performance issues: &#123;&#123;input.code&#125;&#125;" }
      },
      {
        "id": "synthesize",
        "action": "llm",
        "dependsOn": ["code-review", "security-scan", "performance-check"],
        "params": {
          "prompt": "Combine findings:\n- Code Review: &#123;&#123;steps.code-review.result&#125;&#125;\n- Security: &#123;&#123;steps.security-scan.result&#125;&#125;\n- Performance: &#123;&#123;steps.performance-check.result&#125;&#125;"
        }
      }
    ]
  }],
  "tools": [{ "name": "llm", "type": "llm_call" }]
}

E-Commerce Order Processing

json

{
  "id": "process-order",
  "name": "Process E-Commerce Order",
  "workflows": [{
    "name": "order-flow",
    "steps": [
      {
        "id": "validate-inventory",
        "action": "database",
        "params": {
          "operation": "query",
          "collection": "inventory",
          "where": [{ "field": "sku", "operator": "in", "value": "&#123;&#123;input.skus&#125;&#125;" }]
        }
      },
      {
        "id": "check-stock",
        "action": "llm",
        "params": {
          "prompt": "Check if all items are in stock: &#123;&#123;steps.validate-inventory.result&#125;&#125;"
        }
      },
      {
        "id": "process-payment",
        "action": "stripe.charge",
        "conditions": { "steps.check-stock.result.inStock": true },
        "params": {
          "amount": "&#123;&#123;input.total&#125;&#125;",
          "currency": "usd",
          "customer": "&#123;&#123;input.customerId&#125;&#125;"
        }
      },
      {
        "id": "create-shipment",
        "action": "shipping.createLabel",
        "dependsOn": ["process-payment"],
        "params": {
          "address": "&#123;&#123;input.shippingAddress&#125;&#125;",
          "items": "&#123;&#123;input.items&#125;&#125;"
        }
      },
      {
        "id": "send-confirmation",
        "action": "sendgrid.sendTemplate",
        "dependsOn": ["create-shipment"],
        "params": {
          "to": "&#123;&#123;input.email&#125;&#125;",
          "templateId": "order-confirmation",
          "data": {
            "orderId": "&#123;&#123;input.orderId&#125;&#125;",
            "trackingNumber": "&#123;&#123;steps.create-shipment.result.trackingNumber&#125;&#125;"
          }
        }
      }
    ]
  }]
}

Batch Processing with ForEach

json

{
  "id": "process-batch",
  "workflows": [{
    "name": "batch",
    "steps": [
      {
        "id": "fetch-items",
        "action": "jira.search",
        "params": { "jql": "status = Open" }
      },
      {
        "id": "process-each",
        "type": "forEach",
        "items": "&#123;&#123;steps.fetch-items.result.issues&#125;&#125;",
        "step": {
          "action": "llm",
          "params": { "prompt": "Summarize: &#123;&#123;item.fields.summary&#125;&#125;" }
        }
      },
      {
        "id": "aggregate",
        "action": "llm",
        "params": {
          "prompt": "Create summary report from: &#123;&#123;steps.process-each.result&#125;&#125;"
        }
      }
    ]
  }]
}

SDK Usage

Execute Workflows via SDK

typescript

import { createBackflow } from '@backflow/sdk';

const bf = createBackflow({
  tenantId: 'my-tenant',
  apiKey: process.env.BACKFLOW_API_KEY,
  endpoint: 'http://localhost:3000'  // Local development
});

// Execute inline workflow
const result = await bf.workflows.execute({
  steps: [
    { id: 'fetch', action: 'jira.getIssue', params: { issueKey: 'PROJ-123' } },
    { id: 'analyze', action: 'llm', params: { prompt: 'Analyze: &#123;&#123;steps.fetch.result&#125;&#125;' } }
  ]
});

// Run saved workflow
const result = await bf.workflows.run('analyze-ticket', { ticketId: 'PROJ-123' });

// Subscribe to progress
bf.workflows.subscribe(result.executionId, {
  onProgress: (e) => console.log(`${e.stepId}: ${e.status}`),
  onComplete: (r) => console.log('Done:', r),
  onError: (e) => console.error(e)
});

// Control execution
await bf.workflows.pause(result.executionId);
await bf.workflows.resume(result.executionId);
await bf.workflows.cancel(result.executionId);

CLI Script for Workflows

typescript

// scripts/run-workflow.ts
import { createBackflow } from '@backflow/sdk';

const bf = createBackflow({
  tenantId: process.env.BACKFLOW_TENANT_ID!,
  apiKey: process.env.BACKFLOW_API_KEY!,
  endpoint: process.env.BACKFLOW_ENDPOINT || 'http://localhost:3000'
});

const [,, workflowId, inputJson] = process.argv;
const input = inputJson ? JSON.parse(inputJson) : {};

bf.workflows.run(workflowId, input)
  .then(console.log)
  .catch(console.error);

Run workflows from terminal:

bash

npx tsx scripts/run-workflow.ts analyze-ticket '{"ticketId":"PROJ-123"}'

CLI-Based Code Analysis

json

{
  "id": "code-analysis",
  "name": "Analyze Code with Claude CLI",
  "workflows": [{
    "name": "analysis",
    "steps": [
      {
        "id": "read-file",
        "action": "filesystem",
        "params": { "path": "&#123;&#123;input.filePath&#125;&#125;" }
      },
      {
        "id": "analyze",
        "action": "shell",
        "params": {
          "command": "claude --print 'Analyze this code for bugs and improvements:\n&#123;&#123;steps.read-file.stdout&#125;&#125;' --output-format json",
          "cliProvider": "claude",
          "parseJSON": true
        }
      },
      {
        "id": "save-report",
        "action": "storage",
        "params": {
          "operation": "upload",
          "bucket": "reports",
          "path": "analysis/&#123;&#123;input.fileName&#125;&#125;.json",
          "data": "&#123;&#123;steps.analyze.result&#125;&#125;"
        }
      }
    ]
  }],
  "tools": [
    { "name": "filesystem", "type": "mcp_tool" },
    { "name": "shell", "type": "shell_command" },
    { "name": "storage", "type": "storage" }
  ]
}

Workflows ​

Workflow Structure ​

Tool Types ​

llm_call ​

api_call ​

mcp_tool ​

shell_command ​

git_command ​

storage ​

database ​

Multi-Provider Database Workflows ​

notification ​

workflow ​

rag ​

cache ​

Parallel Execution ​

Using parallel: true ​

Using dependsOn ​

Early Return (Background Execution) ​

Using earlyReturn: true ​

WebSocket Progress ​

Polling Status ​

SDK Usage ​

Queue as Job ​

Parallel JIRA Ticket Analysis ​

Conditional Execution ​

Step Conditions ​

Condition Operators ​

Expression Conditions ​

Template Variables ​

Basic Variables ​

Template Filters ​

Conditional Templates ​

Pause and Resume ​

Pause Points ​

Resume Execution ​

Cancel Execution ​

Execute Workflow ​

Run Inline Workflow ​

Run Saved Workflow ​

Plan Only (Dry Run) ​

WebSocket Progress ​

Workflow Status ​

Error Handling ​

Advanced Examples ​

Multi-Agent Orchestration ​

E-Commerce Order Processing ​

Batch Processing with ForEach ​

SDK Usage ​

Execute Workflows via SDK ​

CLI Script for Workflows ​

CLI-Based Code Analysis ​

Workflows

Workflow Structure

Tool Types

llm_call

api_call

mcp_tool

shell_command

git_command

storage

database

Multi-Provider Database Workflows

notification

workflow

rag

cache

Parallel Execution

Using `parallel: true`

Using `dependsOn`

Early Return (Background Execution)

Using `earlyReturn: true`

WebSocket Progress

Polling Status

SDK Usage

Queue as Job

Parallel JIRA Ticket Analysis

Conditional Execution

Step Conditions

Condition Operators

Expression Conditions

Template Variables

Basic Variables

Template Filters

Conditional Templates

Pause and Resume

Pause Points

Resume Execution

Cancel Execution

Execute Workflow

Run Inline Workflow

Run Saved Workflow

Plan Only (Dry Run)

WebSocket Progress

Workflow Status

Error Handling

Advanced Examples

Multi-Agent Orchestration

E-Commerce Order Processing

Batch Processing with ForEach

SDK Usage

Execute Workflows via SDK

CLI Script for Workflows

CLI-Based Code Analysis