Forem: Muhammad Arslan

Building reliable distributed workflows in TypeScript with HazelJS Sagas

Muhammad Arslan — Tue, 12 May 2026 14:28:17 +0000

What problem does a saga solve?

Many business operations are pipelines: do A, then B, then C. In a single database you wrap that in one transaction—if B fails, A rolls back automatically. In the real world, A might be a room hold in a property system, B a card capture at a payment processor, and C an email via a provider. Those systems do not share one transaction log.

Without a structured approach you get ad hoc code: nested try/catch, manual “if payment failed, remember to release inventory” comments, and production bugs where orphan holds or double charges slip through when a step fails or times out.

A saga is a pattern for that situation:

You run the pipeline as a sequence of local steps (each step can succeed or fail on its own).
For steps that must be undone if a later step fails, you define an explicit compensating action—not a generic database rollback, but a business-meaningful reverse (release the hold, refund the charge).
A coordinator (here, SagaOrchestrator) runs the forward steps in order; if one throws, it runs compensators for the steps that already completed, in reverse order.

The purpose of a saga is therefore controlled consistency across independent systems: you accept that there is no global lock, but you refuse to leave the business in an inconsistent state when something breaks mid-flow.

This repository (hazeljs-saga-starter) is a minimal but honest example: a trip booking flow implemented with @hazeljs/saga orchestration inside a small HazelJS HTTP app. You can run it locally and watch both the happy path and a failed payment with automatic compensation.

Why not one giant distributed transaction?

ACID transactions are the right default inside one database. Across payment gateways, PMS/channel managers, and email APIs they are usually not available in a practical form. Two-phase commit is heavy, brittle, and often impossible when vendors only offer REST webhooks.

The saga pattern trades “all-or-nothing in one atomic commit” for:

Clear forward steps (what we try to achieve).
Clear compensators (how we undo what already succeeded if we must abort).

That trade is why sagas show up in checkout, travel, transfers, and provisioning: the workflow spans boundaries you do not control.

Orchestration vs choreography

Orchestration — one place (a class or service) knows the full recipe and calls each step. Easy to read and debug; this starter uses that style.
Choreography — each service reacts to events; the global flow is implicit. Great for very loose coupling; HazelJS also exposes helpers (@SagaChoreography, @OnEvent) for that model.

This example, end to end

We implement a three-step trip booking:

Order	Forward step	What it does (demo)	If we must roll back
1	`holdRoom`	Creates a temporary room hold (`holdId`)	`releaseRoomHold`
2	`chargeGuest`	Captures payment (`paymentReference`)	`refundGuest`
3	`sendConfirmation`	Assigns a confirmation code and logs mail	(no compensator)

Why this order? Inventory is often held before money moves: you do not charge until you know you can fulfill, and you do not want paid bookings with no room. If payment fails after a hold exists, the business rule is: release the hold so another guest can book. The saga encodes that rule as compensation for step 1 when step 2 throws.

What happens when step 2 fails? Only step 1 has completed successfully. The orchestrator compensates in reverse order among completed steps, so it runs releaseRoomHold only. refundGuest does not run in that scenario—there was no successful charge to refund. (If step 3 failed after a successful charge, you would see refundGuest then releaseRoomHold; your real product might define different rules for that edge.)

The demo uses in-memory HotelService, PaymentService, and NotificationService. They stand in for HTTP clients; the saga class would look the same if those methods called external APIs.

The saga in code (`TripBookingSaga`)

The workflow lives in src/sagas/trip-booking.saga.ts:

@Saga({ name: 'trip-booking' }) registers this flow under a stable name the orchestrator can start by string.
@SagaStep({ order: 1, compensate: 'releaseRoomHold' }) marks holdRoom as the first forward step and names the method to call to undo it.
@SagaStep({ order: 2, compensate: 'refundGuest' }) does the same for payment.
@SagaStep({ order: 3 }) is the final step; it has no compensate hook in this demo (you could add one later, e.g. “send cancellation email,” if step 3 could fail after side effects).

Compensator methods (releaseRoomHold, refundGuest) are ordinary async methods on the same class; they are not decorated with @SagaStep because they only run during rollback.

