DEV Community: Muhammad Arslan

Building Reliable AI in NodeJS with Typescript

Muhammad Arslan — Tue, 14 Apr 2026 12:36:21 +0000

If you are shipping AI features, quality can drift silently. A model update, prompt tweak, or retrieval change can lower answer quality without obvious runtime errors.

@hazeljs/eval gives you a practical way to measure that quality with:

Golden datasets
Retrieval metrics (precision@k, recall@k, MRR, NDCG)
Agent trajectory scoring
CI-ready pass/fail reporting

This starter explains how the package works and includes a real-time evaluation example you can run locally.

What `@hazeljs/eval` Solves

@hazeljs/eval is an evaluation toolkit for HazelJS AI applications. You can use it to:

Define expected behavior as golden test cases.
Run your RAG/agent pipeline against those cases.
Score retrieval and response quality.
Fail CI when quality drops below your threshold.

That makes AI quality regression-testable, not guesswork.

Install

npm install @hazeljs/eval @hazeljs/core

Core APIs (Quick Overview)

loadGoldenDatasetFromJson(path): load dataset from JSON.
runGoldenDataset(dataset, runner, options): execute all cases and aggregate scores.
evaluateRetrieval(...): retrieval quality metrics.
answerContextOverlap(...): quick answer-context overlap heuristic.
reportEvalForCi(result, { exitOnFail: true }): CI-friendly reporting.

Real-Time Example: Evaluate Live Support Responses

In this example, we simulate incoming support events and score them in real time.
Every incoming event is evaluated for:

Retrieval quality (precision@k, recall@k, MRR, NDCG)
Answer-context overlap

Suggested project structure

hazeljs-eval-starter/
  package.json
  tsconfig.json
  src/
    realtime-eval.ts
  eval/
    golden.realtime.json

`package.json`

{
  "name": "hazeljs-eval-starter",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx src/realtime-eval.ts"
  },
  "dependencies": {
    "@hazeljs/core": "latest",
    "@hazeljs/eval": "latest"
  },
  "devDependencies": {
    "tsx": "^4.20.0",
    "typescript": "^5.8.0"
  }
}

`tsconfig.json`

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

`eval/golden.realtime.json`

{
  "name": "realtime-support",
  "version": "1.0.0",
  "cases": [
    {
      "id": "billing-01",
      "input": "When will I be charged?",
      "expectedRetrievedIds": ["billing-policy", "pricing-page"]
    },
    {
      "id": "refund-01",
      "input": "Can I get a refund after 20 days?",
      "expectedRetrievedIds": ["refund-policy"]
    }
  ]
}

`src/realtime-eval.ts`

import { EventEmitter } from 'node:events';
import {
  answerContextOverlap,
  evaluateRetrieval,
  loadGoldenDatasetFromJson,
  reportEvalForCi,
  runGoldenDataset,
} from '@hazeljs/eval';

type LiveInference = {
  output: string;
  retrievedIds: string[];
  contexts: string[];
};

const stream = new EventEmitter();
const rollingWindow: number[] = [];
const MAX_WINDOW = 20;

function pushScore(score: number) {
  rollingWindow.push(score);
  if (rollingWindow.length > MAX_WINDOW) rollingWindow.shift();
}

function windowAverage(): number {
  if (rollingWindow.length === 0) return 0;
  return rollingWindow.reduce((a, b) => a + b, 0) / rollingWindow.length;
}

async function fakeRagAnswer(input: string): Promise<LiveInference> {
  if (input.toLowerCase().includes('refund')) {
    return {
      output: 'Yes, refunds are available within 30 days of purchase.',
      retrievedIds: ['refund-policy', 'terms-page'],
      contexts: [
        'Refunds are available within 30 days of purchase.',
        'Terms and conditions apply for enterprise plans.'
      ]
    };
  }

  return {
    output: 'You are charged on the first day of each month.',
    retrievedIds: ['billing-policy', 'pricing-page'],
    contexts: [
      'Billing occurs monthly, on the first day of each month.',
      'Pricing details are listed on the public pricing page.'
    ]
  };
}

async function handleLiveEvent(input: string, relevantIds: string[]) {
  const result = await fakeRagAnswer(input);

  const retrieval = evaluateRetrieval({
    query: input,
    retrievedIds: result.retrievedIds,
    relevantIds,
    k: 5,
  });

  const overlap = answerContextOverlap(result.output, result.contexts);
  const liveScore = (retrieval.ndcgAtK + overlap) / 2;
  pushScore(liveScore);

  console.log('--- live event ---');
  console.log('input:', input);
  console.log('retrievedIds:', result.retrievedIds.join(', '));
  console.log('precision@k:', retrieval.precisionAtK.toFixed(3));
  console.log('recall@k:', retrieval.recallAtK.toFixed(3));
  console.log('mrr:', retrieval.mrr.toFixed(3));
  console.log('ndcg@k:', retrieval.ndcgAtK.toFixed(3));
  console.log('answer overlap:', overlap.toFixed(3));
  console.log('rolling quality score:', windowAverage().toFixed(3));
}

async function runBaselineGoldenEval() {
  const dataset = loadGoldenDatasetFromJson('./eval/golden.realtime.json');
  const evalResult = await runGoldenDataset(
    dataset,
    async ({ input }) => {
      const output = await fakeRagAnswer(input);
      return {
        output: output.output,
        retrievedIds: output.retrievedIds,
      };
    },
    { concurrency: 1, minAverageScore: 0.7 }
  );

  reportEvalForCi(evalResult, { exitOnFail: false });
}

async function main() {
  console.log('Starting baseline golden eval...');
  await runBaselineGoldenEval();

  stream.on('support-query', async (payload: { input: string; relevantIds: string[] }) => {
    await handleLiveEvent(payload.input, payload.relevantIds);
  });

  // Simulate real-time production traffic.
  setInterval(() => {
    const events = [
      { input: 'When will I be charged?', relevantIds: ['billing-policy', 'pricing-page'] },
      { input: 'Can I get a refund after 20 days?', relevantIds: ['refund-policy'] },
    ];
    const next = events[Math.floor(Math.random() * events.length)];
    stream.emit('support-query', next);
  }, 3000);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run It

npm install
npm run dev

You will see:

A baseline golden dataset evaluation summary at startup.
Ongoing real-time event-by-event quality metrics every few seconds.
A rolling quality score you can alert on in production.

Real-Life Example: SaaS Support Bot in Production

Here is a practical pattern used by AI teams:

You run a HazelJS support bot for billing/refund questions.
Every new production conversation is evaluated right after inference.
If rolling quality drops below a threshold, you alert Slack and block new rollouts.
Nightly golden dataset runs enforce a CI quality gate.

Install extra packages for this real setup

npm install @hazeljs/ai @hazeljs/rag

`src/real-life-support-eval.ts`

import { EventEmitter } from 'node:events';
import { HazelAI } from '@hazeljs/ai';
import {
  answerContextOverlap,
  evaluateRetrieval,
  loadGoldenDatasetFromJson,
  reportEvalForCi,
  runGoldenDataset,
} from '@hazeljs/eval';

type SupportEvent = {
  ticketId: string;
  userQuestion: string;
  relevantDocIds: string[];
};

const liveBus = new EventEmitter();
const rollingScores: number[] = [];
const ROLLING_WINDOW = 50;
const ALERT_THRESHOLD = 0.62;

function pushRollingScore(score: number) {
  rollingScores.push(score);
  if (rollingScores.length > ROLLING_WINDOW) rollingScores.shift();
}

function getRollingAverage() {
  if (rollingScores.length === 0) return 0;
  return rollingScores.reduce((sum, score) => sum + score, 0) / rollingScores.length;
}

async function evaluateLiveSupportEvent(ai: ReturnType<typeof HazelAI.create>, event: SupportEvent) {
  const rag = await ai.rag.ask(event.userQuestion, { topK: 6 });
  const retrievedIds = rag.sources.map((source) => source.id);

  const retrieval = evaluateRetrieval({
    query: event.userQuestion,
    retrievedIds,
    relevantIds: event.relevantDocIds,
    k: 6,
  });

  const overlap = answerContextOverlap(
    rag.answer,
    rag.sources.map((source) => source.text),
  );

  const qualityScore = (retrieval.ndcgAtK + overlap) / 2;
  pushRollingScore(qualityScore);

  const rollingAverage = getRollingAverage();
  console.log(`[ticket=${event.ticketId}] score=${qualityScore.toFixed(3)} rolling=${rollingAverage.toFixed(3)}`);

  if (rollingAverage < ALERT_THRESHOLD) {
    // Replace with Slack/PagerDuty webhook in production.
    console.warn(`ALERT: rolling support quality dropped below ${ALERT_THRESHOLD}`);
  }
}

async function runNightlyGoldenEval(ai: ReturnType<typeof HazelAI.create>) {
  const dataset = loadGoldenDatasetFromJson('./eval/golden.realtime.json');

  const result = await runGoldenDataset(
    dataset,
    async ({ input }) => {
      const rag = await ai.rag.ask(input, { topK: 6 });
      return {
        output: rag.answer,
        retrievedIds: rag.sources.map((source) => source.id),
      };
    },
    { concurrency: 2, minAverageScore: 0.7 },
  );

  reportEvalForCi(result, { exitOnFail: process.env.CI === 'true' });
}

async function main() {
  const ai = HazelAI.create({
    defaultProvider: 'openai',
    persistence: {
      rag: {
        vectorStore: 'qdrant',
        connectionString: process.env.QDRANT_URL ?? 'http://127.0.0.1:6333',
        indexName: 'support-docs',
      },
    },
  });

  await runNightlyGoldenEval(ai);

  liveBus.on('support_ticket_answered', async (event: SupportEvent) => {
    await evaluateLiveSupportEvent(ai, event);
  });

  // Simulated production events from your message queue / webhook.
  setInterval(() => {
    const sampleEvents: SupportEvent[] = [
      {
        ticketId: 'T-1001',
        userQuestion: 'Am I charged on the first day of the month?',
        relevantDocIds: ['billing-policy', 'pricing-page'],
      },
      {
        ticketId: 'T-1002',
        userQuestion: 'Can I request refund after 20 days?',
        relevantDocIds: ['refund-policy'],
      },
    ];
    const next = sampleEvents[Math.floor(Math.random() * sampleEvents.length)];
    liveBus.emit('support_ticket_answered', next);
  }, 4000);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Environment variables for real integrations

export OPENAI_API_KEY=your_key_here
export QDRANT_URL=http://127.0.0.1:6333

Why this is "real life"

Uses live retrieval results from your actual vector index.
Scores each production response continuously.
Adds rolling quality alerting for operations.
Keeps CI quality gates with reportEvalForCi.

Why This Pattern Works

Golden datasets protect against regressions before deploy.
Real-time metrics monitor quality after deploy.
CI thresholds let you enforce quality gates automatically.

If you want, the next step is to connect this starter to your actual HazelJS app (HazelAI + real vector store) so the same evaluator runs on true production responses.

Introducing @hazeljs/pubsub: Google Cloud Messaging, HazelJS Style

Muhammad Arslan — Mon, 06 Apr 2026 08:15:32 +0000

We shipped @hazeljs/pubsub to make Google Cloud Pub/Sub feel native inside HazelJS applications.

If your team already runs on GCP, Pub/Sub usually becomes the backbone for async communication. But most app code ends up repeating the same integration work: wiring clients, parsing payloads, handling ack/nack, and registering handlers with slightly different conventions in every service.

This package turns that into a consistent HazelJS module + decorator experience.

TL;DR

Use @hazeljs/pubsub to publish/consume Pub/Sub messages in HazelJS with less boilerplate.
You get a DI-friendly publisher service, decorator-based consumers, and explicit acknowledgement control.
It helps teams standardize event-driven code across multiple services.

Why we built it

We built this package because we kept seeing the same pain points in event-driven Node.js services:

Too much repeated plumbing

Every service re-implements Pub/Sub initialization and subscription handling.
Inconsistent handler behavior

Some handlers auto-ack, some forget to nack, some swallow errors, and reliability suffers.
Leaky transport concerns in business code

Product logic gets mixed with low-level broker/client setup.
Harder onboarding

New developers need to learn each service’s custom Pub/Sub pattern instead of one framework pattern.

HazelJS already gives a clean, declarative style for modules, providers, and decorators. Pub/Sub should follow the same principle.

Purpose of @hazeljs/pubsub

The purpose is simple: make Pub/Sub integration predictable, testable, and framework-native.

@hazeljs/pubsub gives you:

a single module entrypoint (PubSubModule.forRoot / forRootAsync)
one publisher service (PubSubPublisherService)
declarative consumers (@PubSubConsumer + @PubSubSubscribe)
clear acknowledgement behavior (ackOnSuccess, nackOnError, plus manual ack()/nack())

So instead of each service inventing its own event-consumer framework, your team uses one shared pattern.

What problems it solves

1) Boilerplate client setup

Without a package abstraction, every service manually creates and passes Pub/Sub clients.

With PubSubModule, setup is centralized and DI-ready.

2) Message handling drift

Ack/nack logic is usually spread across handlers and easy to get wrong.

With @PubSubConsumer + @PubSubSubscribe, defaults are explicit and overrideable.

3) Payload parsing repetition

Teams repeatedly decode and parse message payloads.

With package defaults, JSON parsing and handler payload typing are built in.

4) Uneven production behavior

Operationally, small differences in handler semantics lead to retries, duplicates, or dropped work.

Standardized patterns reduce those surprises.

What’s in the box

PubSubModule

Configure once with forRoot() or forRootAsync() and use everywhere via DI.

PubSubPublisherService

Publish events from your controllers/services:

publish(topic, data, options?) for string/buffer/object payloads
publishJson(topic, data, options?) for JSON-first workflows

Decorator-based consumers

Define consumers declaratively:

@PubSubConsumer({...defaults}) at class level
@PubSubSubscribe({...}) at method level

Acknowledgement controls

Use defaults (ackOnSuccess, nackOnError) or control each message explicitly:

return 'ack' | 'nack'
call payload.ack() / payload.nack()

Optional subscription auto-create

Enable autoCreateSubscription for bootstrap convenience when topic is provided.

Practical example: Order workflow fan-out

A common SaaS pattern:

API creates an order.
API publishes an order.created event.
Multiple consumers react independently:
- billing creates invoice
- notification sends confirmation email
- analytics tracks conversion event

This decouples services while keeping each handler focused.

Producer

@Service()
export class OrderService {
  constructor(private readonly publisher: PubSubPublisherService) {}

  async createOrder(order: { id: string; userId: string; total: number }) {
    // Persist order first...
    await this.publisher.publishJson('orders-topic', order, {
      attributes: {
        event: 'order.created',
        source: 'order-service',
      },
      orderingKey: order.id,
    });
  }
}

Consumer

@PubSubConsumer({ ackOnSuccess: true, nackOnError: true, parseJson: true })
@Service()
export class BillingConsumer {
  @PubSubSubscribe({
    subscription: 'billing-orders-subscription',
    topic: 'orders-topic',
    autoCreateSubscription: true,
  })
  async handleOrder(
    payload: PubSubSubscriptionHandlerPayload<{ id: string; userId: string; total: number }>
  ) {
    // idempotency check recommended
    // create invoice, emit internal metrics, etc.
  }
}

