Workflow API

Workflow.create()

Creates a new workflow instance.

Workflow.create(id: string, version?: string): Workflow

Parameters:

• id (string) - Unique workflow identifier
• version (string, optional) - Workflow version

Returns: Workflow instance

Example:

const workflow = Workflow.create("refund_v1");

workflow.step()

Adds a step to the workflow.

workflow.step(
  name: string,
  handler: StepHandler,
  decisionRequired?: boolean
): Workflow

Parameters:

• name (string) - Step name (must be unique)
• handler (StepHandler) - Step handler function
• decisionRequired (boolean, optional) - Whether step requires decision

Returns: Workflow instance (for chaining)

Example:

workflow
  .step("step1", async (ctx) => {
    return { decision: "proceed", reason: "...", confidence: 1.0 };
  }, true)
  .step("step2", async (ctx) => {
    // ...
  }, true);

workflow.execute()

Executes the workflow with input data.

workflow.execute(input: any): Promise<Execution>

Parameters:

• input (any) - Input data for the workflow

Returns: Promise<Execution> - Execution instance

Example:

const execution = await workflow.execute({
  userId: "u123",
  amount: 100
});

workflow.deploy()

Deploys the workflow to Motia.

workflow.deploy(): Promise<void>

Returns: Promise<void>

Example:

await workflow.deploy();

StepHandler

Step handler function signature:

type StepHandler = (ctx: StepContext) => Promise<StepDecision>;

StepContext:

interface StepContext {
  input: any;                    // Workflow input
  state: Record<string, any>;    // State from previous steps
  memory: MemoryInterface;       // Memory interface
}

StepDecision:

interface StepDecision {
  decision: string;              // Required
  reason: string;                // Required
  confidence?: number;           // Optional (0-1)
  metadata?: Record<string, any>; // Optional
}

Complete Example

import { Workflow } from "@mdwr/sdk";

const workflow = Workflow.create("my_workflow_v1")
  .step("validate", async (ctx) => {
    if (!ctx.input.userId) {
      return {
        decision: "reject",
        reason: "Missing userId",
        confidence: 1.0
      };
    }
    
    return {
      decision: "approve",
      reason: "Validation passed",
      confidence: 0.9
    };
  }, true)
  .step("process", async (ctx) => {
    if (ctx.state.validate?.decision !== "approve") {
      return {
        decision: "skip",
        reason: "Validation failed",
        confidence: 1.0
      };
    }
    
    return {
      decision: "completed",
      reason: "Processing completed",
      confidence: 1.0
    };
  }, true);

// Deploy
await workflow.deploy();

// Execute
const execution = await workflow.execute({ userId: "u123" });

Next Steps

• Execution API - Execution methods
• Memory API - Memory interface
• Examples - Real-world examples