@verydia/workflow-core

TypeScript-first workflow execution engine for building production-grade AI agent systems

Part of the Verydia framework — a modern, modular TypeScript framework for building real production agentic systems.

🚀 What is workflow-core?

@verydia/workflow-core is the foundational workflow execution engine for Verydia. It provides:

• Declarative Workflow DSL — Define workflows as JSON/YAML with branching, parallelism, and subworkflows
• Type-Safe Execution — Full TypeScript types with Zod validation
• Agent Orchestration — First-class support for LLM-powered agents, RAG, and memory nodes
• Production-Ready — Built-in telemetry, error handling, and observability
• Framework-Agnostic — Works with any LLM provider or agent framework

📦 Installation

npm install @verydia/workflow-core

Or with other Verydia packages:

npm install @verydia/workflow-core @verydia/runtime-public @verydia/schema-core

🎯 Quick Start

Basic Workflow

import { createWorkflow, WorkflowNode } from '@verydia/workflow-core';

// Define workflow nodes
const nodes: WorkflowNode[] = [
  {
    id: 'start',
    type: 'agent',
    config: {
      agentId: 'classifier',
      prompt: 'Classify this input'
    },
    next: 'process'
  },
  {
    id: 'process',
    type: 'agent',
    config: {
      agentId: 'processor',
      prompt: 'Process the classified input'
    }
  }
];

// Create and execute workflow
const workflow = createWorkflow({
  id: 'my-workflow',
  nodes,
  startNode: 'start'
});

const result = await workflow.execute({
  input: { text: 'Hello, world!' }
});

console.log(result.output);

Workflow with Branching

import { createWorkflow } from '@verydia/workflow-core';

const workflow = createWorkflow({
  id: 'branching-workflow',
  nodes: [
    {
      id: 'classify',
      type: 'branch',
      config: {
        condition: (context) => context.score > 0.7,
        trueBranch: 'expert-handler',
        falseBranch: 'simple-handler'
      }
    },
    {
      id: 'expert-handler',
      type: 'agent',
      config: { agentId: 'expert' }
    },
    {
      id: 'simple-handler',
      type: 'agent',
      config: { agentId: 'simple' }
    }
  ],
  startNode: 'classify'
});

Parallel Execution

const workflow = createWorkflow({
  id: 'parallel-workflow',
  nodes: [
    {
      id: 'parallel-start',
      type: 'parallel',
      config: {
        branches: ['task-a', 'task-b', 'task-c']
      },
      next: 'merge'
    },
    {
      id: 'task-a',
      type: 'agent',
      config: { agentId: 'agent-a' }
    },
    {
      id: 'task-b',
      type: 'agent',
      config: { agentId: 'agent-b' }
    },
    {
      id: 'task-c',
      type: 'agent',
      config: { agentId: 'agent-c' }
    },
    {
      id: 'merge',
      type: 'merge',
      config: {
        strategy: 'combine'
      }
    }
  ],
  startNode: 'parallel-start'
});

🧩 Core Concepts

Workflow Nodes

Workflow-core supports multiple node types:

• agent — Execute an LLM-powered agent
• branch — Conditional branching based on context
• parallel — Execute multiple branches concurrently
• merge — Combine results from parallel branches
• rag — Retrieval-augmented generation
• memory — Store and retrieve context
• subworkflow — Nest workflows within workflows

Execution Context

Every node receives an execution context:

interface WorkflowContext {
  input: any;           // Initial workflow input
  state: any;           // Mutable workflow state
  metadata: any;        // Workflow metadata
  previousOutput: any;  // Output from previous node
}

Error Handling

Built-in error handling with retry logic:

const workflow = createWorkflow({
  id: 'resilient-workflow',
  nodes: [...],
  config: {
    errorHandling: {
      retryAttempts: 3,
      retryDelay: 1000,
      fallbackNode: 'error-handler'
    }
  }
});

🔧 Advanced Features

Telemetry Integration

Workflow-core emits telemetry events automatically:

import { createWorkflow } from '@verydia/workflow-core';
import { createTelemetryCollector } from '@verydia/telemetry-core';

const telemetry = createTelemetryCollector();

const workflow = createWorkflow({
  id: 'monitored-workflow',
  nodes: [...],
  telemetry
});

// Events are automatically emitted:
// - workflow.started
// - node.executed
// - workflow.completed
// - workflow.failed

State Management

Persist and restore workflow state:

const workflow = createWorkflow({
  id: 'stateful-workflow',
  nodes: [...],
  config: {
    stateManagement: {
      enabled: true,
      storage: 'memory' // or 'redis', 'postgres'
    }
  }
});

// Save checkpoint
const checkpoint = await workflow.saveCheckpoint();

// Restore from checkpoint
await workflow.restoreCheckpoint(checkpoint);

Custom Node Types

Extend workflow-core with custom node types:

import { registerNodeType } from '@verydia/workflow-core';

registerNodeType('custom', async (node, context) => {
  // Your custom logic here
  return {
    output: 'custom result',
    nextNode: node.next
  };
});

📚 API Reference

createWorkflow(config)

Creates a new workflow instance.

Parameters:

• config.id (string) — Unique workflow identifier
• config.nodes (WorkflowNode[]) — Array of workflow nodes
• config.startNode (string) — ID of the starting node
• config.telemetry (optional) — Telemetry collector instance
• config.config (optional) — Additional workflow configuration

Returns: Workflow instance

workflow.execute(input)

Executes the workflow with the given input.

Parameters:

• input (any) — Initial workflow input

Returns: Promise<WorkflowResult>

workflow.validate()

Validates the workflow structure.

Returns: ValidationResult

🏗 Architecture

Workflow-core is designed as a layered system:

┌─────────────────────────────────────┐
│   Workflow DSL (JSON/YAML)         │
└─────────────────────────────────────┘
                ↓
┌─────────────────────────────────────┐
│   Workflow Compiler                 │
└─────────────────────────────────────┘
                ↓
┌─────────────────────────────────────┐
│   Execution Engine (workflow-core)  │
└─────────────────────────────────────┘
                ↓
┌─────────────────────────────────────┐
│   Runtime & Telemetry               │
└─────────────────────────────────────┘

🔗 Related Packages

• @verydia/workflow-runtime — High-level workflow runtime with agent integration
• @verydia/workflow-dsl — JSON/YAML workflow definition language
• @verydia/runtime-public — Core runtime primitives
• @verydia/schema-core — Type system and validation

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting changes.

📄 License

Apache-2.0

🆘 Support

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Email: [email protected]

🌟 Why Verydia?

Verydia is the only OSS agentic framework that ships with:

• ✅ TypeScript-first — Full type safety and inference
• ✅ Workflow as Data — Declarative JSON/YAML workflows
• ✅ Built-in Governance — Safety evaluation, compliance, decision logs
• ✅ Production Observability — Telemetry, traces, and insights
• ✅ Framework-Agnostic — Works with any LLM provider