Important implementation detail: SagaOrchestrator.start('trip-booking', state) passes the same object into every forward step and compensator. The starter’s TripBookingState is therefore mutated as the saga runs: holdId appears after step 1, paymentReference after a successful step 2, confirmationCode after step 3. That mirrors how teams often thread a “booking draft” DTO through a pipeline without a separate context bag.

How HazelJS triggers the saga (`BookingController`)

The HTTP layer does not use dependency injection for the saga registry. Instead, loading the saga module runs the class decorator and registers the workflow once. In app.module.ts you will see:

import "./sagas/trip-booking.saga";

That import exists for its side effect so the orchestrator knows about trip-booking before any request arrives.

BookingController (src/booking.controller.ts) handles POST /bookings: it builds a TripBookingState from JSON (including simulatePaymentFailure for demos), then:

const context = await SagaOrchestrator.getInstance().start(
  "trip-booking",
  state,
);

The response includes:

status — e.g. COMPLETED or ABORTED (after compensation).
steps — each forward step’s outcome, and which steps were marked compensated.
data — the same state object, now filled with ids on success.
failureReason — when a step threw, the error message is surfaced for debugging.

GET /bookings/audit-log reads the in-memory notification log so you can see that a confirmation was actually “sent” on success, or inspect side effects while learning.

What to try with `curl`

Happy path — all steps succeed; response shows COMPLETED, a holdId, paymentReference, and confirmationCode.

Failure path — send "simulatePaymentFailure": true. PaymentService.capture throws; the orchestrator moves the saga to a compensating phase, releases the hold, and returns ABORTED. In the steps array you should see the payment step as failed and the inventory step as compensated—a concrete picture of what “rollback” means here.

That visibility is the point of the example: you can reason about purpose (keep inventory and money aligned) and mechanism (decorators + orchestrator + compensators) without Kafka or a workflow engine.

Orchestration vs choreography (again, in HazelJS terms)

For this booking story, orchestration wins because:

The sequence and compensations fit in one class that new teammates can read top to bottom.
Support and incident response benefit from a single named workflow (trip-booking) tied to logs and HTTP responses.

Choreography remains valuable when many teams publish and subscribe to events and no one team should own the full script. HazelJS documents that path separately; the mental model for purpose is the same—explicit recovery—only the coordination style changes.

Before you ship something like this to production

This starter is intentionally small. In production you would typically add:

Persistence — store saga id, status, and step results so you can survive process restarts and audit history.
Idempotency — external APIs should accept idempotency keys (often derived from saga id + step name) so safe retries do not double-charge or double-hold.
Timeouts and async steps — long-running or human-in-the-loop work usually moves to queues and state machines; the orchestrator here runs steps inline in the request.
Compensation failure — if releaseRoomHold itself fails, you need alerting and manual playbooks; no pattern removes that need entirely.

Try it

Get the code:

git clone https://github.com/hazel-js/hazeljs-saga-starter.git
cd hazeljs-saga-starter

Repository: github.com/hazel-js/hazeljs-saga-starter.

Then run npm install and npm run dev (see README.md for port and curl snippets). d

A saga is not magic—it is explicit failure design: you document how success looks and how you undo partial success when the world says no. @hazeljs/saga gives you a thin, decorator-first way to express that in TypeScript next to your HazelJS controllers.

Last updated: @hazeljs/saga orchestration API, HazelJS 0.8.x.

Build an MCP Server in Node.js & TypeScript: A Practical HazelJS Tutorial

Muhammad Arslan — Sat, 09 May 2026 17:02:16 +0000

Expose your existing TypeScript classes to Cursor, Claude Desktop, and any other Model Context Protocol (MCP) client — without writing protocol code, without a heavy SDK, and without standing up a separate HTTP service.

This post walks through the hazeljs-mcp-starter example in this folder: a small but realistic task board MCP server, written in TypeScript, that you can run locally with node dist/main.js and immediately drop into your AI tooling. It is not another "hello world" — every pattern below is the same one you would use to ship an internal support agent, a runbook automation server, or an admin operations panel for your team.

By the end you will know:

What MCP actually is (and is not), at the wire level
Why a tiny abstraction like @hazeljs/mcp beats writing JSON-RPC by hand
How to define tools with @Tool() decorators in idiomatic TypeScript
How to wire the resulting server into Cursor and Claude Desktop
How to test it without an LLM in the loop
How to evolve from in-memory toy code to a production-grade tool server (validation, persistence, observability, security)

Source code: hazel-js/hazeljs-mcp-starter on GitHub. Clone it and follow along:
git clone git@github.com:hazel-js/hazeljs-mcp-starter.git
cd hazeljs-mcp-starter
npm install

1. What is the Model Context Protocol, really?

MCP is a small, open JSON-RPC 2.0 protocol for one job: letting an AI client (Cursor, Claude Desktop, an SDK, your own runner) discover and invoke tools and resources exposed by a server. The wire format is intentionally boring — newline-delimited JSON over stdio (or HTTP/SSE) — which is what makes it portable.

The methods you'll see in practice are:

Method	Direction	Purpose
`initialize`	client → server	Handshake; server returns name, version, capabilities
`ping`	either	Liveness check
`tools/list`	client → server	Server returns its tool catalog (with JSON Schema)
`tools/call`	client → server	Server runs a named tool with arguments

A tool, on the wire, is just a name + description + JSON Schema for inputs. When the model decides to call it, the client sends tools/call, the server runs the corresponding function, and the result comes back as a content block (typically { type: 'text', text: '...' }).

That is the entire surface area. Everything else — auth, persistence, validation, observability — is your application's job, exactly as it would be for any other JSON-RPC service. MCP is plumbing, not a framework.

Why the protocol is small (and why that matters)

Because MCP is so minimal, the same server that Cursor talks to today can be consumed tomorrow by Claude Desktop, an OpenAI client, your in-house agent runtime, or a bash one-liner. You write the business logic once and let the transport carry it. That is the central value proposition we'll lean on for the rest of the article.

2. Why use `@hazeljs/mcp` instead of writing the protocol by hand?

Spec-correct JSON-RPC + MCP is not hard, but it's repetitive: parsing newline-delimited frames, routing methods, mapping your domain types to JSON Schema, formatting error envelopes with the right code values, preserving this context across decorator-based handlers, and so on. @hazeljs/mcp does all of that in roughly 200 lines, with zero runtime dependencies, so you can drop it into any Node.js project without dragging in a transport SDK or an LLM client.

Concretely, the package gives you three pieces:

HazelToolAdapter — a transport-agnostic adapter that maps Hazel-style ToolMetadata (what @Tool() produces) to MCP's McpToolDefinition and dispatches tools/call to the right method, with the original this binding intact.
A request router — pure async function over McpRequest → McpResponse, easy to plug into stdio (provided), HTTP, or SSE.
A stdio transport — listenStdio() wires the router to process.stdin / process.stdout and handles concurrent in-flight calls without head-of-line blocking.

It also pairs with @hazeljs/agent, which provides the @Tool() decorator and ToolRegistry. The registry is the same one Hazel agents use internally, so a tool you write for your agent is automatically MCP-ready without a second tool definition format.

If you already have a ToolRegistry running inside your agent, you do not need to redefine anything. The same registry instance can be passed to createMcpServer() to project that tool surface to MCP clients.

3. What the starter does (and why a task board?)

A task board has just enough domain logic to be non-trivial: state, IDs, validation, status transitions, filtering. Replace the in-memory store with Prisma, Redis, or your HTTP API and the MCP boundary stays identical. That is the lesson worth taking home.

The starter exposes four tools:

Tool	Inputs	Output	Purpose
`list_tasks`	`status?` ("open"/"done")	`{ tasks: Task[] }`	List all tasks; optional status filter
`add_task`	`title` (string)	`Task`	Create a new open task
`complete_task`	`task_id` (string)	`Task`	Transition a task to `done`
`board_stats`	(none)	`{ open: number, done: number }`	Quick aggregate for the model

Implementation files (linked to GitHub):

src/agents/TaskBoardMcpAgent.ts — domain logic + @Tool() decorators
src/main.ts — registry + createMcpServer() + listenStdio()
tsconfig.json — TypeScript config (notably experimentalDecorators: true)
package.json — pinned npm versions of @hazeljs/agent and @hazeljs/mcp

4. Project layout