Quick start

Install:

npm install @hazeljs/pubsub

@HazelModule({
  imports: [
    PubSubModule.forRoot({
      projectId: process.env.GCP_PROJECT_ID,
    }),
  ],
})
export class AppModule {}

Pub/Sub vs Queue vs Kafka

Use @hazeljs/pubsub when you’re on GCP and want managed Pub/Sub semantics.
Use @hazeljs/queue for Redis/BullMQ background job processing.
Use @hazeljs/kafka when Kafka is your streaming/event backbone.

Production notes

Keep handlers idempotent (at-least-once delivery can reprocess messages).
Attach correlation IDs in message attributes for tracing/debugging.
Monitor nack/error rates for early schema/runtime regressions.
Plan retry + dead-letter strategy at the platform level.
Keep handlers fast and offload heavy work when needed.

Backlinks and resources

PubSub docs: PubSub Docs
NPM: @hazeljs/pubsub
GitHub monorepo: HazelJS Github
Landing docs root: HazelJS Docs

If you’re building event-driven systems on GCP with HazelJS, try it and share feedback via GitHub issues or Discord.

Introducing HCEL: The Most Fluent Way to Build AI Pipelines in TypeScript

Muhammad Arslan — Wed, 01 Apr 2026 13:11:06 +0000

In the rapidly evolving landscape of AI development, orchestration is everything. As developers move from simple LLM calls to complex, multi-step agentic workflows, the need for a clean, expressive, and type-safe way to define these pipelines becomes critical.

Today, we are excited to introduce HCEL (HazelJS Composable Expression Language)—a fluent, TypeScript-native DSL designed to make AI orchestration as intuitive as a standard functional chain.

What is HCEL?

HCEL stands for HazelJS Composable Expression Language. It is not a separate language you need to learn, but a fluent API provided by the @hazeljs/ai package. It allows you to "chain" together different AI capabilities—prompts, RAG searches, agents, and machine learning models—into a single, executable pipeline.

Why HCEL?

Traditional AI pipelines often suffer from "pyramid of doom" callback structures or messy async/await boilerplate for passing state between steps. HCEL solves this by providing:

Fluent Method Chaining: Build complex logic step-by-step.
Implicit Context Passing: The output of operation A automatically becomes the input for operation B.
Observability by Default: Every step in the chain is automatically traced and timed.
Flow Integration: Easily convert any HCEL chain into a durable @hazeljs/flow node.

Real-World Examples from Our Codebase

Let's explore actual working examples from our @hazeljs/ai/examples directory that demonstrate HCEL in action.

Example 1: Simple HCEL Chain

From hcel-demo.ts:

// Simple HCEL Chain
const simpleResult = await ai.hazel
  .prompt('What is HazelJS?')
  .execute() as string;

console.log(`Result: ${simpleResult.slice(0, 100)}...`);

What's happening here?

We start with ai.hazel - the entry point for HCEL chains
.prompt() creates a text generation operation
.execute() runs the entire chain and returns the result
The result is automatically typed as string thanks to TypeScript inference

Example 2: RAG + ML Chain

From hcel-demo.ts:

// RAG + ML Chain
const ragMlResult = await ai.hazel
  .rag('docs')                    // Search documentation
  .ml('sentiment')                // Analyze sentiment
  .execute() as SentimentResult;

console.log(`Sentiment: ${ragMlResult.sentiment} (${ragMlResult.score})`);

What's happening here?

.rag('docs') searches your documentation for relevant context
The RAG result is automatically passed to the next step
.ml('sentiment') runs sentiment analysis on the RAG output
The final result includes both sentiment and confidence score

Example 3: Streaming Chain

From hcel-demo.ts:

// Streaming Chain
console.log('Assistant: ');
for await (const chunk of ai.hazel
  .prompt('Tell me a short story about AI and creativity')
  .stream()) {
  process.stdout.write(chunk as string);
}

What's happening here?

.stream() instead of .execute() enables real-time streaming
Perfect for chat interfaces or long-running generations
Each chunk is processed as it arrives from the AI provider

Example 4: Chain with Context & Observability

From hcel-demo.ts:

const contextChain = ai.hazel
  .prompt('Analyze this user feedback: {feedback}')
  .ml('sentiment')
  .context({ userId: 'user-123', sessionId: 'session-456' })
  .observe((event) => {
    console.log(`📡 Event: ${event.type} at ${new Date(event.timestamp).toISOString()}`);
  });

const contextResult = await contextChain.execute() as SentimentResult;

What's happening here?

.context() adds metadata that flows through the entire chain
.observe() hooks into every operation for logging and monitoring
Perfect for debugging and production observability

Production-Ready Features

HCEL isn't just for demos—it's built for production workloads. Let's look at our production example:

Example 5: Persistent HCEL Chains

From hcel-production-demo.ts:

// Production HazelAI with Persistence Configuration
const ai = HazelAI.create({
  defaultProvider: 'openai',
  model: 'gpt-4o',
  temperature: 0.7,

  // Production persistence configuration
  persistence: {
    memory: {
      store: 'in-memory', // Change to 'postgres' or 'redis' for production
      ttl: 3600, // 1 hour
    },
    rag: {
      vectorStore: 'in-memory', // Change to 'pinecone', 'qdrant', etc. for production
      options: {
        topK: 5,
        chunkSize: 1000,
        chunkOverlap: 200,
      }
    },
    chains: {
      store: 'in-memory', // Change to 'postgres' or 'redis' for production
      ttl: 7200, // 2 hours
    }
  }
});

// Create a persistent analysis chain
const analysisChain = ai.hazel
  .prompt('Analyze user feedback: This product is amazing! It works perfectly.')
  .persist('user-feedback-analysis') // Persist this chain
  .cache(1800); // Cache results for 30 minutes

const result = await analysisChain.execute();

Production Features:

Persistence: Chain state is automatically saved to Redis/Postgres
Caching: Results are cached to avoid redundant API calls
Configuration: Production-ready settings for stores and TTLs

Example 6: Parallel Operations

From hcel-demo.ts:

// Parallel Operations
const parallelChain = ai.hazel
  .parallel(
    ai.hazel.prompt('Summarize: "AI is transforming the world"'),
    ai.hazel.ml('sentiment', { labels: ['positive', 'negative', 'neutral'] })
  );

const parallelResult = await parallelChain.execute();

What's happening here?

.parallel() executes multiple operations simultaneously
Perfect for independent tasks that can run concurrently
Results are collected and returned as an array

Advanced Orchestration Patterns

Example 7: Flow Engine Integration

From hcel-flow-demo.ts:

// HCEL-Flow Bridge - Wraps HCEL chains as Flow Engine nodes
class HCELFlowNode {
  constructor(private chain: any) {}

