Workflow Schema

Properties

type (optional)

• Type: string
• Value: workflow
• Default: workflow
• Description: Identifies this configuration as a workflow. While optional due to the default value, including it explicitly helps with YAML validation and clarity.

type: workflow

title (optional)

• Type: string
• Description: A human-readable name for your workflow. This helps identify and organize your workflows in the Loopstack AI interface and appears in the studio UI.

title: "Invoice Processing Workflow"

description (optional)

• Type: string
• Description: A detailed explanation of the workflow’s purpose, functionality, or business logic. Useful for documentation, team collaboration, and understanding the workflow’s role in your automation.

description: "Automates invoice processing from receipt to payment approval with multi-stage validation"

transitions (optional)

• Type: array
• Description: An array of transition definitions that control the workflow’s state machine logic. Transitions define how the workflow moves between states, what tools are executed, and under what conditions. This is the core mechanism that drives workflow execution.

transitions:
  - id: process
    from: start
    to: processing
    call:
      - tool: ProcessDataTool
  - id: complete
    from: processing
    to: end

Transition Properties

id (required)

• Type: string
• Description: A unique identifier for this transition. Used for referencing the transition in logs, debugging, and to access data in subsequent transitions.

transitions:
  - id: validate-input
    from: start
    to: validated

from (optional)

• Type: string or array of strings
• Description: Specifies the source state(s) from which this transition can be triggered. Can be a single state name or an array of state names. Workflows always start in the start state and end in the end state.

transitions:
  # Single source state
  - id: step1
    from: start
    to: processing
 
  # Multiple source states
  - id: step2
    from:
      - processing
      - retry
    to: completed

to (optional)

• Type: string or array of strings
• Description: Specifies the destination state(s) to which this transition leads. Can be a single state name or an array of state names for branching logic. The workflow completes when reaching the end state.

transitions:
  # Single destination
  - id: process
    from: start
    to: processed
 
  # Multiple destinations (branching)
  - id: evaluate
    from: processed
    to:
      - approved
      - rejected

when (optional)

• Type: "manual", "onEntry", or template expression
• Description: Defines when this transition should be triggered.
• manual: Requires explicit user action (e.g., button click in the UI)
• onEntry: Automatically triggers when entering the from state
• Template expression: Custom condition using ${ expression } syntax

transitions:
  # Automatic execution on state entry
  - id: auto-process
    from: start
    to: processing
    when: onEntry
 
  # Manual user action required
  - id: approve
    from: review
    to: approved
    when: manual
 
  # Conditional execution
  - id: high-priority
    from: processing
    to: escalated
    when: ${ args.priority === "high" }

call (optional)

• Type: array
• Description: An array of tool calls to execute when this transition is triggered. Tools are executed sequentially in the order specified. Each tool call can access results from previous calls.

transitions:
  - id: process-order
    from: start
    to: processed
    call:
      - tool: ValidateOrderTool
        args:
          orderId: ${ args.orderId }
      - id: total
        tool: CalculateTotalTool
        args:
          items: ${ args.items }
        assign:
          invoiceTotal: ${ result.data.total }
      - tool: CreateInvoiceTool
        args:
          items: ${ args.items }
          total: ${ invoiceTotal }

onError (optional)

• Type: string
• Description: Specifies the state to transition to if an error occurs during the execution of this transition. This enables error handling and recovery workflows. If not specified, errors will halt the workflow execution.

transitions:
  - id: risky-operation
    from: start
    to:
      - success
      - error
    onError: error
    call:
      - tool: RiskyApiCallTool
 
  - id: handle-error
    from: error
    to: end
    call:
      - tool: LogErrorTool
      - tool: SendAlertTool

Tool Call Properties

id (optional)

• Type: string
• Description: A unique identifier for this specific tool call. Useful for debugging and for referencing the tool call’s results in subsequent operations.

call:
  - id: fetch-user-data
    tool: GetUserTool
    args:
      userId: ${ args.userId }

tool (required)

• Type: string
• Description: The name of the tool to execute. The tool must be imported in the workflow’s TypeScript configuration.

call:
  - tool: SendEmailTool
  - tool: CreateDocumentTool
  - tool: ApiCallTool

args (optional)

• Type: any
• Description: Arguments to pass to the tool when it executes. The structure depends on what the specific tool expects. Can contain any valid YAML data structure including template expressions to access workflow context, input parameters, and results from previous tool calls.

call:
  - tool: ProcessDataTool
    args:
      # Simple values
      apiKey: "secret-key"
      maxRetries: 3
 
      # Template expressions
      userId: ${ args.userId }

assign (optional)

• Type: object
• Description: Maps specific values from the tool’s result or other context variables to named variables. Each key-value pair assigns a value to a property name of the workflow service. Supports template expressions, primitive values, and nested objects. Use ~ (null) to clear a variable.

call:
  - tool: ProcessOrderTool
    args:
      orderId: ${ args.orderId }
    assign:
      # Extract from result
      orderId: ${ result.data.id }
      customerName: ${ result.data.customer.name }
 
      # Static values
      status: "completed"
 
      # Clear variable
      temporaryData: ~
 
      # Complex object
      summary:
        total: ${ result.data.total }
        items: ${ result.data.itemCount }