@bernierllc/chat-agent-flow-executor

Conversation flow execution engine for chat agents that processes decision trees, actions, conditions, and escalations in a structured workflow format compatible with generic-workflow-ui.

Installation

npm install @bernierllc/chat-agent-flow-executor

Usage

Basic Flow Execution

import { FlowExecutor, FlowDefinition } from '@bernierllc/chat-agent-flow-executor';

const executor = new FlowExecutor();

// Define a simple flow
const flow: FlowDefinition = {
  id: 'support-flow',
  name: 'Customer Support Flow',
  startNodeId: 'classify',
  nodes: [
    {
      id: 'classify',
      type: 'decision',
      label: 'Classify Request',
      parameters: {
        decisionType: 'support_vs_feature'
      },
      next: {
        support: 'handle-support',
        feature: 'handle-feature'
      }
    },
    {
      id: 'handle-support',
      type: 'action',
      label: 'Handle Support Request',
      parameters: {
        actionType: 'call_ai',
        prompt: 'Provide support for the customer issue'
      }
    },
    {
      id: 'handle-feature',
      type: 'action',
      label: 'Handle Feature Request',
      parameters: {
        actionType: 'set_variable',
        parameters: {
          requestType: 'feature',
          status: 'logged'
        }
      }
    }
  ]
};

// Register and execute
executor.registerFlow(flow);
const result = executor.executeFlow('support-flow');

console.log(result.success); // true
console.log(result.context.history); // Execution history

Decision Nodes

Decision nodes route the flow based on AI-powered decisions:

{
  type: 'decision',
  parameters: {
    decisionType: 'support_vs_feature' | 'route_vs_handle' | 'escalate_vs_continue'
  },
  next: {
    support: 'support-node-id',
    feature: 'feature-node-id'
  }
}

Action Nodes

Action nodes perform operations and modify context:

// Set variables
{
  type: 'action',
  parameters: {
    actionType: 'set_variable',
    parameters: {
      key: 'value'
    }
  }
}

// Call AI service
{
  type: 'action',
  parameters: {
    actionType: 'call_ai',
    prompt: 'Generate a response'
  }
}

// Access MCP tools
{
  type: 'action',
  parameters: {
    actionType: 'access_mcp',
    toolName: 'search',
    parameters: { query: 'documentation' }
  }
}

// Query RAG system
{
  type: 'action',
  parameters: {
    actionType: 'query_rag',
    prompt: 'Find relevant context'
  }
}

Condition Nodes

Condition nodes evaluate expressions and branch accordingly:

// Variable condition
{
  type: 'condition',
  parameters: {
    variable: 'isAuthenticated'
  },
  next: {
    true: 'authenticated-path',
    false: 'login-path'
  }
}

// Expression condition
{
  type: 'condition',
  parameters: {
    expression: 'userRole == admin'
  },
  next: {
    true: 'admin-panel',
    false: 'user-panel'
  }
}

// Function condition
{
  type: 'condition',
  parameters: {
    function: 'hasError'
  },
  next: {
    true: 'error-handler',
    false: 'continue'
  }
}

Escalation Nodes

Escalation nodes transfer control to human operators or supervisors:

{
  type: 'escalation',
  parameters: {
    escalationType: 'human_handoff' | 'supervisor' | 'emergency',
    reason: 'Complex issue requiring human attention'
  }
}

API Reference

FlowExecutor

Methods

• registerFlow(flow: FlowDefinition): void - Register a flow for execution
• executeFlow(flowId: string, initialVariables?: Record<string, JsonValue>): FlowExecutionResult - Execute a registered flow
• getFlow(flowId: string): FlowDefinition | undefined - Get a registered flow by ID
• hasFlow(flowId: string): boolean - Check if a flow is registered
• getFlowIds(): string[] - Get all registered flow IDs

FlowValidator

Methods

• validate(flow: FlowDefinition): FlowValidationResult - Validate a flow definition