  async execute(input: unknown): Promise<NodeResult> {
    try {
      const result = await this.chain.execute(input);
      return {
        status: 'ok',
        output: result
      };
    } catch (error) {
      return {
        status: 'error',
        reason: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }
}

// Convert HCEL chain to Flow node
const hcelNode = new HCELFlowNode(
  ai.hazel
    .prompt('Process user request: {{input}}')
    .rag('knowledge-base')
    .agent('support-specialist')
);

What's happening here?

HCEL chains can be wrapped as Flow Engine nodes
Enables durable, long-running workflows with AI steps
Perfect for human-in-the-loop processes and complex business logic

How to Run These Examples

All examples are available in our packages/ai/examples directory:

Setup

# From the packages/ai directory
npm run build

# Set your API key
export OPENAI_API_KEY=your-key-here

Run the Examples

# Basic HCEL demo
node dist/examples/hcel-demo.js

# Production features demo
node dist/examples/hcel-production-demo.js

# Flow integration demo
node dist/examples/hcel-flow-demo.js

What Each Example Demonstrates

hcel-demo.ts - Basic HCEL operations, streaming, parallel execution
hcel-production-demo.ts - Persistence, caching, memory management
hcel-flow-demo.ts - Integration with HazelJS Flow Engine
simple-demo.ts - Works without API keys for testing
unified-platform-example.ts - Complete platform showcase

The Power of Implicit Context

The core magic of HCEL is the Implicit Context. Every step in the builder returns a new state that includes a pipe. The pipe is what transforms the output of Operation N into the input of Operation N+1.

Explicit vs Implicit Context

// ❌ Traditional approach - explicit context passing
const summary = await ai.chat('Summarize: ' + userQuery);
const context = await ai.rag('docs', summary);
const analysis = await ai.agent('analyst', context);

// ✅ HCEL approach - implicit context passing
const result = await ai.hazel
  .prompt('Summarize: {{input}}')
  .rag('docs')
  .agent('analyst')
  .execute(userQuery);

Context Transformation

// Each step transforms the context
const pipeline = ai.hazel
  .prompt('Extract key topics: {{input}}')           // string → string
  .ml('classify', { labels: ['tech', 'business', 'other'] }) // string → ClassificationResult
  .conditional((result) => result.label === 'tech')   // ClassificationResult → boolean
    .prompt('Explain this tech topic: {{input}}')     // ClassificationResult → string
  .execute('AI is revolutionizing software development');

Type Safety and IntelliSense

Because HCEL is built with TypeScript, you get full type safety and IDE support:

// TypeScript knows the return type based on the last operation
const sentimentResult = await ai.hazel
  .prompt('Analyze: {{input}}')
  .ml('sentiment')
  .execute() as SentimentResult; // Type is inferred!

// Get full chain summary with types
const summary = ai.hazel
  .prompt('Test')
  .ml('sentiment')
  .getSummary();

console.log(summary.operations); // ['prompt', 'ml']
console.log(summary.config);     // Chain configuration

Getting Started with HCEL

Installation

npm install @hazeljs/ai @hazeljs/core

Basic Usage

import { HazelAI } from '@hazeljs/ai';

const ai = HazelAI.create({
  defaultProvider: 'openai',
  model: 'gpt-4o'
});

// Your first HCEL chain
const result = await ai.hazel
  .prompt('What is the future of AI?')
  .execute();

Advanced Usage

// Production-ready chain
const pipeline = ai.hazel
  .persist('user-analysis')
  .prompt('Analyze user feedback: {{input}}')
  .rag('product-docs')
  .ml('sentiment')
  .cache(3600)
  .observe((event) => console.log(event));

What's Next?

HCEL is just the beginning. We're working on:

More ML Operations: Classification, extraction, translation
Advanced Flow Patterns: Conditional branching, loops, retries
Enhanced Observability: OpenTelemetry integration, custom metrics
Visual Builder: Web-based HCEL chain designer
Template Library: Pre-built chains for common use cases

Join the HCEL Community

GitHub: hazeljs/hazeljs
Documentation: hazeljs.com/docs
Examples: packages/ai/examples
Discord: Join our developer community

Conclusion

HCEL represents a fundamental shift in how we think about AI orchestration. By providing a fluent, type-safe, and production-ready API, we're making sophisticated AI workflows accessible to every TypeScript developer.

Whether you're building simple chatbots or complex multi-agent systems, HCEL provides the tools you need to compose, observe, and scale your AI operations with confidence.

Try HCEL today and experience the future of AI orchestration in TypeScript! 🚀 in .prompt() tells HCEL exactly where to inject the previous step's result.

Auto-Injection: Operations like .rag() or .agent() automatically use the current context as their search query or instruction if no specific input is provided.

This allows you to focus on the logic, not the data-shuffling boilerplate.

Real-World Case Study: Automated Support Triage

Here is a full implementation of an automated support triage system built with HCEL:

@Service()
export class SupportTriage {
  constructor(private readonly ai: AIEnhancedService) {}

  async handleTicket(ticketText: string) {
    return this.ai.hazel
      .persist('support-triage')
      .ml('sentiment')
      .parallel(
        this.ai.hazel.ml('classify', { categories: ['billing', 'technical', 'sales'] }),
        this.ai.hazel.prompt('Extract product names from: {{input}}')
      )
      .conditional((context) => context.sentiment === 'negative' && context.classification === 'technical')
        .agent('SeniorTechnicalSupport')
      .conditional((context) => context.classification === 'billing')
        .rag('billing-faq')
        .prompt('Answer billing query: {{input}}')
      .execute(ticketText);
  }
}

This single method replaces what would traditionally be dozens of lines of nested if statements, manual RAG lookups, and complex state management.

Try it Today

HCEL is available now in @hazeljs/ai version v0.7.0+.

Whether you are building a simple chat bot or a massively parallel research engine, HCEL provides the expressive power you need without the boilerplate.

Resources:

HCEL Guide — Full API reference and advanced patterns.
AI Package Documentation — Getting started with AI in HazelJS.
Agentic RAG Guide — Learn how to pair HCEL with advanced retrieval strategies.

Happy coding with HazelJS!

AI-Native CLI Template: Build Production-Ready AI Agents in Minutes in NodeJS

Muhammad Arslan — Sun, 29 Mar 2026 17:49:42 +0000

Building AI-powered applications just got dramatically easier. We're excited to introduce the AI-Native CLI Template for HazelJS—a complete, production-ready starter that brings together our most powerful AI and agent capabilities into a single, easy-to-use package.

Whether you're building a customer support bot, an intelligent data analyst, or a complex multi-agent system, this template gives you everything you need to go from idea to production in minutes, not weeks.

Why an AI-Native Template?

The AI landscape is evolving rapidly, and developers need tools that keep pace. Traditional frameworks force you to wire together disparate libraries, manage complex state, and build infrastructure from scratch. The HazelJS AI-Native template eliminates this friction by providing:

Pre-configured AI Integration: OpenAI, Anthropic, and custom LLM support out of the box
Production-Ready Agent System: Multi-agent orchestration with streaming, tracing, and delegation
Complete RAG Pipeline: Vector search, document ingestion, and semantic retrieval
Docker & Deployment Ready: Full containerization with health checks and monitoring
Type-Safe Development: Full TypeScript support with intelligent autocomplete

What's Included?

🤖 Advanced Agent Capabilities

The template showcases HazelJS's powerful @hazeljs/agent package with real-world examples:

1. Execution Tracing (`POST /agent/trace`)

Get complete visibility into your agent's reasoning process with detailed execution traces:

@Agent({ name: 'WeatherAgent', description: 'Weather information agent' })
export class WeatherAgent {
  @Tool({
    description: 'Get current weather for a city',
    parameters: [
      { name: 'city', type: 'string', required: true, description: 'City name' }
    ]
  })
  async getCurrentWeather(input: { city: string }) {
    return {
      city: input.city,
      temperature: 72,
      conditions: 'Sunny',
      humidity: 45
    };
  }
}

The trace endpoint returns a complete breakdown of every step:

{
  "result": "The weather in San Francisco is currently sunny...",
  "steps": [
    {
      "stepNumber": 1,
      "action": { "type": "tool_call", "toolName": "getCurrentWeather" },
      "result": { "city": "San Francisco", "temperature": 72 }
    }
  ]
}

2. Server-Sent Events Streaming (`POST /agent/stream`)

Real-time streaming responses for better UX:

async executeStream(
  @Body() body: { input: string },
  @Res() res: HazelResponse
) {
  res.setHeader('Content-Type', 'text/event-stream');

  for await (const chunk of this.agentService.executeStream(
    'WeatherAgent',
    body.input
  )) {
    res.write(`data: ${JSON.stringify(chunk)}\n\n`);
  }

  res.end();
}

Stream types include:

token: Individual LLM response tokens
step: Complete reasoning steps
done: Execution completion signal

3. Multi-Agent Delegation (`POST /travel`)

Build complex workflows by delegating between specialized agents:

@Agent({ name: 'TravelAgent', description: 'Travel planning assistant' })
export class TravelAgent {
  @Delegate({
    agent: 'WeatherAgent',
    description: 'Get weather information for travel planning'
  })
  async checkWeather(input: { input: string }): Promise<string> {
    return '';  // Implementation handled by @Delegate
  }

  @Delegate({
    agent: 'FactsAgent',
    description: 'Get interesting facts about destinations'
  })
  async getCityFacts(input: { input: string }): Promise<string> {
    return '';
  }
}

The @Delegate decorator automatically:

Routes requests to the appropriate agent
Handles tool registration for LLM visibility
Manages context passing between agents
Provides transparent error handling

4. Supervisor Pattern (`POST /travel/supervisor`)

Let the LLM intelligently route requests to the right agent:

async executeSupervisor(@Body() body: { input: string }) {
  return this.agentService.executeSupervisor(
    body.input,
    ['WeatherAgent', 'FactsAgent'],
    {
      systemPrompt: 'Route travel-related queries to the appropriate agent'
    }
  );
}

The supervisor analyzes the user's intent and automatically selects the best agent for the task.

💬 AI Chat & RAG

Beyond agents, the template includes a complete AI chat system with RAG capabilities:

@Post('chat')
async chat(@Body() body: { message: string; enableRAG?: boolean }) {
  return this.aiService.complete({
    messages: [{ role: 'user', content: body.message }],
    temperature: 0.7,
    maxTokens: 1000
  });
}

RAG Integration (POST /rag/query):

async queryWithRAG(@Body() body: { query: string }) {
  // Semantic search across your knowledge base
  const relevantDocs = await this.ragService.search(body.query, { limit: 5 });

  // Augment LLM context with retrieved documents
  return this.aiService.complete({
    messages: [
      { role: 'system', content: `Context: ${relevantDocs.join('\n')}` },
      { role: 'user', content: body.query }
    ]
  });
}

🐳 Production-Ready Infrastructure

The template includes complete Docker configuration:

Dockerfile with multi-stage builds:

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

docker-compose.yml with PostgreSQL and Redis:

services:
  hazeljs-ai-app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s

📦 Complete Postman Collection

Test all endpoints immediately with the included Postman collection:

Agent execution with tracing
Streaming responses
Multi-agent delegation
Supervisor routing
RAG queries
Standard chat completions

Key Benefits

1. Instant Productivity

npx @hazeljs/cli new my-ai-app --template ai-native
cd my-ai-app
npm install
npm run dev

Your AI application is running in under 2 minutes with:

✅ Multiple working agent examples
✅ Streaming and tracing configured
✅ RAG pipeline ready
✅ Docker deployment files
✅ Health checks and monitoring

2. Learn by Example

Every feature is demonstrated with working code:

WeatherAgent: Simple tool-based agent
FactsAgent: Knowledge retrieval agent
TravelAgent: Multi-agent delegation
Supervisor: Intelligent routing

Copy, modify, and extend these examples for your use case.

3. Production-Grade Architecture

Built on battle-tested HazelJS patterns:

Type Safety: Full TypeScript with strict mode
Error Handling: Comprehensive error boundaries
Logging: Structured logging with log levels
Health Checks: Kubernetes-ready health endpoints
Graceful Shutdown: Proper cleanup on termination

4. Scalable from Day One

Start simple, scale when needed:

Local Development: SQLite for quick iteration
Production: PostgreSQL with connection pooling
Caching: Redis for session and vector storage
Horizontal Scaling: Stateless design for easy replication

5. Comprehensive Testing

The agent package includes 439 tests with 74.52% branch coverage, ensuring reliability:

Unit tests for all agent features
Integration tests for multi-agent workflows
Streaming and tracing validation
Error scenario coverage

Real-World Use Cases

Customer Support Bot

@Agent({ name: 'SupportAgent', description: 'Customer support assistant' })
export class SupportAgent {
  @Tool({ description: 'Search knowledge base' })
  async searchKB(input: { query: string }) {
    return this.ragService.search(input.query);
  }

  @Delegate({ agent: 'TicketAgent', description: 'Create support ticket' })
  async createTicket(input: { issue: string }) {
    return '';
  }
}

Data Analysis Assistant

@Agent({ name: 'DataAnalyst', description: 'Analyze business data' })
export class DataAnalyst {
  @Tool({ description: 'Query database' })
  async queryData(input: { sql: string }) {
    return this.db.query(input.sql);
  }

  @Tool({ description: 'Generate visualization' })
  async createChart(input: { data: any[], type: string }) {
    return this.chartService.generate(input.data, input.type);
  }
}

Content Generation Pipeline

@Agent({ name: 'ContentAgent', description: 'Generate marketing content' })
export class ContentAgent {
  @Delegate({ agent: 'ResearchAgent', description: 'Research topics' })
  async research(input: { topic: string }) {
    return '';
  }

  @Delegate({ agent: 'WriterAgent', description: 'Write content' })
  async write(input: { outline: string }) {
    return '';
  }

  @Delegate({ agent: 'EditorAgent', description: 'Edit and polish' })
  async edit(input: { draft: string }) {
    return '';
  }
}

Getting Started

Prerequisites

Node.js 18+
OpenAI API key (or other LLM provider)
Docker (optional, for containerized deployment)

Quick Start

# Create new project
npx @hazeljs/cli new my-ai-app --template ai-native

# Navigate to project
cd my-ai-app

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Add your OPENAI_API_KEY to .env

# Start development server
npm run dev

# Test the endpoints
curl -X POST http://localhost:3000/agent \
  -H "Content-Type: application/json" \
  -d '{"input": "What is the weather in Paris?"}'

Import Postman Collection

Open Postman
Import HazelJS-AI-Native.postman_collection.json
Test all endpoints with pre-configured requests

Deploy with Docker

# Build image
docker build -t my-ai-app .

# Run with docker-compose
docker-compose up -d

# Check health
curl http://localhost:3000/health

What's Next?

The AI-Native template is just the beginning. We're actively working on:

More Agent Patterns: Graph-based workflows, hierarchical agents, and autonomous loops
Enhanced RAG: Multi-modal retrieval, hybrid search, and reranking
Observability: Built-in tracing with OpenTelemetry and LangSmith integration
Fine-tuning Support: Easy integration with custom model training
Agent Marketplace: Share and discover pre-built agents

Join the Community

The HazelJS ecosystem is growing rapidly with 45+ packages and an active community of developers building AI-native applications.

GitHub: github.com/hazel-js/hazeljs
Discord: Join Discord
Documentation: hazeljs.com/docs

Conclusion

The AI-Native CLI template represents our vision for the future of AI application development: powerful, yet simple. By combining production-ready infrastructure with intuitive APIs, we're making it possible for any developer to build sophisticated AI agents without the complexity.

Whether you're a solo developer exploring AI or a team building production systems, this template gives you a solid foundation to build upon.

Try it today and see how quickly you can go from idea to intelligent application.

npx @hazeljs/cli new my-ai-app --template ai-native

HazelJS: The modular, AI-native framework for building production-grade TypeScript applications.

Distributed Sagas, Locking, and Zero-Config Documentation in NodeJS

Muhammad Arslan — Thu, 26 Mar 2026 07:14:29 +0000

We are thrilled to announce the release of HazelJS v0.4.0, a major update focused on building resilient, distributed systems with ease. This release introduces two powerhouse packages—@hazeljs/saga and @hazeljs/distributed-lock—along with significant observability and developer productivity enhancements across our entire ecosystem.

As the HazelJS ecosystem continues to grow with 45+ specialized packages, we remain committed to our mission: providing a modular, AI-native framework that scales from local experiments to production-grade distributed architectures.

What's New in v0.4.0?

1. Distributed Sagas (@hazeljs/saga) 🔄

Managing data consistency in microservices shouldn't require complex, manual state machine code. @hazeljs/saga brings declarative distributed transactions to HazelJS with both Orchestration and Choreography patterns.

Key Features:

Dual Pattern Support: Choose between centralized orchestration or decentralized event-driven choreography
Decorator-Based API: Clean, intuitive @Saga, @SagaStep, and @OnEvent decorators
Auto-Compensation: Automatic reversal of completed steps in reverse order on failure
Status Management: Built-in tracking for STARTED, COMPENSATING, ABORTED, and COMPLETED states
Type-Safe Context: Pass state and data across transaction steps with full TypeScript support

Orchestration Example:

@Saga({ name: 'checkout-saga' })
export class CheckoutSaga {
  @SagaStep({ order: 1, compensate: 'cancelReservation' })
  async reserveProduct(ctx: SagaContext) {
    return await this.inventory.reserve(ctx.input.productId);
  }

  @SagaStep({ order: 2, compensate: 'refund' })
  async chargeUser(ctx: SagaContext) {
    return await this.payment.charge(ctx.input.userId, ctx.input.amount);
  }

  async cancelReservation(ctx: SagaContext) {
    await this.inventory.cancel(ctx.input.productId);
  }
}

Choreography Example:

@Injectable()
export class OrderService {
  @OnEvent('order.created')
  async handleOrderCreated(data: any) {
    // Automatically participates in distributed transaction
    await this.processOrder(data);
  }
}

2. Distributed Locking (@hazeljs/distributed-lock) 🔒

Race conditions can destroy data integrity in multi-node environments. @hazeljs/distributed-lock provides first-class mutual exclusion with Redis and In-Memory backends.

Key Features:

Decorator-Based API: @DistributedLock() for declarative method-level locking
Dynamic Key Resolution: Template placeholders ({id}, {user.token}) resolve from method arguments
Multiple Backends: Redis for production, Memory for development/testing
Atomic Mutual Exclusion: Exactly one process executes critical sections across all nodes
Configurable Strategies: Retry counts, delays, TTLs, and wait behaviors
Automatic Cleanup: Locks released on method completion, regardless of success/failure

Usage:

@Injectable()
export class StockService {
  @DistributedLock({ 
    key: 'update-stock-{{productId}}', 
    ttl: 10000, 
    wait: true 
  })
  async decrementStock(productId: string) {
    // Only one instance can execute this for the same productId
    return await this.db.update(productId);
  }
}

3. Zero-Config Swagger Documentation 📚

Documentation should keep up with your code, not slow you down. @hazeljs/swagger now features generateAutoSpec(), producing complete OpenAPI 3.0 specifications by scanning your module's controllers—no decorators required.

Key Features:

Zero-Config Generation: Complete API specs without adding a single decorator
Path Discovery: Automatic detection of routes including complex path parameters
Smart Summaries: Infers operation descriptions from TypeScript method names
Method Mapping: Correct handling of GET, POST, PUT, DELETE, and PATCH methods
Default Schemas: Automatic inclusion of 400 and 500 error response schemas

How it works:

import { SwaggerService } from '@hazeljs/swagger';
import { AppModule } from './app.module';

@Service()
export class MyDocService {
  constructor(private readonly swagger: SwaggerService) {}

  getDocs() {
    // Discovers all controllers in AppModule and builds a spec
    return this.swagger.generateAutoSpec(AppModule, {
      title: 'Auto-Generated API',
      version: '1.0.0'
    });
  }
}

4. Core Observability: Performance Monitoring & Tracing 📊

Observability is now a first-class citizen in HazelJS Core with built-in performance monitoring and OpenTelemetry support.

Performance Monitoring:

// Built-in performance hooks
app.addPerformanceHook(BuiltinPerformanceHooks.slowRequestLogger(1000));
app.addPerformanceHook(BuiltinPerformanceHooks.memoryMonitor());
app.addPerformanceHook(BuiltinPerformanceHooks.metricsCollector());

// Custom hooks
app.addPerformanceHook({
  name: 'custom-metrics',
  onResponse: (metrics) => {
    // Track custom metrics
    this.metrics.track(metrics.duration, metrics.statusCode);
  }
});

Tracing with @trace:

@Service()
export class AIService {
  @Trace('ai.generate_summary')
  async summarize(text: string) {
    // Execution time automatically tracked and exported
    return await this.llm.call(text);
  }
}

Key Features:

Built-in Hooks: Slow request logger, memory monitor, rate limiter, metrics collector
Custom Hooks: Easy extension with custom performance monitoring
OpenTelemetry Integration: @Trace decorator for automatic span creation
Request Lifecycle: Full request tracking from start to finish
Performance Metrics: Active requests, response times, error rates

5. Enhanced Error Handling with EnhancedErrors 🚨

Consistency is key to a great developer experience. The new EnhancedErrors utility provides standardized error handling with helpful suggestions and context.

Key Features:

Standardized Errors: Consistent error codes and messages across your application
Helpful Suggestions: Automatic suggestions for common error scenarios
Context Preservation: Maintain request context and metadata
Type Safety: Full TypeScript support with proper error typing

Usage:

if (!user) {
  throw EnhancedErrors.notFound('User not found in registry');
}

if (!permission) {
  throw EnhancedErrors.unauthorized('Insufficient permissions');
}

if (validationError) {
  throw EnhancedErrors.validationFailed('Invalid input data');
}

Available Error Types:

validationFailed() - 400 Bad Request
unauthorized() - 401 Unauthorized
notFound() - 404 Not Found
methodNotAllowed() - 405 Method Not Allowed
rateLimitExceeded() - 429 Too Many Requests

6. Lazy Loading for Performance Optimization ⚡

New lazy loading capabilities in the Core DI container improve startup performance and reduce memory usage.

Key Features:

Module-Level Lazy: Load entire modules only when needed
Provider-Level Lazy: Individual providers instantiate on first use
Circular Dependency Handling: Graceful resolution of circular dependencies
Memory Optimization: Reduced initial memory footprint

Usage:

@Lazy()
@Injectable()
export class HeavyService {
  // Only instantiated when first resolved
}

@Module({
  lazy: true, // Entire module loads lazily
  providers: [HeavyService]
})
export class LazyModule {}

Ecosystem Highlights: 45+ Packages & Growing

HazelJS v0.4.0 continues our commitment to modularity with specialized packages for every need:

AI & Machine Learning 🤖

@hazeljs/ai - Multi-provider AI integration (OpenAI, Anthropic, Gemini, Cohere, Ollama)
@hazeljs/rag - Complete RAG + GraphRAG pipeline with 11 document loaders
@hazeljs/ml - Machine learning utilities and model management
@hazeljs/prompts - Prompt engineering and template management
@hazeljs/guardrails - AI safety and content filtering

Data & Persistence 💾

@hazeljs/data - Data pipelines and ETL workflows
@hazeljs/prisma - Prisma ORM integration
@hazeljs/typeorm - TypeORM integration
@hazeljs/cache - Multi-backend caching (Redis, Memory, etc.)

Distributed Systems 🌐

@hazeljs/saga - Distributed transaction management
@hazeljs/distributed-lock - Cross-node mutual exclusion
@hazeljs/kafka - Apache Kafka integration
@hazeljs/messaging - Message queue abstractions
@hazeljs/event-emitter - Event-driven architecture

Security & Auth 🔐

@hazeljs/auth - Authentication and authorization
@hazeljs/oauth - OAuth 2.0 integration
@hazeljs/casl - Access control lists
@hazelcs/security-headers - Security middleware

Observability & Monitoring 📈

@hazeljs/observability - Metrics and tracing
@hazeljs/inspector - Application inspection and debugging
@hazeljs/audit - Audit logging and compliance

Developer Tools 🛠️

@hazeljs/cli - Command-line interface and scaffolding
@hazeljs/testing - Enhanced testing utilities
@hazeljs/flow - Workflow and orchestration engine
@hazeljs/serverless - Serverless deployment support

Performance & Quality Improvements

Test Coverage: 83.73% 🎯

Performance Monitoring: 91.8% coverage
Enhanced Errors: 90.56% coverage
Container DI: 80.68% coverage
Overall Suite: 908 passing tests

TypeScript Enhancements

Strict Type Safety: Improved type inference across all packages
Better IntelliSense: Enhanced IDE support with proper exports
Reduced Bundle Size: Optimized imports and tree-shaking support

Developer Experience

Zero-Config Defaults: Sensible defaults that work out of the box
Progressive Enhancement: Start simple, add complexity as needed
Unified APIs: Consistent patterns across all packages

Migration Guide

From v0.3.x to v0.4.0

The migration is straightforward with most changes being additive:

# Update existing packages
npm update @hazeljs/core @hazeljs/swagger

# Add new packages (optional)
npm install @hazeljs/saga @hazeljs/distributed-lock

Breaking Changes

None - This is a fully backward-compatible release

Recommended Upgrades

Add Performance Monitoring: Enable built-in performance hooks
Implement Enhanced Errors: Standardize error handling
Try Zero-Config Docs: Replace manual Swagger decorators with auto-generation
Evaluate Distributed Needs: Consider sagas and locking for multi-node deployments

Getting Started

New Project Setup

# Install HazelJS CLI
npm install -g @hazeljs/cli

# Create new project
hazel create my-app

# Add distributed features
cd my-app
npm install @hazeljs/saga @hazeljs/distributed-lock

Existing Project Enhancement

# Update to latest
npm update @hazeljs/core @hazeljs/swagger

# Add new capabilities
npm install @hazeljs/saga @hazeljs/distributed-lock @hazeljs/ai

What's Next?

Looking ahead to v0.5.0, we're focusing on:

Advanced Observability: Distributed tracing and APM integrations
GraphQL Enhancements: Federation and subscription improvements
AI Agent Framework: Multi-agent systems with coordination
Edge Computing: Optimizations for serverless and edge deployments
Performance Tuning: Further optimizations for high-throughput scenarios

HazelJS v0.4.0 represents our most significant release yet, bringing enterprise-grade distributed systems capabilities to the Node.js ecosystem while maintaining the simplicity and developer experience that makes HazelJS special.

Join thousands of developers building the next generation of TypeScript applications with HazelJS.

HazelJS: The Future of Modular, AI-Native TypeScript Frameworks.

The Next Frontier of AI Agent Runtimes: Observability, MCP, and High-Precision RAG

Muhammad Arslan — Wed, 25 Mar 2026 04:04:15 +0000

TL;DR: HazelJS is evolving from a library to a robust Agent Runtime. New updates include native OpenTelemetry tracing, full Model Context Protocol (MCP) integration, and Cohere-powered RAG reranking.

In the fast-paced world of AI engineering, developers are moving past simple prompt-response loops and into the era of autonomous agent runtimes. At HazelJS, our mission has always been to provide the most robust, type-safe, and production-grade environment for these agents.

Today, we are excited to announce a major evolution in the HazelJS ecosystem: the introduction of Native OpenTelemetry Observability, Full Model Context Protocol (MCP) Support, and High-Precision RAG Reranking.

🏗️ 1. Observability: Ending the Debugging Nightmare

Traditional AI agents are "black boxes." When an agent fails after the 15th tool call in a complex flow, standard console logs are useless. You need a full stack trace of the AI's "thought process."

The HazelJS Way: Native OpenTelemetry

We’ve launched @hazeljs/observability, built directly on OpenTelemetry. Instead of boilerplate code, we’ve introduced a smart @Trace() decorator that works across both synchronous and asynchronous methods.

class FinancialAgent {
  @Trace('analyze_risk')
  async calculatePortfolioRisk(data: PortfolioData) {
    // Automatically creates spans, tracks duration, and captures metadata
    const result = await this.llm.generate(...);

    // Built-in cost and token tracking
    this.observability.trackCost('gpt-4o', result.usage.prompt, result.usage.completion);

    return result;
  }
}

[!TIP]
Zero Overhead: Our tracing implementation uses asynchronous BatchSpanProcessors to ensure observability never blocks your agent's execution performance.

🔌 2. Breaking Silos with Model Context Protocol (MCP)

Agents have historically been "islands"—limited by the tools hardcoded into their runtime. Connecting a GitHub agent to a Slack tool usually required custom, brittle glue code.

The HazelJS Solution: MCP-as-a-First-Class-Citizen

By integrating support for the Model Context Protocol (MCP), HazelJS agents can now instantly connect to a vast ecosystem of external tools via Standardized STDIO or HTTP Transports.

Instant Toolkits: Connect to a local GitHub MCP server or a remote Database bridge in seconds.
Dynamic Schema Mapping: HazelJS automatically translates MCP JSON-RPC definitions into internal ToolRegistry types.

🎯 3. High-Precision RAG: Quality Over Quantity

Standard Vector Search (RAG) often suffers from "noise" in the top-k results. Getting the right context is the difference between an expert agent and a confidently incorrect one.

Semantic Reranking with Cohere

We’ve integrated the CohereReranker (using Cohere Rerank 3) into the @hazeljs/rag pipeline.

Why Rerank?: Vector embeddings are great for finding "related" concepts, but Rerankers are experts at identifying the specific chunk that answers the query.
Deep Integration: Reranking is now an optional middleware step in the RAGPipeline, ensuring your LLM only sees the most relevant truth.

🛡️ 4. Production-Grade at Scale

"Move fast and break things" doesn't work for AI agents controlling real-world APIs. That's why we’ve overhauled our internal runtime stability.

A2A Protocol Compliance: Full adherence to the Agent-to-Agent (A2A) specification for cross-runtime interoperability.

HazelJS vs. The Competition

Feature	HazelJS	LangChain	Vercel AI SDK
Execution	Runtime-First (A2A)	Library-First	Framework-First
Observability	Native OTel Decorators	3rd Party (LangSmith)	Basic Telemetry
Tooling	Native MCP Support	Manual Adapters	Tool Definitions
Type Safety	Strict TypeScript	Mixed/Loose	High
Scaling	Distributed (Redis Store)	Often Single-process	Serverless-centric

Getting Started

Ready to build the next generation of observable AI?

npm install @hazeljs/agent @hazeljs/observability @hazeljs/mcp

Explore our updated Documentation or join the community on GitHub.

HazelJS 0.3.0: The AI-Native Framework for Production-Ready Intelligent Applications

Muhammad Arslan — Mon, 23 Mar 2026 16:28:01 +0000

We're thrilled to announce the release of HazelJS 0.3.0, a major milestone that transforms HazelJS into the most comprehensive AI-native backend framework for Node.js. This release brings enterprise-grade machine learning capabilities, advanced RAG systems, and a complete toolkit for building production-ready AI applications.

🎯 What is HazelJS?

HazelJS is a modern, TypeScript-first Node.js framework designed from the ground up for the AI era. Unlike traditional frameworks that bolt on AI features as an afterthought, HazelJS treats AI as a first-class citizen, providing native support for:

🤖 AI Agents with autonomous decision-making
🧠 Machine Learning pipelines and model management
📚 Retrieval-Augmented Generation (RAG) with advanced chunking strategies
💾 Persistent Memory for context-aware applications
🔄 Agentic Workflows with visual flow builders
40+ Enterprise Packages for complete application development

✨ What's New in 0.3.0

🧪 Complete Machine Learning Toolkit (`@hazeljs/ml`)

The new ML package provides everything you need to build, train, and deploy machine learning models in production:

Model Management & Training

import { Model, Train, Predict, TrainerService } from '@hazeljs/ml';

@Model({ name: 'sentiment-classifier', version: '1.0.0', framework: 'tensorflow' })
class SentimentModel {
  @Train()
  async train(data: TrainingData) {
    // Your training logic
    return { accuracy: 0.95, loss: 0.05 };
  }

  @Predict()
  async predict(input: { text: string }) {
    return { sentiment: 'positive', confidence: 0.92 };
  }
}

Experiment Tracking

Track your ML experiments with built-in support for metrics, parameters, and artifacts:

import { ExperimentService } from '@hazeljs/ml';

const experiment = experimentService.createExperiment('sentiment-analysis');
const run = experimentService.startRun(experiment.id);

experimentService.logMetric(run.id, 'accuracy', 0.95);
experimentService.logMetric(run.id, 'f1_score', 0.93);
experimentService.logArtifact(run.id, 'model', 'model', modelData);

experimentService.endRun(run.id);

Model Drift Detection

Monitor your models in production with comprehensive drift detection:

import { DriftService } from '@hazeljs/ml';

const driftService = new DriftService();
driftService.setReferenceDistribution('age', trainingData);

const driftResult = driftService.detectDrift('age', productionData, {
  method: 'psi', // Population Stability Index
  threshold: 0.25
});

if (driftResult.driftDetected) {
  console.log(`Drift detected! Score: ${driftResult.score}`);
}

Supports multiple drift detection methods:

PSI (Population Stability Index)
KS (Kolmogorov-Smirnov)
JSD (Jensen-Shannon Divergence)
Wasserstein Distance
Chi-Square for categorical features

Model Evaluation & Metrics

import { MetricsService } from '@hazeljs/ml';

const result = await metricsService.evaluate('sentiment-classifier', testData, {
  metrics: ['accuracy', 'precision', 'recall', 'f1']
});

console.log(result.metrics);
// { accuracy: 0.95, precision: 0.94, recall: 0.96, f1Score: 0.95 }

Production Monitoring

import { MonitorService } from '@hazeljs/ml';

monitorService.registerModel({
  modelName: 'sentiment-classifier',
  modelVersion: '1.0.0',
  featureDrift: { method: 'psi', threshold: 0.25 },
  accuracyMonitor: { threshold: 0.9, windowSize: 100 },
  checkIntervalMinutes: 60
});

monitorService.onAlert((alert) => {
  console.log(`Alert: ${alert.message}`);
  // Send to Slack, PagerDuty, etc.
});

📊 Test Coverage Achievement: The ML package now has 97.52% test coverage with 246 comprehensive tests, ensuring production-ready reliability.

🔍 Advanced RAG Capabilities (`@hazeljs/rag`)

Enhanced RAG system with production-grade features:

Intelligent Document Chunking

import { ChunkingStrategy } from '@hazeljs/rag';

// Semantic chunking based on meaning
const semanticChunker = new ChunkingStrategy({
  type: 'semantic',
  maxChunkSize: 512,
  overlapSize: 50
});

// Recursive chunking for structured documents
const recursiveChunker = new ChunkingStrategy({
  type: 'recursive',
  separators: ['\n\n', '\n', '. ', ' ']
});

Multi-Vector Store Support

Pinecone - Serverless vector database
Weaviate - Open-source vector search
Qdrant - High-performance vector similarity
Chroma - AI-native embedding database
In-Memory - For development and testing

Agentic RAG

Build autonomous RAG systems that can reason and make decisions:

import { AgenticRAG } from '@hazeljs/rag';

const agenticRAG = new AgenticRAG({
  vectorStore: pineconeStore,
  llm: openaiService,
  tools: [webSearchTool, calculatorTool],
  maxIterations: 5
});

const answer = await agenticRAG.query(
  'What were the Q4 2023 revenue figures and how do they compare to Q3?'
);

🤖 Enhanced AI Agent Runtime (`@hazeljs/agent`)

Build production-ready AI agents with advanced capabilities:

import { Agent, Tool } from '@hazeljs/agent';

@Agent({
  name: 'customer-support-agent',
  model: 'gpt-4',
  temperature: 0.7,
  maxIterations: 10
})
class CustomerSupportAgent {
  @Tool({ description: 'Search knowledge base' })
  async searchKB(query: string) {
    return await this.ragService.search(query);
  }

  @Tool({ description: 'Create support ticket' })
  async createTicket(issue: string, priority: string) {
    return await this.ticketService.create({ issue, priority });
  }
}

💾 Persistent Memory System (`@hazeljs/memory`)

Give your AI applications long-term memory:

import { MemoryService } from '@hazeljs/memory';

// Store conversation context
await memoryService.store({
  userId: 'user123',
  sessionId: 'session456',
  content: 'User prefers technical explanations',
  metadata: { type: 'preference', importance: 'high' }
});

// Retrieve relevant memories
const memories = await memoryService.recall({
  userId: 'user123',
  query: 'How should I explain this?',
  limit: 5
});

🔄 Visual Flow Builder (`@hazeljs/flow` + `@hazeljs/flow-runtime`)

Create complex AI workflows with a visual interface:

import { Flow, FlowNode } from '@hazeljs/flow';

const workflow = new Flow('customer-onboarding')
  .addNode('validate-email', { type: 'validation' })
  .addNode('send-welcome', { type: 'email' })
  .addNode('create-profile', { type: 'database' })
  .addNode('ai-personalization', { type: 'ai-agent' })
  .connect('validate-email', 'send-welcome')
  .connect('send-welcome', 'create-profile')
  .connect('create-profile', 'ai-personalization');

await flowRuntime.execute(workflow, { email: 'user@example.com' });

📊 Data Processing & ETL (`@hazeljs/data`)

Enterprise-grade data processing with quality checks:

import { DataPipeline, DataContract } from '@hazeljs/data';

@DataContract({
  owner: 'data-team',
  schema: {
    userId: { type: 'string', required: true },
    email: { type: 'string', format: 'email' },
    age: { type: 'number', min: 0, max: 120 }
  },
  sla: { freshness: '1h', completeness: 0.95 }
})
class UserData {}

const pipeline = new DataPipeline()
  .extract(source)
  .transform(cleanData)
  .validate(schema)
  .load(destination);

🛡️ AI Guardrails (`@hazeljs/guardrails`)

Ensure safe and compliant AI outputs:

import { GuardrailService } from '@hazeljs/guardrails';

const guardrails = new GuardrailService({
  toxicity: { threshold: 0.7 },
  pii: { detect: true, redact: true },
  factuality: { enabled: true },
  bias: { check: true }
});

const result = await guardrails.validate(aiResponse);
if (!result.passed) {
  console.log('Guardrail violations:', result.violations);
}

🏢 40+ Enterprise Packages

HazelJS 0.3.0 includes a complete ecosystem of packages:

Core Infrastructure

@hazeljs/core - Framework foundation
@hazeljs/config - Configuration management
@hazeljs/cache - Multi-tier caching (Redis, Memory)
@hazeljs/discovery - Service discovery & registry
@hazeljs/gateway - API gateway with rate limiting

AI & ML

@hazeljs/ai - Multi-provider AI integration (OpenAI, Anthropic, Gemini, Cohere, Ollama)
@hazeljs/ml - Complete ML toolkit
@hazeljs/rag - Advanced RAG systems
@hazeljs/agent - AI agent runtime
@hazeljs/memory - Persistent memory
@hazeljs/guardrails - AI safety & compliance
@hazeljs/prompts - Prompt management & templates

Data & Integration

@hazeljs/data - ETL & data quality
@hazeljs/prisma - Prisma ORM integration
@hazeljs/typeorm - TypeORM integration
@hazeljs/graphql - GraphQL server
@hazeljs/grpc - gRPC support
@hazeljs/kafka - Kafka integration
@hazeljs/queue - Job queues
@hazeljs/messaging - Message bus

Security & Auth

@hazeljs/auth - JWT authentication
@hazeljs/oauth - OAuth 2.0 / OpenID Connect
@hazeljs/casl - Authorization (CASL)
@hazeljs/audit - Audit logging

DevOps & Monitoring

@hazeljs/inspector - Runtime inspector dashboard
@hazeljs/ops-agent - Operations agent
@hazeljs/resilience - Circuit breakers & retries
@hazeljs/serverless - Serverless deployment

Developer Experience

@hazeljs/cli - Code generation & scaffolding
@hazeljs/swagger - OpenAPI documentation
@hazeljs/i18n - Internationalization
@hazeljs/cron - Scheduled tasks

View all packages →

🎓 Getting Started

Installation

# Create a new HazelJS project
npx @hazeljs/cli new my-ai-app

# Or add to existing project
npm install @hazeljs/core @hazeljs/ai @hazeljs/ml @hazeljs/rag

Quick Example: AI-Powered API

import { Module, Controller, Get, Post, Body } from '@hazeljs/core';
import { AIEnhancedService } from '@hazeljs/ai';
import { RAGService } from '@hazeljs/rag';
import { MetricsService } from '@hazeljs/ml';

@Controller('/api')
class AIController {
  constructor(
    private ai: AIEnhancedService,
    private rag: RAGService,
    private metrics: MetricsService
  ) {}

  @Post('/chat')
  async chat(@Body() { message }: { message: string }) {
    // Use RAG for context
    const context = await this.rag.search(message, { limit: 3 });

    // Generate AI response
    const response = await this.ai
      .chat()
      .system('You are a helpful assistant')
      .context(context)
      .user(message)
      .execute();

    // Track metrics
    await this.metrics.recordEvaluation({
      modelName: 'chat-assistant',
      version: '1.0.0',
      metrics: { responseTime: response.latency }
    });

    return response;
  }
}

@Module({
  controllers: [AIController],
  providers: [AIEnhancedService, RAGService, MetricsService]
})
class AppModule {}

📈 Performance & Reliability

97.52% Test Coverage for ML package
Production-tested drift detection algorithms
Type-safe APIs with full TypeScript support
Modular architecture - use only what you need
Enterprise-ready with comprehensive monitoring

🔗 Resources & Links

Website: https://hazeljs.ai
Documentation: https://hazeljs.ai/docs
GitHub: https://github.com/hazel-js/hazeljs
NPM: https://www.npmjs.com/org/hazeljs
Discord Community: https://discord.com/channels/1448263814238965833/1448263814859456575

Package Documentation

AI Package - Multi-provider AI integration
ML Package - Machine learning toolkit
RAG Package - Retrieval-augmented generation
Agent Package - AI agent runtime
Memory Package - Persistent memory
Data Package - ETL & data quality
Flow Package - Visual workflow builder

Guides & Tutorials

🤝 Community & Support

Join our growing community:

GitHub Discussions: Ask questions and share ideas
Discord: Real-time chat with the team and community
Stack Overflow: Tag your questions with hazeljs

🎯 What's Next?

We're already working on exciting features for the next release:

AutoML capabilities for automated model selection
Federated Learning support for privacy-preserving ML
Enhanced Graph RAG with knowledge graph integration
Multi-modal AI support (vision, audio, video)
Distributed Training for large-scale ML
Real-time Model Serving with optimized inference

💡 Why Choose HazelJS?

AI-Native Architecture

Unlike frameworks that add AI as an afterthought, HazelJS is built from the ground up for AI applications.

Production-Ready

With 97%+ test coverage, comprehensive monitoring, and enterprise features, HazelJS is ready for production workloads.

Developer Experience

TypeScript-first design, intuitive APIs, and excellent documentation make development a joy.

Complete Ecosystem

40+ packages covering everything from AI to databases, authentication to monitoring.

Open Source

Apache 2.0 licensed, community-driven, and transparent development.

🚀 Try It Today

npx @hazeljs/cli new my-intelligent-app
cd my-intelligent-app
npm run dev

Visit hazeljs.ai to get started and join the AI-native revolution in backend development!

Found this helpful? Give us a ⭐ on GitHub

Questions? Drop a comment below or join our Discord community.

Real-Time AI Agent Streaming in NodeJS: A Complete Guide

Muhammad Arslan — Fri, 20 Mar 2026 11:40:08 +0000

Building ChatGPT-like streaming experiences with Server-Sent Events

Introduction

In the world of AI applications, user experience is everything. When users interact with AI agents, they expect immediate, real-time feedback—not a loading spinner followed by a wall of text. This is where streaming becomes crucial.

In this comprehensive guide, we'll explore how to build production-ready, real-time AI agent streaming using HazelJS, complete with:

✅ True word-by-word token streaming (like ChatGPT)
✅ Server-Sent Events (SSE) for web applications
✅ Plain text streaming for terminal/CLI usage
✅ Beautiful web UI with real-time metrics
✅ Production-ready error handling

By the end of this post, you'll have a fully functional streaming AI agent that delivers tokens in real-time, providing an exceptional user experience.

Why Streaming Matters
The Challenge: Async Generator Buffering
The Solution: Server-Sent Events
Implementation Overview
Building the Streaming Backend
Creating the Web UI
Terminal Streaming with curl
Performance & Metrics
Production Considerations
Conclusion

Why Streaming Matters

The User Experience Problem

Traditional AI interactions follow this pattern:

User: "Explain TypeScript 5.0 features"
[10 seconds of loading...]
AI: [Entire 500-word response appears at once]

This creates several UX issues:

Perceived latency: Users wait with no feedback
Anxiety: Is it working? Did it crash?
Poor engagement: No sense of "thinking" or progress

The Streaming Solution

With streaming, the experience transforms:

User: "Explain TypeScript 5.0 features"
AI: TypeScript 5.0 introduces several significant features...
    [tokens appear word-by-word in real-time]
    ...including decorators, the satisfies operator...
    [continues streaming naturally]

Benefits:

⚡ Instant feedback: First token appears in ~100-200ms
🎯 Engagement: Users see the AI "thinking" and responding
📊 Transparency: Real-time metrics show progress
🚀 Perceived speed: Feels 10x faster even with same total time

The Challenge: Async Generator Buffering

JavaScript's Hidden Limitation

When building streaming in Node.js, you might naturally reach for async generators:

async function* streamTokens() {
  for await (const chunk of openai.chat.completions.create({
    stream: true,
    // ...
  })) {
    yield chunk.choices[0]?.delta?.content || '';
  }
}

// Usage
for await (const token of streamTokens()) {
  console.log(token); // ❌ All tokens appear at once!
}

The Problem: JavaScript's for await...of loop buffers the entire async iterable before processing. This is a fundamental limitation of the async iteration protocol.

What Actually Happens

Expected:  [0.1s] "Type" [0.2s] "Script" [0.3s] " is"...
Reality:   [10.5s] "TypeScript is a programming language..."

All 500+ tokens arrive in one batch after the LLM finishes, defeating the purpose of streaming.

The Solution: Server-Sent Events

Why SSE?

Server-Sent Events (SSE) is a web standard that enables servers to push real-time updates to clients over HTTP. Unlike async generators, SSE delivers data immediately as it becomes available.

Key advantages:

🔥 True real-time: No buffering, tokens arrive instantly
🌐 Web standard: Built into browsers via EventSource API
🔌 Simple protocol: Just HTTP with text/event-stream content type
🔄 Automatic reconnection: Browsers handle connection drops
📡 One-way communication: Perfect for streaming responses

SSE vs WebSockets

Feature	SSE	WebSockets
Direction	Server → Client	Bidirectional
Protocol	HTTP	Custom (ws://)
Reconnection	Automatic	Manual
Browser Support	Excellent	Excellent
Complexity	Simple	More complex
Use Case	Streaming responses	Real-time chat

For AI agent streaming, SSE is the perfect fit.

Implementation Overview

Our streaming solution consists of three main components:

┌─────────────────────────────────────────────────────────┐
│                    HazelJS Backend                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │  StreamingController                             │  │
│  │  • SSE endpoint: /api/stream                     │  │
│  │  • Format: JSON (web) or plain text (terminal)  │  │
│  │  • Real-time token delivery                      │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                          ↓
                    SSE Connection
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    Frontend Options                     │
│  ┌──────────────────┐         ┌────────────────────┐   │
│  │   Web Browser    │         │   Terminal/curl    │   │
│  │  EventSource API │         │   Plain text       │   │
│  │  Beautiful UI    │         │   Clean output     │   │
│  └──────────────────┘         └────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Building the Streaming Backend

Step 1: Add SSE Support to HazelJS Core

First, we enhanced @hazeljs/core with native SSE support by adding an sse() method to the HazelHttpResponse class:

// packages/core/src/hazel-response.ts
export class HazelHttpResponse implements HazelResponse {
  private isStreaming: boolean = false;
  private headersSent: boolean = false;
  private customHeaders: Record<string, string> = {};

  sse(): { write: (data: string) => void; end: () => void } {
    if (!this.headersSent) {
      this.headersSent = true;
      this.isStreaming = true;
      this.res.setHeader('Content-Type', 'text/event-stream');
      this.res.setHeader('Cache-Control', 'no-cache');
      this.res.setHeader('Connection', 'keep-alive');
    }

    return {
      write: (data: string) => {
        this.res.send(data);
      },
      end: () => {
        this.res.end();
      },
    };
  }
}

Key features:

Sets proper SSE headers (text/event-stream, no-cache, keep-alive)
Returns a simple interface with write() and end() methods
Handles header management automatically

Step 2: Create the Streaming Controller

Now we can build our streaming endpoint:

// src/server/streaming-server.ts
import { Controller, Get, Req, Res } from '@hazeljs/core';
import { AgentRuntime } from '@hazeljs/agent';

@Controller('/api')
export class StreamingController {
  private runtime: AgentRuntime;

  constructor() {
    this.runtime = new AgentRuntime({
      llmProvider: new OpenAILLMProvider(process.env.OPENAI_API_KEY),
      defaultMaxSteps: 10,
      enableObservability: true,
    });

    this.runtime.registerAgent(ResearchAgent);
    this.runtime.registerAgentInstance('ResearchAgent', new ResearchAgent());
  }

  @Get('/stream')
  async streamAgent(@Req() req: any, @Res() res: any) {
    const query = req.query?.q || 'What are the key features of TypeScript 5.0?';
    const format = req.query?.format || 'sse'; // 'sse' or 'text'

    // Start SSE streaming
    const stream = res.sse();

    try {
      let tokenCount = 0;
      const startTime = Date.now();

      // Send initial connection message for web UI
      if (format === 'sse') {
        stream.write('data: {"type":"connected"}\n\n');
      }

      // Stream agent execution with real-time token delivery
      for await (const chunk of this.runtime.executeStream(
        'ResearchAgent',
        query,
        { streaming: true }
      )) {
        if (format === 'sse') {
          // JSON format for web UI
          const data = JSON.stringify({
            type: chunk.type,
            ...(chunk.type === 'token' && { content: chunk.content }),
            ...(chunk.type === 'step' && { 
              step: {
                state: chunk.step.state,
                action: chunk.step.action?.type,
              }
            }),
            ...(chunk.type === 'done' && {
              result: {
                state: chunk.result.state,
                duration: chunk.result.duration,
                response: chunk.result.response,
              }
            }),
            timestamp: Date.now() - startTime,
          });
          stream.write(`data: ${data}\n\n`);

          if (chunk.type === 'token') {
            tokenCount++;
          }
        } else {
          // Plain text format for terminal
          if (chunk.type === 'token') {
            stream.write(chunk.content);
            tokenCount++;
          } else if (chunk.type === 'step') {
            stream.write('\n\n');
          }
        }
      }

      // Send completion message
      if (format === 'sse') {
        stream.write(`data: {"type":"complete","tokens":${tokenCount}}\n\n`);
      } else {
        const duration = ((Date.now() - startTime) / 1000).toFixed(2);
        stream.write(`\n\n---\n✅ Complete: ${tokenCount} tokens in ${duration}s\n`);
      }

      stream.end();

    } catch (error) {
      const errorData = JSON.stringify({
        type: 'error',
        error: error instanceof Error ? error.message : 'Unknown error',
      });
      stream.write(`data: ${errorData}\n\n`);
      stream.end();
    }
  }

  @Get('/health')
  health() {
    return { status: 'ok', service: 'agent-streaming' };
  }
}

Key implementation details:

Dual format support: The format query parameter allows switching between:
- sse: JSON events for web UI (default)
- text: Plain text for terminal/curl
Event types: We stream different event types:
- connected: Initial connection established
- token: Individual LLM tokens (the actual content)
- step: Agent step transitions
- done: Agent execution complete
- complete: Stream finished with metrics
Real-time delivery: Each token is written immediately via stream.write(), bypassing any buffering
Error handling: Graceful error messages sent as SSE events

Creating the Web UI

The web interface provides a beautiful, real-time streaming experience with live metrics.

HTML Structure

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>HazelJS Agent Streaming Demo</title>
  <!-- Beautiful gradient background and modern styling -->
</head>
<body>
  <div class="container">
    <div class="header">
      <h1>🚀 HazelJS Agent Streaming</h1>
      <p>Real-time word-by-word AI responses using Server-Sent Events</p>
    </div>

    <div class="card">
      <!-- Input section -->
      <div class="input-section">
        <div class="input-group">
          <input 
            type="text" 
            id="queryInput" 
            placeholder="Ask me anything..."
            value="What are the key features of TypeScript 5.0?"
          >
          <button id="streamBtn" onclick="startStreaming()">
            Stream Response
          </button>
        </div>
      </div>

      <!-- Status indicator -->
      <div id="status" class="status">
        <span class="status-dot"></span>
        <span id="statusText">Ready</span>
      </div>

      <!-- Real-time metrics -->
      <div class="metrics">
        <div class="metric">
          <div class="metric-value" id="tokenCount">0</div>
          <div class="metric-label">Tokens</div>
        </div>
        <div class="metric">
          <div class="metric-value" id="duration">0.0s</div>
          <div class="metric-label">Duration</div>
        </div>
        <div class="metric">
          <div class="metric-value" id="tokensPerSec">0</div>
          <div class="metric-label">Tokens/sec</div>
        </div>
        <div class="metric">
          <div class="metric-value" id="stepCount">0</div>
          <div class="metric-label">Steps</div>
        </div>
      </div>

      <!-- Response container -->
      <div class="response-container">
        <div class="response-text" id="response"></div>
      </div>
    </div>
  </div>
</body>
</html>

JavaScript: EventSource Integration

The magic happens with the browser's EventSource API:

let eventSource = null;
let tokenCount = 0;
let stepCount = 0;
let startTime = 0;

function startStreaming() {
  const query = document.getElementById('queryInput').value;
  const responseEl = document.getElementById('response');
  const statusEl = document.getElementById('status');
  const statusText = document.getElementById('statusText');
  const streamBtn = document.getElementById('streamBtn');

  // Reset UI
  responseEl.textContent = '';
  tokenCount = 0;
  stepCount = 0;
  updateMetrics();

  // Disable button during streaming
  streamBtn.disabled = true;
  streamBtn.textContent = 'Streaming...';

  // Show status
  statusEl.style.display = 'flex';
  statusEl.className = 'status streaming';
  statusText.textContent = 'Connecting...';

  // Close existing connection
  if (eventSource) {
    eventSource.close();
  }

  // Create new SSE connection
  const url = `/api/stream?q=${encodeURIComponent(query)}`;
  eventSource = new EventSource(url);
  startTime = Date.now();

  eventSource.onopen = () => {
    statusText.textContent = 'Streaming response...';
  };

  eventSource.onmessage = (event) => {
    try {
      const data = JSON.parse(event.data);

      switch (data.type) {
        case 'connected':
          statusEl.className = 'status connected';
          statusText.textContent = 'Connected';
          break;

        case 'token':
          // Add token immediately - true real-time streaming!
          responseEl.textContent += data.content;
          tokenCount++;
          updateMetrics();

          // Auto-scroll to bottom
          responseEl.parentElement.scrollTop = 
            responseEl.parentElement.scrollHeight;
          break;

        case 'step':
          stepCount++;
          updateMetrics();
          break;

        case 'done':
          statusEl.className = 'status connected';
          statusText.textContent = 'Complete';
          streamBtn.disabled = false;
          streamBtn.textContent = 'Stream Response';
          eventSource.close();
          break;

        case 'complete':
          console.log('Stream complete:', data);
          break;

        case 'error':
          statusEl.className = 'status error';
          statusText.textContent = `Error: ${data.error}`;
          streamBtn.disabled = false;
          streamBtn.textContent = 'Stream Response';
          eventSource.close();
          break;
      }
    } catch (error) {
      console.error('Error parsing SSE data:', error);
    }
  };

  eventSource.onerror = (error) => {
    console.error('SSE error:', error);
    statusEl.className = 'status error';
    statusText.textContent = 'Connection error';
    streamBtn.disabled = false;
    streamBtn.textContent = 'Stream Response';
    eventSource.close();
  };
}

function updateMetrics() {
  document.getElementById('tokenCount').textContent = tokenCount;

  const duration = (Date.now() - startTime) / 1000;
  document.getElementById('duration').textContent = duration.toFixed(1) + 's';

  const tokensPerSec = duration > 0 ? Math.round(tokenCount / duration) : 0;
  document.getElementById('tokensPerSec').textContent = tokensPerSec;

  document.getElementById('stepCount').textContent = stepCount;
}

Key features:

EventSource API: Browser's native SSE client
Event handling: Different handlers for each event type
Real-time metrics: Updates on every token
Auto-scroll: Keeps latest content visible
Error handling: Graceful degradation on connection issues

Terminal Streaming with curl

For CLI users and debugging, we support plain text streaming:

# Stream with plain text format
curl -N "http://localhost:3000/api/stream?q=Explain%20TypeScript&format=text"

Output:

TypeScript 5.0, released in March 2023, introduces several significant 
features and improvements that enhance the language's capabilities and 
developer experience...

[tokens stream in real-time, word by word]

---
✅ Complete: 561 tokens in 14.71s

Why this works:

-N flag disables curl's buffering
format=text parameter triggers plain text mode
Tokens appear immediately as they're generated
Clean, readable output perfect for terminal viewing

Performance & Metrics

Real-World Performance

Based on production testing with OpenAI's GPT-4:

Metric	Value
First token latency	100-200ms
Throughput	50-100 tokens/sec
Memory usage	Minimal (streaming, not buffering)
Concurrent users	Handles 100+ simultaneous streams
Total response time	10-15s for 500 tokens

Perceived vs Actual Speed

Without streaming:

User waits: 10 seconds
Perceived speed: Slow ❌

With streaming:

User waits: 0.1 seconds (first token)
Perceived speed: Instant ✅

Even though the total time is the same, streaming makes the experience feel 10x faster.

Production Considerations

1. Error Handling

Always handle connection errors gracefully:

try {
  for await (const chunk of runtime.executeStream(...)) {
    stream.write(`data: ${JSON.stringify(chunk)}\n\n`);
  }
} catch (error) {
  stream.write(`data: ${JSON.stringify({
    type: 'error',
    error: error.message
  })}\n\n`);
} finally {
  stream.end();
}

2. Timeout Management

Set reasonable timeouts to prevent hanging connections:

// In your HazelJS app
app.setTimeout(60000); // 60 second timeout

3. Rate Limiting

Protect your API from abuse:

import { RateLimiterMiddleware } from '@hazeljs/core';

@Controller('/api')
@UseMiddleware(RateLimiterMiddleware.create({
  windowMs: 60000,
  max: 10 // 10 requests per minute
}))
export class StreamingController {
  // ...
}

4. CORS Configuration

Enable CORS for web clients:

// src/server/main.ts
const app = new HazelApp(StreamingServerModule);
app.enableCors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  credentials: true
});

5. Monitoring & Logging

Track streaming metrics:

const metrics = {
  totalStreams: 0,
  activeStreams: 0,
  avgTokensPerStream: 0,
  avgDuration: 0
};

// Update metrics on each stream
stream.on('start', () => metrics.activeStreams++);
stream.on('end', (stats) => {
  metrics.activeStreams--;
  metrics.totalStreams++;
  metrics.avgTokensPerStream = 
    (metrics.avgTokensPerStream + stats.tokens) / 2;
});

6. Deployment

Nginx configuration for SSE:

location /api/stream {
    proxy_pass http://localhost:3000;
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
    proxy_buffering off;
    proxy_cache off;
}

Docker deployment:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "run", "server:streaming"]