hazeljs-mcp-starter/
├── package.json
├── tsconfig.json
├── README.md
├── BLOG.md                ← you are here
└── src/
    ├── main.ts            ← MCP entrypoint
    └── agents/
        └── TaskBoardMcpAgent.ts

A few things to notice:

Single TypeScript project, single output directory. No monorepo gymnastics; tsc -p tsconfig.json writes everything to dist/.
src/main.ts is intentionally tiny. All it does is build the registry, hand it to createMcpServer, and call listenStdio(). Tests should drive the agent class directly, not the transport.
No top-level reflect-metadata import. @Tool() does not need design-time type metadata; only experimentalDecorators is required. Keeping that out of the surface keeps the bundle tiny.

5. The agent class, decorator by decorator

Here is the heart of the starter. Each method has a one-to-one mapping to an MCP tool, with parameter metadata that becomes JSON Schema in tools/list.

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

type TaskStatus = 'open' | 'done';

interface Task {
  id: string;
  title: string;
  status: TaskStatus;
  createdAt: string;
}

/**
 * In-memory task board exposed as MCP tools.
 * Replace the store with Prisma, Redis, or your API — the @Tool surface stays the same.
 */
export class TaskBoardMcpAgent {
  private tasks: Task[] = [];
  private nextId = 1;

  @Tool({
    name: 'list_tasks',
    description: 'List tasks. Optionally filter by status (open or done).',
    parameters: [
      {
        name: 'status',
        type: 'string',
        description: 'Optional filter: "open" or "done"',
        required: false,
      },
    ],
  })
  async listTasks(input: Record<string, unknown>): Promise<{ tasks: Task[] }> {
    const filter = typeof input.status === 'string' ? input.status.toLowerCase() : undefined;
    const tasks =
      filter === 'open' || filter === 'done'
        ? this.tasks.filter((t) => t.status === filter)
        : [...this.tasks];
    return { tasks };
  }

Full file on GitHub: src/agents/TaskBoardMcpAgent.ts

A few design choices worth explaining:

name is decoupled from the method name. listTasks (camelCase) is your TypeScript ergonomics; list_tasks (snake_case) is what the model sees. Keep the model-facing names short, lowercase, and verb-led — they show up in tool palettes and prompts.

description is prompt engineering. The LLM uses descriptions to decide whether to call your tool. "List tasks. Optionally filter by status" is much more useful than "List tasks." Add expected formats and edge cases ("Returns an empty array when no tasks exist"), but stay terse. A long description bloats every tool-routing prompt.

Parameters become a JSON Schema object. Each entry maps directly to a property under inputSchema.properties, with required: true lifting the name into inputSchema.required. Optional fields are declared as required: false and omitted from the required list. The model receives the full schema in tools/list and constructs valid arguments.

Inputs are Record<string, unknown>, not typed at compile time. That is the trade-off of working with an LLM: you cannot trust the shape, you must validate at runtime. We do exactly that with typeof input.status === 'string'. For larger tools, switch to a runtime validator (zod, ajv, valibot) — the package supports schema on @Tool() for Zod-first definitions.

Errors are thrown. When add_task receives an empty title we throw, and the MCP transport converts the exception into a -32603 INTERNAL_ERROR JSON-RPC response. The client surfaces that to the model, which can then retry with a corrected payload. For expected validation failures consider returning { ok: false, error: '...' } instead — that lets you keep HTTP-style semantics in the JSON body and avoids polluting your error logs.

6. The entrypoint: from class to wire

src/main.ts is deliberately five lines of "real" work:

/**
 * MCP entrypoint — started by Cursor / Claude Desktop via STDIO.
 * Build first: npm run build → run dist/main.js
 */
import { ToolRegistry } from '@hazeljs/agent';
import { createMcpServer } from '@hazeljs/mcp';

import { TaskBoardMcpAgent } from './agents/TaskBoardMcpAgent';

const registry = new ToolRegistry();
registry.registerAgentTools('taskboard', new TaskBoardMcpAgent());

const server = createMcpServer({
  name: 'hazeljs-mcp-starter-taskboard',
  version: '1.0.0',
  toolRegistry: registry,
});

server.listenStdio();

What happens, step by step:

new ToolRegistry() creates an empty store of name → ToolMetadata.
registerAgentTools('taskboard', new TaskBoardMcpAgent()) reads decorator metadata off the class, creates fully-qualified entries (taskboard.list_tasks, …) for agent-to-agent dispatch, and keeps the short name ("list_tasks") that MCP clients will see.
createMcpServer(...) snapshots the registry into a HazelToolAdapter, builds the JSON-RPC router, and returns an object with listenStdio() and listTools().
server.listenStdio() attaches the router to process.stdin / process.stdout using a line-buffered reader. From this point forward, the process is a long-lived MCP child.

A subtle point: the registry is snapshotted at server-create time. If you add tools after createMcpServer() they will not show up. That is by design — MCP supports a listChanged capability for dynamic catalogs, but most servers do not need it, and a stable snapshot keeps the adapter simple.

7. The wire protocol, end to end

For an add_task call the conversation looks like this (one JSON object per line, both directions):

Client → server: handshake

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

Server → client

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"hazeljs-mcp-starter-taskboard","version":"1.0.0"},"capabilities":{"tools":{}}}}