Validates:

• Flow structure (required fields, node connectivity)
• Circular reference detection
• Orphaned node detection
• Next node reference validity

Type Definitions

FlowDefinition

interface FlowDefinition {
  id: string;
  name: string;
  description?: string;
  version?: string;
  nodes: FlowNode[];
  startNodeId: string;
}

FlowNode

interface FlowNode {
  id: string;
  type: 'decision' | 'action' | 'condition' | 'escalation';
  label: string;
  parameters?: NodeParameters;
  next?: string | Record<string, string>;
}

ExecutionContext

interface ExecutionContext {
  flowId: string;
  currentNodeId: string;
  variables: Record<string, JsonValue>;
  history: ExecutionHistoryEntry[];
  metadata?: JsonObject;
}

Examples

Multi-Step Workflow

const complexFlow: FlowDefinition = {
  id: 'user-onboarding',
  name: 'User Onboarding Flow',
  startNodeId: 'check-auth',
  nodes: [
    {
      id: 'check-auth',
      type: 'condition',
      label: 'Check Authentication',
      parameters: { variable: 'authenticated' },
      next: {
        true: 'welcome',
        false: 'login'
      }
    },
    {
      id: 'login',
      type: 'action',
      label: 'Authenticate User',
      parameters: {
        actionType: 'call_ai',
        prompt: 'Guide user through authentication'
      },
      next: 'set-auth'
    },
    {
      id: 'set-auth',
      type: 'action',
      label: 'Mark Authenticated',
      parameters: {
        actionType: 'set_variable',
        parameters: { authenticated: true }
      },
      next: 'welcome'
    },
    {
      id: 'welcome',
      type: 'action',
      label: 'Welcome Message',
      parameters: {
        actionType: 'call_ai',
        prompt: 'Send personalized welcome message'
      }
    }
  ]
};

executor.registerFlow(complexFlow);
const result = executor.executeFlow('user-onboarding', { userId: '123' });

Error Handling with Escalation

const errorFlow: FlowDefinition = {
  id: 'error-handler',
  name: 'Error Handling Flow',
  startNodeId: 'check-error',
  nodes: [
    {
      id: 'check-error',
      type: 'condition',
      label: 'Check for Errors',
      parameters: { function: 'hasError' },
      next: {
        true: 'classify-error',
        false: 'continue-normal'
      }
    },
    {
      id: 'classify-error',
      type: 'decision',
      label: 'Classify Error Severity',
      parameters: { decisionType: 'escalate_vs_continue' },
      next: {
        escalate: 'escalate-emergency',
        continue: 'auto-resolve'
      }
    },
    {
      id: 'escalate-emergency',
      type: 'escalation',
      label: 'Emergency Escalation',
      parameters: {
        escalationType: 'emergency',
        reason: 'Critical system error detected'
      }
    },
    {
      id: 'auto-resolve',
      type: 'action',
      label: 'Attempt Auto-Resolution',
      parameters: {
        actionType: 'call_ai',
        prompt: 'Suggest resolution steps'
      }
    },
    {
      id: 'continue-normal',
      type: 'action',
      label: 'Continue Normal Flow',
      parameters: {
        actionType: 'set_variable',
        parameters: { status: 'normal' }
      }
    }
  ]
};

Integration Status

• Logger Integration: Not applicable - Core flow execution package with no external dependencies
• NeverHub Integration: Not applicable - Pure execution engine with no service discovery requirements
• Docs-Suite: Ready - Complete markdown documentation with TypeScript API types

This is a standalone core package that provides pure flow execution logic without external integrations.

Quality Metrics

• Test Coverage: 96%+ across all metrics
• Type Safety: Strict TypeScript with zero any types
• Validation: Complete flow validation before execution
• Error Handling: Graceful failure with detailed error messages

License

Copyright (c) 2025 Bernier LLC. All rights reserved.