Running the Example

Prerequisites

# Install dependencies
npm install

# Set your OpenAI API key
export OPENAI_API_KEY=your_api_key_here

Start the Server

npm run example:streaming

The server starts on http://localhost:3000 with:

🎨 Web UI: http://localhost:3000/streaming-demo.html
🔌 SSE Endpoint: http://localhost:3000/api/stream
💚 Health Check: http://localhost:3000/api/health

Test with curl

# Plain text streaming (for terminal)
curl -N "http://localhost:3000/api/stream?q=Your%20question&format=text"

# SSE format (for debugging)
curl -N "http://localhost:3000/api/stream?q=Your%20question"

Test with Browser

Open http://localhost:3000/streaming-demo.html
Enter your question
Click "Stream Response"
Watch tokens appear in real-time! ✨

Code Architecture

Project Structure

hazeljs-multi-agent-ai-workflows-example/
├── src/
│   ├── server/
│   │   ├── main.ts                    # Server bootstrap
│   │   └── streaming-server.ts        # Streaming controller
│   ├── agents/
│   │   └── research-agent.ts          # AI agent implementation
│   ├── utils/
│   │   └── llm-provider.ts            # OpenAI integration
│   └── examples/
│       └── 05-streaming-example.ts    # CLI streaming example
├── public/
│   └── streaming-demo.html            # Web UI
└── package.json