Client → server: discover tools

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Server → client (truncated)

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"add_task","description":"Create a new open task with the given title.","inputSchema":{"type":"object","properties":{"title":{"type":"string","description":"Short description of the work item"}},"required":["title"]}}, …]}}

Client → server: call a tool

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_task","arguments":{"title":"Buy milk"}}}

Server → client

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"id\":\"tsk_1\",\"title\":\"Buy milk\",\"status\":\"open\",\"createdAt\":\"2026-05-09T16:49:51.862Z\"}"}],"isError":false}}

Heads up: MCP is JSON-RPC, not a CLI. Typing bare commands like list_tasks into the running server's stdin returns -32700 Parse error — that is the spec correctly rejecting non-JSON input, not a bug.

If you want a friendly REPL on top of these tools, build it as a separate script that consumes the registry directly. The MCP server itself must remain protocol-pure so real clients can talk to it.

8. Running the starter

Clone the hazel-js/hazeljs-mcp-starter repository and install:

git clone git@github.com:hazel-js/hazeljs-mcp-starter.git
cd hazeljs-mcp-starter
npm install
npm run build

You should now have dist/main.js. To run it standalone (it will block on stdin, which is normal):

node dist/main.js

To exercise the protocol without typing JSON by hand, paste these envelopes one per line into the running server's stdin and press Enter after each:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_task","arguments":{"title":"Buy milk"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_tasks","arguments":{}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"board_stats","arguments":{}}}

That's the fastest feedback loop for "did my change break the protocol?" — much faster than a full Cursor reload.

The repository's package.json pins published versions of the HazelJS packages:

"@hazeljs/agent": "0.7.9",
"@hazeljs/mcp": "0.7.9"

9. Wiring Cursor

Add a server entry to .cursor/mcp.json at your project root, with an absolute path to the built dist/main.js. Relative paths sometimes work, but absolute is unambiguous across reloads:

{
  "mcpServers": {
    "hazeljs-taskboard": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hazeljs-mcp-starter/dist/main.js"]
    }
  }
}

Reload the MCP servers (or restart Cursor). The four tools should appear in the tool list, and the model can call them in chat. A natural prompt to try:

"Add a task titled 'Write MCP blog' and another 'Ship starter repo', mark the first one done, then show me board stats."

If something goes wrong, Cursor surfaces the JSON-RPC error code in its MCP logs. -32601 (method not found) usually means the server crashed and a different process is responding; -32603 (internal error) means a tool threw — log the exception in the server to see the real cause.

10. Wiring Claude Desktop (macOS)

In ~/Library/Application Support/Claude/claude_desktop_config.json, add the same command / args pair pointing at your dist/main.js. Restart Claude Desktop. Tool discovery happens automatically on next chat.

The same dist/main.js works for both Cursor and Claude Desktop because MCP is a contract, not a vendor protocol. That's the whole point.

11. From in-memory to production

The starter's array store is a placeholder; here are the swap-ins you will actually want.

Persistence with Prisma

import { PrismaClient } from '@prisma/client';

export class TaskBoardMcpAgent {
  constructor(private prisma: PrismaClient) {}

