Skip to main content

Core Types

FlowContext

The context object available in every step handler:
interface FlowContext<TInput = any, TResults = Record<string, any>> {
  workflowId: string;
  executionId: string;
  input: TInput;               // Original workflow input
  results: TResults;           // All previous step results (plain object)
  currentStep: string;         // Current step ID
  metadata: {
    startTime: Date;
    currentTime: Date;
    stepCount: number;         // Steps executed so far
    totalSteps: number;        // Total steps in workflow
  };
}

WorkflowConfig

interface WorkflowConfig {
  id: string;
  name?: string;
  description?: string;
  inputSchema: z.ZodSchema;
  outputSchema: z.ZodSchema;
  steps: WorkflowStep[];
  options?: WorkflowOptions;
  outputTransform?: (stepResults: Record<string, any>, input: any) => any;
}

WorkflowStep

interface WorkflowStep {
  id: string;
  name?: string;
  description?: string;
  type: 'agent' | 'function' | 'connector' | 'condition' | 'parallel' | 'switch' | 'foreach';
  config: StepConfig;
  inputTransform?: (previousOutput: any, workflowInput: any) => any;
  outputTransform?: (stepOutput: any) => any;
  condition?: (context: FlowContext) => boolean;
  retryConfig?: RetryConfig;
}

AgentStepResult

Returned by .agent() steps:
interface AgentStepResult {
  text: string;
  metadata: {
    agent: string;    // Agent name
    model: string;    // Model used
    stepId: string;   // Step ID
  };
}

Builder Option Types

StepOpts

Options for .step():
interface StepOpts {
  outputSchema?: z.ZodSchema;   // Runtime output validation
  retryConfig?: RetryConfig;
  condition?: (ctx: FlowContext) => boolean;
  inputTransform?: (previousOutput: any, workflowInput: any) => any;
  outputTransform?: (stepOutput: any) => any;
}

BranchOpts

Options for .branch():
interface BranchOpts {
  condition: (ctx: FlowContext) => boolean;
  onTrue: StepHandler | WorkflowStep[];
  onFalse?: StepHandler | WorkflowStep[];
  unwrap?: boolean;   // default: true
}

SwitchOpts

Options for .switch():
interface SwitchOpts {
  on: (ctx: FlowContext) => string;
  cases: Record<string, StepHandler | WorkflowStep[]>;
  default?: StepHandler | WorkflowStep[];
  unwrap?: boolean;   // default: true
}

ForeachOpts

Options for .foreach():
interface ForeachOpts {
  handler: (item: any, ctx: FlowContext) => Promise<any>;
  concurrency?: number;   // default: 1 (sequential)
}

AgentOpts

Options for .agent():
interface AgentOpts {
  prompt?: string;
  promptTemplate?: string;
  when?: (ctx: FlowContext) => boolean;
  retry?: RetryConfig;
}

ParallelOpts

Options for .parallel():
interface ParallelOpts {
  waitForAll?: boolean;    // default: true
  maxConcurrency?: number;
}

Configuration Types

RetryConfig

interface RetryConfig {
  maxAttempts: number;
  backoff: 'fixed' | 'exponential' | 'linear';
  delay: number;                // Base delay in ms
  retryableErrors?: string[];   // Only retry matching errors
}

WorkflowOptions

interface WorkflowOptions {
  timeout?: number;
  maxRetries?: number;
  onError?: 'stop' | 'continue' | 'retry';
  persistState?: boolean;
}

Graph Types

WorkflowGraph

Returned by workflow.toGraph():
interface WorkflowGraph {
  id: string;
  name: string;
  nodes: GraphNode[];
  edges: GraphEdge[];
}

interface GraphNode {
  id: string;
  type: 'step' | 'agent' | 'condition' | 'switch' | 'parallel' | 'foreach' | 'connector';
  label: string;
  metadata?: {
    description?: string;
    inputSchema?: object;
    outputSchema?: object;
  };
}

interface GraphEdge {
  source: string;
  target: string;
  label?: string;   // e.g. 'true', 'false', 'billing', 'default'
}

Event Types

WorkflowEvents

Events emitted by Workflow during execution:
interface WorkflowEvents {
  'workflow:start':    { workflowId: string; executionId: string; input: any };
  'workflow:complete': { executionId: string; output: any; durationMs: number };
  'workflow:error':    { executionId: string; error: string; durationMs: number };
  'step:start':        { stepId: string; stepType: string; input: any };
  'step:complete':     { stepId: string; output: any; durationMs: number };
  'step:error':        { stepId: string; error: string };
  'step:skip':         { stepId: string; reason: string };
}

Handler Types

StepHandler

type StepHandler<TIn = any, TOut = any> = (
  input: TIn,
  ctx: FlowContext,
) => Promise<TOut>;

Legacy Types (Deprecated)

WorkflowContext

/** @deprecated Use FlowContext instead */
interface WorkflowContext {
  workflowId: string;
  executionId: string;
  input: any;
  stepResults: Map<string, any>;   // Use ctx.results instead
  currentStep: string;
  metadata: { startTime: Date; currentTime: Date; stepCount: number; totalSteps: number };
  runflowAPI: RunflowAPIClient;    // Internal — use connector() helper
}

Next Steps

Trace Types

Observability type definitions

Workflows Guide

Learn workflow concepts