Key Files

1. Streaming Controller (src/server/streaming-server.ts)

Handles SSE connections
Manages agent execution
Supports dual format (SSE/text)

2. Web UI (public/streaming-demo.html)

EventSource integration
Real-time metrics
Beautiful, responsive design

3. Server Bootstrap (src/server/main.ts)

HazelJS app initialization
CORS configuration
Static file serving

Advanced Features

1. Custom Event Types

Add your own event types for richer interactions:

// Send thinking indicator
stream.write(`data: ${JSON.stringify({
  type: 'thinking',
  message: 'Analyzing your question...'
})}\n\n`);

// Send progress updates
stream.write(`data: ${JSON.stringify({
  type: 'progress',
  percent: 45,
  step: 'Researching documentation'
})}\n\n`);

2. Multi-Agent Streaming

Stream from multiple agents simultaneously:

const agents = ['ResearchAgent', 'AnalysisAgent', 'SummaryAgent'];

for (const agentName of agents) {
  stream.write(`data: ${JSON.stringify({
    type: 'agent-start',
    agent: agentName
  })}\n\n`);

  for await (const chunk of runtime.executeStream(agentName, query)) {
    stream.write(`data: ${JSON.stringify({
      type: 'token',
      agent: agentName,
      content: chunk.content
    })}\n\n`);
  }
}