  @Tool({ name: 'add_task', description: 'Create a new open task', parameters: [
    { name: 'title', type: 'string', description: 'Title', required: true },
  ]})
  async addTask(input: { title: string }) {
    return this.prisma.task.create({
      data: { title: input.title.trim(), status: 'open' },
    });
  }
}

Construct the agent with a PrismaClient once in main.ts; every tools/call reuses the connection pool.

Distributed state with Redis

For multi-process deployments where any worker can serve any call (e.g. a managed agent platform spinning up several MCP children), back the store with Redis. @Tool() doesn't change. The methods just become thin wrappers over redis.hSet / hGetAll.

Calling existing HTTP APIs

The most common path: your tools wrap existing REST or gRPC endpoints. Pass an httpClient (axios, undici, fetch) into the constructor and translate domain calls inside each @Tool(). This is typically the first MCP server a team ships — it gives the model read/write access to systems that are already running, without touching the underlying services.

Schema-first validation with Zod

For anything beyond toy tools, declare a Zod schema instead of a parameters[] array:

import { z } from 'zod';

const AddTaskInput = z.object({
  title: z.string().min(1).max(280),
  priority: z.enum(['low', 'medium', 'high']).default('medium'),
});

@Tool({
  name: 'add_task',
  description: 'Create a new open task',
  schema: AddTaskInput,
})
async addTask(input: z.infer<typeof AddTaskInput>) { ... }

@hazeljs/agent converts the Zod schema to JSON Schema for tools/list and (with guardrails enabled) validates inputs before your method runs. You get autocomplete inside the method body and reject malformed inputs at the boundary, not deep inside business logic.

12. Error handling without surprises

There are two failure modes worth thinking about:

Programmer errors (bugs) should throw. The transport will return a -32603 INTERNAL_ERROR envelope, the client logs it, and you see a stack trace in stderr. Do not catch and swallow these.

User-facing failures (validation, "not found", "already completed") should return a structured result instead of throwing. Example:

async completeTask(input: { task_id: string }) {
  const task = this.tasks.find((t) => t.id === input.task_id);
  if (!task) {
    return { ok: false, error: `No task with id: ${input.task_id}` };
  }
  task.status = 'done';
  return { ok: true, task };
}

The model sees a normal JSON response and can recover gracefully (e.g. ask the user to confirm the ID). Reserve thrown exceptions for "this should never happen" cases.

For protocol-level errors (-32700, -32601, -32602) you don't write any code — the package generates the right envelope automatically.

13. Multi-agent registries

Real systems split tools across domains. You can register multiple agents into the same registry:

const registry = new ToolRegistry();
registry.registerAgentTools('support', new SupportAgent(deps));
registry.registerAgentTools('billing', new BillingAgent(deps));
registry.registerAgentTools('admin', new AdminAgent(deps));

const server = createMcpServer({ name: 'company-tools', version: '1.0.0', toolRegistry: registry });
server.listenStdio();

Tool names must be globally unique at the MCP layer because the adapter keys by short name. Either pick distinct name values (e.g. support_lookup_customer vs billing_lookup_customer) or run separate processes per domain. The latter is often cleaner: it gives you per-domain logging, restart blast-radius, and access controls.

14. Security: what to check before shipping

MCP servers run as child processes of trusted clients, so the threat model is different from a public HTTP API — but it is not zero.

Treat tool inputs as untrusted. The model can be prompt-injected by an upstream document, page, or message, and forwarded inputs reflect that. Validate, escape, and bound everything you pass to your data layer (no raw SQL string-interpolation, no eval, no shell exec without an allowlist).
Don't log secrets. Tools often pass through API keys or PII. Strip secrets from winston / pino events. Hazel's logger supports redaction patterns; use them.
Bound destructive actions behind requiresApproval. @hazeljs/agent lets you mark tools that should pause for human approval. Use it for password resets, refunds, deletes — anything you would not want a model to do unattended.
Pin tool names. Renaming a tool can silently degrade an agent that learned to call it. If you must rename, alias the old name for a deprecation window.

15. Observability

Because the server is "just Node.js," any logger or metrics backend you already use works:

Logs: wrap the agent with a Proxy (or a @hazeljs/agent middleware) that logs tool_name, duration_ms, and is_error for every call. Five lines of code, enormous debugging value.
Metrics: export a counter mcp_tool_calls_total{tool, status} and a histogram mcp_tool_duration_seconds{tool}. Cursor will happily call your tools 10× per chat — you want a graph for that.
Tracing: start a span around each tools/call invocation and propagate it into downstream HTTP/db calls. OpenTelemetry's @opentelemetry/instrumentation-http covers most of it for free.

A nice property of MCP: because every interesting action is a tools/call, you get per-tool telemetry without any framework opinionation — just instrument the adapter once.

16. Comparing alternatives

Approach	Pros	Cons
Hand-written MCP server (no SDK)	Full control, zero deps	You re-implement JSON-RPC framing, error envelopes, JSON Schema mapping
Official MCP TypeScript SDK	Officially maintained, full feature set (resources, prompts, sampling)	Heavier, separate tool definition style; less idiomatic if you already use Hazel decorators
`@hazeljs/mcp` + `@hazeljs/agent`	Single tool definition shared with your agent runtime, ~200-line transport, no deps	Tool-only today (resources/prompts not yet covered)
Custom HTTP API consumed by an agent	Familiar mental model, easy to test	Every IDE / client needs a bespoke integration; not portable
OpenAI-only function calling	First-class in OpenAI clients	Single-vendor; requires your code to be the orchestrator instead of the IDE

For most teams already running TypeScript backends, @hazeljs/mcp hits the sweet spot: write your tools once with @Tool(), expose them to every MCP client today, and migrate to the official SDK later if you need resources/prompts/sampling.

17. Where to go next

Replace the in-memory store with your real data layer (Prisma, Drizzle, MongoDB, or an HTTP client over your existing services).
Add a domain-specific server for each subsystem (support, billing, infra) and register them under separate .cursor/mcp.json entries — one process per blast-radius.
Adopt Zod schemas with @Tool({ schema }) for validated inputs and inferred TypeScript types in the method body.
Wire approvals with requiresApproval: true on destructive tools and configure your client to gate them.
Layer observability (logs + metrics + traces) at the adapter level, not inside each tool.
Read the package source — @hazeljs/mcp on GitHub is small enough to read in 15 minutes and understanding it makes debugging trivial.

The combination of @Tool() and @hazeljs/mcp keeps the server's surface area small: one decorator per method, one registry, one createMcpServer, one line to listen. Your domain logic stays domain logic, the protocol stays plumbing, and any MCP-aware client picks up your tools for free.

References

Starter source on GitHub: hazel-js/hazeljs-mcp-starter
HazelJS @hazeljs/mcp on npm
HazelJS @hazeljs/agent on npm
Model Context Protocol specification
JSON-RPC 2.0

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

Forem: Muhammad Arslan

Building reliable distributed workflows in TypeScript with HazelJS Sagas

What problem does a saga solve?

Why not one giant distributed transaction?

Orchestration vs choreography

This example, end to end

The saga in code (TripBookingSaga)

How HazelJS triggers the saga (BookingController)

What to try with curl

Orchestration vs choreography (again, in HazelJS terms)

Before you ship something like this to production

Try it

Build an MCP Server in Node.js & TypeScript: A Practical HazelJS Tutorial

1. What is the Model Context Protocol, really?

Why the protocol is small (and why that matters)

2. Why use @hazeljs/mcp instead of writing the protocol by hand?

3. What the starter does (and why a task board?)

4. Project layout

5. The agent class, decorator by decorator

6. The entrypoint: from class to wire

7. The wire protocol, end to end

8. Running the starter

9. Wiring Cursor

10. Wiring Claude Desktop (macOS)

11. From in-memory to production

Persistence with Prisma

Distributed state with Redis

Calling existing HTTP APIs

Schema-first validation with Zod

12. Error handling without surprises

13. Multi-agent registries

14. Security: what to check before shipping

15. Observability

16. Comparing alternatives

17. Where to go next

References

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

The saga in code (`TripBookingSaga`)

How HazelJS triggers the saga (`BookingController`)

What to try with `curl`

2. Why use `@hazeljs/mcp` instead of writing the protocol by hand?

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`)