3. Conversation History

Maintain context across streams:

const conversationHistory = new Map();

@Get('/stream')
async streamAgent(@Req() req: any, @Res() res: any) {
  const sessionId = req.query?.session;
  const history = conversationHistory.get(sessionId) || [];

  // Include history in agent context
  for await (const chunk of runtime.executeStream(
    'ResearchAgent',
    query,
    { history, streaming: true }
  )) {
    // Stream response...
  }

  // Save to history
  history.push({ role: 'user', content: query });
  history.push({ role: 'assistant', content: fullResponse });
  conversationHistory.set(sessionId, history);
}

Troubleshooting

Issue: Tokens Still Buffered

Problem: Tokens appear in batches instead of individually.

Solution: Ensure you're using SSE, not async generators:

// ❌ Wrong - uses async generators
for await (const token of streamTokens()) {
  console.log(token); // Buffered!
}

// ✅ Correct - uses SSE
const stream = res.sse();
stream.write(`data: ${token}\n\n`); // Immediate!

Issue: CORS Errors

Problem: Browser blocks SSE connection.

Solution: Enable CORS in your HazelJS app:

app.enableCors({
  origin: '*', // or specific domains
  credentials: true
});

Issue: Connection Drops

Problem: SSE connection closes unexpectedly.

Solution: Check reverse proxy settings (Nginx, etc.):

proxy_buffering off;
proxy_cache off;
proxy_read_timeout 300s;

Issue: Slow Streaming

Problem: Tokens arrive slowly.

Solution: This is typically due to LLM API latency, not your code. Consider:

Using faster models (GPT-3.5 vs GPT-4)
Reducing max_tokens
Implementing caching for common queries

Comparison: Before vs After

Before (No Streaming)

// Traditional approach
const response = await openai.chat.completions.create({
  messages: [{ role: 'user', content: query }],
  model: 'gpt-4'
});

// User waits 10+ seconds
res.json({ response: response.choices[0].message.content });

User Experience:

⏳ 10 second wait
😰 No feedback
📄 Wall of text appears
😕 Poor engagement

After (With Streaming)

// Streaming approach
const stream = res.sse();

for await (const chunk of runtime.executeStream(...)) {
  stream.write(`data: ${JSON.stringify(chunk)}\n\n`);
}

User Experience:

⚡ 0.1 second to first token
🎯 Immediate feedback
📝 Text flows naturally
😊 Excellent engagement

Best Practices

1. Always Set Proper Headers

res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
res.setHeader('X-Accel-Buffering', 'no'); // For Nginx

2. Handle Cleanup

req.on('close', () => {
  // Client disconnected, cleanup resources
  eventSource.close();
  runtime.cancel();
});

3. Implement Heartbeats

Keep connections alive with periodic pings:

const heartbeat = setInterval(() => {
  stream.write(': heartbeat\n\n');
}, 30000); // Every 30 seconds

// Clear on completion
clearInterval(heartbeat);

4. Use Compression Carefully

SSE and compression don't mix well. Disable compression for streaming endpoints:

app.use(compression({
  filter: (req, res) => {
    if (req.path === '/api/stream') return false;
    return compression.filter(req, res);
  }
}));

5. Monitor Performance

Track key metrics:

const streamMetrics = {
  startTime: Date.now(),
  firstTokenTime: 0,
  tokenCount: 0,

  recordFirstToken() {
    if (!this.firstTokenTime) {
      this.firstTokenTime = Date.now() - this.startTime;
    }
  }
};

Conclusion

Real-time streaming transforms AI agent interactions from frustrating waits into engaging, ChatGPT-like experiences. With HazelJS's native SSE support, implementing production-ready streaming is straightforward and powerful.

Key Takeaways

✅ SSE bypasses async generator buffering for true real-time streaming

✅ HazelJS provides native sse() method in the core framework

✅ Dual format support enables both web UI and terminal usage

✅ EventSource API makes client-side integration simple

✅ Real-time metrics enhance user engagement and transparency

What We Built

🚀 Production-ready streaming backend with HazelJS
🎨 Beautiful web UI with real-time token display
🖥️ Terminal-friendly plain text streaming
📊 Live metrics (tokens/sec, duration, steps)
🔧 Error handling and connection management
📦 Complete, runnable example

Next Steps

Try the example: Run npm run example:streaming
Customize the UI: Modify streaming-demo.html to match your brand
Add features: Implement conversation history, multi-agent support
Deploy: Use the production guidelines to go live
Monitor: Track metrics and optimize performance

Resources

GitHub: hazeljs-multi-agent-ai-workflows-example
Documentation: HazelJS Docs
Demo: Try the live demo at http://localhost:3000/streaming-demo.html

Full Example Code

Server Setup

# Install dependencies
npm install @hazeljs/core @hazeljs/agent openai

# Set environment variable
export OPENAI_API_KEY=your_key_here

# Run the server
npm run example:streaming

Quick Start

import { HazelApp } from '@hazeljs/core';
import { StreamingServerModule } from './streaming-server';

const app = new HazelApp(StreamingServerModule);
app.enableCors();
await app.listen(3000);

console.log('🚀 Streaming server ready!');
console.log('📡 http://localhost:3000/streaming-demo.html');

That's it! You now have a fully functional, production-ready streaming AI agent.

Happy Streaming! 🚀

Built with ❤️ using HazelJS

About the Author

This guide was created by the HazelJS team to help developers build better AI experiences. HazelJS is a modern, TypeScript-first Node.js framework designed for building production-grade AI applications.

Questions or feedback? Open an issue on GitHub or join our Discord community.

Multi-Agent Orchestration: Three Patterns for Complex AI Workflows in NodeJS

Muhammad Arslan — Fri, 20 Mar 2026 07:49:55 +0000

Building production-grade AI systems with HazelJS Agent Runtime

Introduction

The future of AI isn't single-purpose chatbots—it's coordinated teams of specialized agents working together to solve complex problems. Just as modern software systems evolved from monolithic applications to microservices, AI systems are evolving from single-agent interactions to multi-agent orchestration.

But building multi-agent systems is hard. You need to:

Route tasks to the right specialist
Coordinate execution across multiple agents
Handle failures gracefully
Maintain state across agent boundaries
Observe what's happening in your system

This is where HazelJS Agent Runtime shines. It provides three complementary patterns for multi-agent orchestration, each designed for different use cases:

@Delegate — Peer-to-peer agent delegation
AgentGraph — DAG-based workflow pipelines
SupervisorAgent — LLM-driven dynamic routing

In this article, we'll explore each pattern, understand when to use them, and build a complete content creation pipeline that combines all three.

Why Multi-Agent Systems?

Before diving into patterns, let's understand why you'd want multiple agents instead of one powerful agent.

The Monolith Problem

A single agent handling everything becomes:

Bloated — Too many tools, overwhelming context
Unfocused — Jack of all trades, master of none
Hard to test — Can't isolate specific capabilities
Expensive — Large context windows for every request

The Multi-Agent Solution

Specialized agents are:

Focused — Each agent has a clear domain
Composable — Mix and match for different workflows
Testable — Test each agent independently
Efficient — Smaller contexts, targeted prompts

Think of it like a software team: you don't hire one person to do design, frontend, backend, and DevOps. You hire specialists and coordinate their work.

Pattern 1: `@Delegate` — Peer-to-Peer Delegation

What is it?

@Delegate lets one agent call another agent as if it were a tool. The orchestrator agent doesn't know it's delegating—from the LLM's perspective, it's just calling a function. The runtime handles the delegation transparently.

Architecture

OrchestratorAgent
   ├── @Delegate → ResearchAgent
   ├── @Delegate → WriterAgent
   └── @Delegate → EditorAgent

When to use it?

Clear hierarchy — One orchestrator, multiple workers
2-5 agents — Simple delegation chains
Predefined roles — You know which agent does what

Code Example

import { Agent, Delegate, Tool } from '@hazeljs/agent';

// Worker Agent 1: Research
@Agent({
  name: 'ResearchAgent',
  description: 'Expert researcher who finds and synthesizes information',
  systemPrompt: 'You are an expert researcher. Find accurate, relevant information and cite sources.',
})
export class ResearchAgent {
  @Tool({
    description: 'Search the web for information',
    parameters: [{ name: 'query', type: 'string', required: true }],
  })
  async searchWeb(input: { query: string }) {
    // Simulate web search
    return {
      results: [
        { title: 'AI Agents Overview', snippet: 'AI agents are autonomous...' },
        { title: 'Multi-Agent Systems', snippet: 'Coordination between agents...' },
      ],
      sources: ['https://example.com/ai-agents', 'https://example.com/multi-agent'],
    };
  }

  @Tool({
    description: 'Analyze research findings and extract key insights',
    parameters: [{ name: 'data', type: 'string', required: true }],
  })
  async analyzeFindings(input: { data: string }) {
    return {
      insights: ['Key finding 1', 'Key finding 2', 'Key finding 3'],
      confidence: 0.85,
    };
  }
}

// Worker Agent 2: Writing
@Agent({
  name: 'WriterAgent',
  description: 'Professional technical writer who creates polished content',
  systemPrompt: 'You are a professional technical writer. Create clear, engaging content.',
})
export class WriterAgent {
  @Tool({
    description: 'Write a blog post section from research notes',
    parameters: [
      { name: 'topic', type: 'string', required: true },
      { name: 'research', type: 'string', required: true },
    ],
  })
  async writeBlogSection(input: { topic: string; research: string }) {
    return {
      content: `## ${input.topic}\n\nBased on research: ${input.research}...`,
      wordCount: 450,
    };
  }

  @Tool({
    description: 'Format content as markdown with proper structure',
    parameters: [{ name: 'rawContent', type: 'string', required: true }],
  })
  async formatMarkdown(input: { rawContent: string }) {
    return `# Article\n\n${input.rawContent}\n\n---\n*Generated by AI*`;
  }
}

// Orchestrator Agent
@Agent({
  name: 'ContentOrchestratorAgent',
  description: 'Orchestrates research and writing tasks to create complete articles',
  systemPrompt: `You orchestrate content creation. Use researchTopic to gather information, 
then use writeArticle to create the final content. Always research before writing.`,
})
export class ContentOrchestratorAgent {
  // This looks like a tool to the LLM, but it's actually a delegation to ResearchAgent
  @Delegate({
    agent: 'ResearchAgent',
    description: 'Research a topic thoroughly and return key findings with sources',
    inputField: 'query',
  })
  async researchTopic(query: string): Promise<string> {
    return ''; // Body replaced at runtime by AgentRuntime
  }

  // This delegates to WriterAgent
  @Delegate({
    agent: 'WriterAgent',
    description: 'Write a polished article from research notes',
    inputField: 'content',
  })
  async writeArticle(content: string): Promise<string> {
    return ''; // Body replaced at runtime by AgentRuntime
  }
}

Running the Example

import { AgentRuntime } from '@hazeljs/agent';
import { AIService } from '@hazeljs/ai';

// Setup runtime
const runtime = new AgentRuntime({
  llmProvider: new AIService({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY }),
  defaultMaxSteps: 15,
});

// Register all agents
const orchestrator = new ContentOrchestratorAgent();
const researcher = new ResearchAgent();
const writer = new WriterAgent();

[ResearchAgent, WriterAgent, ContentOrchestratorAgent].forEach(A => runtime.registerAgent(A));
runtime.registerAgentInstance('ContentOrchestratorAgent', orchestrator);
runtime.registerAgentInstance('ResearchAgent', researcher);
runtime.registerAgentInstance('WriterAgent', writer);

// Execute
const result = await runtime.execute(
  'ContentOrchestratorAgent',
  'Write a blog post about multi-agent AI systems',
  { sessionId: 'demo-session-1' }
);

console.log(result.response);
console.log(`Completed in ${result.steps.length} steps`);

Key Benefits

✅ Transparent — LLM doesn't know it's delegating
✅ Type-safe — Full TypeScript support
✅ Observable — All delegations emit events
✅ Simple — Easy to understand and debug

Pattern 2: `AgentGraph` — DAG Workflow Pipelines

What is it?

AgentGraph lets you build directed acyclic graphs (DAGs) of agents and functions. Think LangGraph but TypeScript-native and integrated with HazelJS.

You define:

Nodes — Agents or functions
Edges — Sequential or conditional connections
Entry point — Where execution starts

Architecture

Entry → NodeA → NodeB → END              (sequential)
Entry → Router → NodeA | NodeB → END     (conditional)
Entry → Split → [NodeA ‖ NodeB] → Merge → END (parallel)

When to use it?

Known workflow — You know the steps at design time
Conditional routing — Different paths based on state
Parallel execution — Multiple agents run simultaneously
Complex pipelines — 5+ steps with branching logic

Example 1: Sequential Pipeline

import { END } from '@hazeljs/agent';

const pipeline = runtime
  .createGraph('blog-pipeline')
  .addNode('researcher', { type: 'agent', agentName: 'ResearchAgent' })
  .addNode('writer', { type: 'agent', agentName: 'WriterAgent' })
  .addNode('editor', { type: 'agent', agentName: 'EditorAgent' })
  .addEdge('researcher', 'writer')
  .addEdge('writer', 'editor')
  .addEdge('editor', END)
  .setEntryPoint('researcher')
  .compile();

const result = await pipeline.execute('Write about TypeScript generics');
console.log(result.output);

Example 2: Conditional Routing

// Classifier agent determines the type of request
@Agent({
  name: 'ClassifierAgent',
  systemPrompt: 'Classify the request as "code", "article", or "analysis"',
})
export class ClassifierAgent {
  @Tool({
    description: 'Classify request type',
    parameters: [{ name: 'request', type: 'string', required: true }],
  })
  async classify(input: { request: string }) {
    // Simple classification logic
    if (input.request.includes('code') || input.request.includes('implement')) {
      return { type: 'code' };
    } else if (input.request.includes('analyze')) {
      return { type: 'analysis' };
    }
    return { type: 'article' };
  }
}

const router = runtime
  .createGraph('smart-router')
  .addNode('classifier', { type: 'agent', agentName: 'ClassifierAgent' })
  .addNode('coder', { type: 'agent', agentName: 'CoderAgent' })
  .addNode('analyst', { type: 'agent', agentName: 'AnalystAgent' })
  .addNode('writer', { type: 'agent', agentName: 'WriterAgent' })
  .setEntryPoint('classifier')
  .addConditionalEdge('classifier', (state) => {
    const type = state.data?.type;
    if (type === 'code') return 'coder';
    if (type === 'analysis') return 'analyst';
    return 'writer';
  })
  .addEdge('coder', END)
  .addEdge('analyst', END)
  .addEdge('writer', END)
  .compile();

const result = await router.execute('Implement a binary search algorithm');
// Routes to CoderAgent

Example 3: Parallel Fan-Out / Fan-In

import { GraphState, ParallelBranchResult } from '@hazeljs/agent';

// Function to split task
async function splitTask(state: GraphState) {
  return {
    ...state,
    data: {
      ...state.data,
      split: true,
      timestamp: Date.now(),
    },
  };
}

// Function to merge results
async function mergeResults(state: GraphState) {
  const results = state.data?.branchResults as ParallelBranchResult[];
  const combined = results.map(r => r.output).join('\n\n---\n\n');

  return {
    ...state,
    output: `# Combined Analysis\n\n${combined}`,
  };
}

const parallel = runtime
  .createGraph('parallel-research')
  .addNode('splitter', { type: 'function', fn: splitTask })
  .addNode('parallel-1', {
    type: 'parallel',
    branches: ['tech-researcher', 'market-researcher', 'competitor-researcher'],
  })
  .addNode('tech-researcher', { type: 'agent', agentName: 'TechResearchAgent' })
  .addNode('market-researcher', { type: 'agent', agentName: 'MarketResearchAgent' })
  .addNode('competitor-researcher', { type: 'agent', agentName: 'CompetitorResearchAgent' })
  .addNode('combiner', { type: 'function', fn: mergeResults })
  .addEdge('splitter', 'parallel-1')
  .addEdge('parallel-1', 'combiner')
  .addEdge('combiner', END)
  .setEntryPoint('splitter')
  .compile();

const result = await parallel.execute('Analyze the AI framework market');
console.log(result.output);

Streaming Execution

for await (const chunk of pipeline.stream('Tell me about GraphRAG')) {
  if (chunk.type === 'node_start') {
    console.log(`▶ Starting ${chunk.nodeId}...`);
  }
  if (chunk.type === 'node_complete') {
    console.log(`✓ ${chunk.nodeId}: ${chunk.output?.slice(0, 80)}...`);
  }
  if (chunk.type === 'error') {
    console.error(`✗ Error in ${chunk.nodeId}:`, chunk.error);
  }
}

Visualization

const diagram = pipeline.visualize();
console.log(diagram);
// Outputs Mermaid diagram:
// graph TD
//   researcher --> writer
//   writer --> editor
//   editor --> END

Key Benefits

✅ Visual — Easy to understand workflow structure

✅ Flexible — Sequential, conditional, parallel execution

✅ Composable — Mix agents and functions

✅ Debuggable — Stream execution events

Pattern 3: `SupervisorAgent` — LLM-Driven Routing

What is it?

SupervisorAgent uses an LLM to make routing decisions. It decomposes tasks into subtasks, routes each to the best worker agent, and continues until the task is complete.

Architecture

User Task
    │
Supervisor  ←──────────────────────────┐
    │                                   │
┌───▼────────────────┐           Worker result
│  Route to worker?  │                  │
└───────────┬────────┘                  │
            │                           │
     ┌──────▼──────┐                    │
     │ WorkerAgent │───────────────────┘
     └─────────────┘

When to use it?

Dynamic tasks — Task structure unknown at design time
Complex decomposition — LLM decides how to break down work
Adaptive routing — Route based on worker results
6+ agents — Too many to hardcode routing logic

Code Example

import { SupervisorConfig } from '@hazeljs/agent';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const supervisor = runtime.createSupervisor({
  name: 'project-manager',
  workers: [
    'ResearchAgent',
    'CoderAgent',
    'WriterAgent',
    'EditorAgent',
    'DesignerAgent',
  ],
  maxRounds: 8,
  llm: async (prompt: string) => {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: prompt }],
      temperature: 0.7,
    });
    return response.choices[0].message.content ?? '';
  },
});

const result = await supervisor.run(
  'Build a REST API for a todo app with documentation and tests',
  { sessionId: 'project-001' }
);

console.log(result.response);
console.log(`\nExecution rounds: ${result.rounds.length}`);

result.rounds.forEach((round, i) => {
  console.log(`\nRound ${i + 1}:`);
  console.log(`  Worker: ${round.worker}`);
  console.log(`  Task: ${round.task.slice(0, 80)}...`);
  console.log(`  Result: ${round.workerResult.response.slice(0, 80)}...`);
});

How it works

Supervisor receives task — "Build a REST API..."
LLM decomposes — "First, we need to design the API schema"
Routes to DesignerAgent — Designs API endpoints
Receives result — API schema completed
LLM decides next step — "Now implement the endpoints"
Routes to CoderAgent — Implements the code
Continues — Documentation, tests, etc.
Completes — All subtasks done

Key Benefits

✅ Adaptive — LLM decides routing dynamically

✅ Scalable — Handles many workers easily

✅ Intelligent — Can adjust based on results

✅ Flexible — No hardcoded workflow

Comparison: When to Use Which Pattern?

Pattern	Best For	Complexity	Control	Flexibility
`@Delegate`	2-5 agents, clear hierarchy	Low	High	Low
`AgentGraph`	Known workflows, conditional logic	Medium	High	Medium
`SupervisorAgent`	Dynamic tasks, 6+ agents	High	Low	High

Decision Tree

Do you know the exact workflow at design time?
├─ YES → Use AgentGraph
└─ NO → Is the task highly dynamic?
    ├─ YES → Use SupervisorAgent
    └─ NO → Do you have 2-5 agents with clear roles?
        ├─ YES → Use @Delegate
        └─ NO → Use SupervisorAgent

Complete Example: Content Creation Pipeline

Let's combine all three patterns to build a production-grade content creation system.

System Architecture

User Request → SupervisorAgent
                    ↓
        ┌───────────┴───────────┐
        ▼                       ▼
  ContentGraph            SEOGraph
  (AgentGraph)           (AgentGraph)
        │                       │
        └───────────┬───────────┘
                    ▼
            OrchestratorAgent
            (@Delegate pattern)
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   Research      Writer      Editor

Implementation

See the complete code in the hazeljs-multi-agent-ai-workflows-example repository.

Production Best Practices

1. Error Handling

@Tool({ description: 'Call external API' })
async callAPI(input: { endpoint: string }) {
  try {
    return await this.api.call(input.endpoint);
  } catch (error) {
    return {
      success: false,
      error: (error as Error).message,
      retryable: true,
    };
  }
}

2. Observability

runtime.on(AgentEventType.EXECUTION_STARTED, (e) => {
  logger.info('Agent started', { agentName: e.data.agentName });
});

runtime.on(AgentEventType.TOOL_EXECUTION_COMPLETED, (e) => {
  metrics.increment('tool.executions', { tool: e.data.toolName });
});

3. State Persistence

// Use Redis for production
import { RedisStateManager } from '@hazeljs/agent';

const runtime = new AgentRuntime({
  stateManager: new RedisStateManager({
    redis: redisClient,
    ttl: 3600,
  }),
});

4. Approval Workflows

@Tool({
  requiresApproval: true,
  description: 'Deploy to production',
})
async deploy(input: { environment: string }) {
  // Requires human approval before execution
}

runtime.on(AgentEventType.TOOL_APPROVAL_REQUESTED, async (event) => {
  // Send to approval UI
  await notifyApprovalSystem(event.data);
});

Performance Considerations

Parallel Execution

// Sequential: 30s total
researcher → writer → editor  // 10s + 10s + 10s

// Parallel: 10s total
[tech-research ‖ market-research ‖ competitor-research] → combiner

Context Management

Keep agents focused — Smaller contexts = faster inference
Use delegation — Don't pass full context to every agent
Cache results — Avoid re-running expensive operations

Cost Optimization

// Use cheaper models for routing
const supervisor = runtime.createSupervisor({
  llm: async (prompt) => {
    return await openai.chat.completions.create({
      model: 'gpt-4o-mini', // Cheaper for routing decisions
      messages: [{ role: 'user', content: prompt }],
    });
  },
});

// Use powerful models for specialized work
@Agent({
  name: 'WriterAgent',
  llmConfig: { model: 'gpt-4o' }, // Better for creative writing
})

Conclusion

Multi-agent orchestration is the key to building production-grade AI systems. HazelJS provides three powerful patterns:

@Delegate for simple peer-to-peer delegation
AgentGraph for complex DAG workflows
SupervisorAgent for dynamic LLM-driven routing

Choose the right pattern for your use case, or combine them for maximum flexibility.

Next Steps

Try the example — Clone hazeljs-multi-agent-ai-workflows-example
Read the docs — hazeljs.ai/docs/packages/agent
Join the community — Discord

Resources

Built with HazelJS — Production-grade AI infrastructure for TypeScript.

Questions? Reach out on Discord.

Discovering the HazelJS Ecosystem: A Guide to “Awesome HazelJS

Muhammad Arslan — Wed, 18 Mar 2026 06:52:14 +0000

If you’re building modern AI-powered backends in Node.js, chances are you’ve come across HazelJS — a TypeScript-first framework designed for AI-native applications, agents, and scalable APIs.

Explore HazelJS: https://hazeljs.ai
Documentation: https://hazeljs.ai/docs

But once you start exploring, one big question comes up:

Where do I find the best tools, examples, and resources around HazelJS?

That’s exactly where the “Awesome HazelJS” list comes in.

What is HazelJS (Quick Context)

Before diving in, let’s set the stage.

HazelJS is not just another backend framework — it’s built with AI at its core.

Official Site: https://hazeljs.ai
Docs: https://hazeljs.ai/docs

Key Features

Built-in LLM integrations (OpenAI, Claude, Gemini, etc.)
Agent runtime with tools, memory, and workflows
Native RAG (Retrieval-Augmented Generation)
Modular architecture (install only what you need)

Instead of wiring everything manually, HazelJS lets you build AI systems from day one.

What is “Awesome HazelJS”?

The GitHub repo: https://github.com/hazel-js/hazeljs/blob/main/awesome-hazeljs/README.md

…is a curated collection of resources for the HazelJS ecosystem.

You can also explore the main repository:
https://github.com/hazel-js/hazeljs

What You’ll Find Inside

The Awesome HazelJS list typically includes:

Plugins & packages (@hazeljs/*)
AI agents & RAG examples
Starter templates
Real-world use cases (ML APIs, chatbots, ops agents)
Tools & integrations
Learning resources (blogs, tutorials)

Learn more in docs: https://hazeljs.ai/docs

It’s essentially the entry point into the HazelJS universe.

🧭 How Developers Can Use It Effectively

1. Start with Starter Projects

If you’re new to HazelJS, jump straight into:

ML starter APIs https://github.com/hazel-js/hazeljs-ml-starter
AI/RAG agent examples https://github.com/hazel-js/hazeljs-rag-documents-starter
Flow-based apps https://github.com/hazel-js/hazeljs-flow-starter

Docs for getting started: https://hazeljs.ai/docs/guides/tutorial-rest-api

Example use cases:

Sentiment analysis API
Chat support bot
Fraud detection system

2. Explore AI Capabilities

HazelJS shines in AI workflows. The awesome list helps you discover:

Agent-based systems (multi-step reasoning)
RAG pipelines with vector databases
AI-powered automation (DevOps, support, etc.)

AI module docs: https://hazeljs.ai/docs/packages/ai

3. Find Reusable Modules

Instead of reinventing the wheel, you’ll find packages like:

@hazeljs/ai → LLM integrations
@hazeljs/agent → agent runtime
@hazeljs/rag → vector search + retrieval

Modules overview: https://hazeljs.ai/docs

4. Discover Community Projects

The awesome list is also a community hub.

Explore community resources:

https://github.com/hazel-js/hazeljs/tree/main/awesome-hazeljs

You’ll find:

Independent tools
Experimental ideas
Production-ready examples

5. Learn by Real Use Cases

Instead of abstract docs, you get real-world scenarios:

AI customer support agents
ML inference APIs
Event-driven systems
Chat + messaging platforms

Examples: https://github.com/hazel-js/hazeljs/tree/main/example

Why This Matters

Most frameworks give you:

“Here’s the docs. Good luck.”

HazelJS (and its awesome list) gives you:

“Here’s everything already built — go faster.”

Pro Tips for Using Awesome HazelJS

Star the repo → https://github.com/hazel-js/hazeljs
Check it regularly → new tools are added often
Clone and run examples locally
Contribute your own projects

Contribution guide: https://github.com/hazel-js/hazeljs/blob/main/CONTRIBUTORS.md

Final Thoughts

The Awesome HazelJS list is your shortcut into the ecosystem.

Start here:

https://github.com/hazel-js/hazeljs/blob/main/awesome-hazeljs/README.md

Instead of spending weeks figuring out:

how to build agents
how to integrate RAG
how to structure AI apps

You can:

Start with proven patterns
Learn from real implementations
Ship faster

Call to Action

If you're serious about building AI-powered backends:

Visit HazelJS → https://hazeljs.ai
Read the docs → https://hazeljs.ai/docs
Explore awesome list → https://github.com/hazel-js/hazeljs/blob/main/awesome-hazeljs/README.md

HazelJS v0.2.0 Stable Release

Muhammad Arslan — Tue, 17 Mar 2026 22:57:30 +0000

We’re excited to launch HazelJS v0.2.0 in stable.

In just the last month, the community has already shown up big:

36 GitHub stars
170k+ downloads per month

That momentum matters. It means you’re building, shipping, and asking for the details that make a framework feel predictable when it meets real projects.

What “stable” means here

Stable is our promise that the core developer experience is now consistent and automation-friendly:

generator outputs are easier to reason about (and script)
workflows are “sharp edges first, escape hatches included”
the stack stays modular without turning setup into a scavenger hunt

If you’re coming from beta/alpha, you should feel this immediately when you scaffold and iterate.

AI-native runtime and framework

HazelJS is built for AI applications from the ground up—AI isn’t a plugin you bolt on later, it’s first-class in how you build, compose, and ship.

With the stable v0.2.0 release, the “core” and the “AI” pieces snap together cleanly:

@hazeljs/ai — one unified API for LLM providers (streaming, embeddings, function calling)
@hazeljs/agent — production-ready agent runtime (think → act → persist, tools, memory, and safe execution)
@hazeljs/rag — end-to-end retrieval pipeline (loaders, vector stores, and knowledge-grounded responses)

So you can build AI features using the same patterns you already trust in HazelJS: modules, dependency injection, controllers, and lifecycle hooks.

The headline upgrade: CLI generation, built for automation

HazelJS v0.2.0 makes scaffolding and generation simple, predictable, and automation-ready.

Here are the new “grab-and-go” workflows we’re most excited about:

Start with a quick app skeleton

hazel g app my-api
cd my-api
npm install

No installs or git init run automatically here—just a clean, repeatable starting point.

Generate anything with `setup` (any package)

Need a minimal starter file for a package? Now you can:

hazel g setup swagger
# alias: hazel g st swagger

hazel g setup oauth
hazel g setup prisma

This drops a ready-to-edit *.setup.ts file and prints the next step (npm install @hazeljs/<package>).

Discover everything the CLI can generate

hazel g --list
hazel g --list --list-json

Machine-readable output with `--json`

When you’re generating in CI, you want output you can parse.

Just add --json:

hazel g controller users --json
hazel g setup swagger --json

The CLI prints a single JSON object describing what was created (or would be created in --dry-run mode).

How to try HazelJS v0.2.0

If you want a minimal starting point:

npm install @hazeljs/core @hazeljs/cli

Then scaffold and go:

hazel g app my-app
cd my-app
npm install
npm run dev

For full docs, jump into:

Docs + NPM backlinks (all packages)

Thanks for pushing us to stable

Stable releases don’t happen in a vacuum—they happen because people try the thing, break it, and tell us what to fix.

Thanks for the 36 stars and the 170k+ downloads. We’re ready for the next wave of real-world use, and we’ll keep improving the DX with the same “ship-first” mindset.

— The HazelJS Team

HazelJS CLI Generation Upgrade: faster scaffolding, fewer commands

Muhammad Arslan — Tue, 17 Mar 2026 09:26:15 +0000

The HazelJS CLI is about one thing: shipping. If you’re building APIs, realtime services, or AI features, you shouldn’t be hand-writing boilerplate or hunting for the “right” folder structure.

This release improves the generation workflow so it’s simpler, more consistent, and easier to automate in scripts and CI.

If you’re new here: start at HazelJS on hazeljs.ai, then jump into the docs at Docs.

What’s new

1) A skeleton app generator (like `create-next-app`)

You can now generate a minimal HazelJS application skeleton directly from the generator group:

hazel g app my-app
cd my-app
npm install
npm run dev

This creates a clean starting project using the CLI template (or a fallback minimal structure if the template isn’t available). It intentionally does not run installs or initialize git—so it’s fast and predictable.

If you want the full interactive setup (package selection, installs, git init), hazel new is still there:

hazel new my-app -i

Docs: CLI package • Modules guide

2) “Setup” generator for every HazelJS package

HazelJS has many packages by design—core, auth, cache, workflow, data, AI, agent, RAG, messaging, and more. But adding a new capability shouldn’t start with “go read five docs and stitch code together”.

Use setup to generate a minimal starter file for any package:

# shorthand: st
hazel g setup swagger
hazel g setup kafka
hazel g setup oauth
hazel g setup @hazeljs/guardrails

This creates a small *.setup.ts file with a ready-to-edit snippet and prints the next step (npm install @hazeljs/<package>).

Related: Controllers guide • Providers guide

3) Discovery: list all generators

To see everything the CLI can generate:

hazel g --list

If you want a machine-readable list (for scripts):

hazel g --list --list-json

4) Consistent output + `--dry-run` + `--json`

All generators support:

--dry-run to preview created paths without writing files
--json to print a single JSON object with ok, created (paths), and optional nextSteps

Examples:

hazel g crud user --dry-run
hazel g controller users --json
hazel g setup swagger --json

Example output (with --json):

{"ok":true,"created":["/path/to/project/src/users.controller.ts"]}

In --dry-run --json mode you get the same shape; created lists what would be written.

Why this matters

Modern backends aren’t “just controllers.” You ship authentication, caching, background jobs, workflows, observability, and—more and more—AI primitives like agents and retrieval. The CLI’s job is to remove friction so you can:

start a project instantly,
add a new capability safely,
generate consistent code across a team,
and automate the workflow in CI.

If you try these generators and feel anything is missing, open an issue—we’re optimizing for real-world DX.

DEV Community: Muhammad Arslan

Building Reliable AI in NodeJS with Typescript

What @hazeljs/eval Solves

Install

Core APIs (Quick Overview)

Real-Time Example: Evaluate Live Support Responses

Suggested project structure

package.json

tsconfig.json

eval/golden.realtime.json

src/realtime-eval.ts

Run It

Real-Life Example: SaaS Support Bot in Production

Install extra packages for this real setup

src/real-life-support-eval.ts

Environment variables for real integrations

Why this is "real life"

Why This Pattern Works

Introducing @hazeljs/pubsub: Google Cloud Messaging, HazelJS Style

TL;DR

Why we built it

Purpose of @hazeljs/pubsub

What problems it solves

1) Boilerplate client setup

2) Message handling drift

3) Payload parsing repetition

4) Uneven production behavior

What’s in the box

PubSubModule

PubSubPublisherService

Decorator-based consumers

Acknowledgement controls

Optional subscription auto-create

Practical example: Order workflow fan-out

Producer

Consumer

Quick start

Pub/Sub vs Queue vs Kafka

Production notes

Backlinks and resources

Introducing HCEL: The Most Fluent Way to Build AI Pipelines in TypeScript

What is HCEL?

Why HCEL?

Real-World Examples from Our Codebase

Example 1: Simple HCEL Chain

Example 2: RAG + ML Chain

Example 3: Streaming Chain

Example 4: Chain with Context & Observability

Production-Ready Features

Example 5: Persistent HCEL Chains

Example 6: Parallel Operations

Advanced Orchestration Patterns

Example 7: Flow Engine Integration

How to Run These Examples

Setup

Run the Examples

What Each Example Demonstrates

The Power of Implicit Context

Explicit vs Implicit Context

Context Transformation

Type Safety and IntelliSense

Getting Started with HCEL

Installation

Basic Usage

Advanced Usage

What's Next?

Join the HCEL Community

Conclusion

Real-World Case Study: Automated Support Triage

Try it Today

Resources:

AI-Native CLI Template: Build Production-Ready AI Agents in Minutes in NodeJS

Why an AI-Native Template?

What's Included?

🤖 Advanced Agent Capabilities

1. Execution Tracing (POST /agent/trace)

2. Server-Sent Events Streaming (POST /agent/stream)

3. Multi-Agent Delegation (POST /travel)

4. Supervisor Pattern (POST /travel/supervisor)

💬 AI Chat & RAG

What `@hazeljs/eval` Solves

`package.json`

`tsconfig.json`

`eval/golden.realtime.json`

`src/realtime-eval.ts`

`src/real-life-support-eval.ts`

1. Execution Tracing (`POST /agent/trace`)

2. Server-Sent Events Streaming (`POST /agent/stream`)

3. Multi-Agent Delegation (`POST /travel`)

4. Supervisor Pattern (`POST /travel/supervisor`)