Production AI Agents in Node.js with HazelJS

Build stateful, tool-using AI agents in TypeScript/Node.js with human-in-the-loop, memory, RAG, and HTTP — without bolting LangChain onto Express or Nest.

Quick Reference

Purpose: Intent guide for “production AI agents Node.js” / “TypeScript agent backend”.
When to use: You need agents that pause, resume, call tools safely, and sit behind real APIs.
Key concepts: @Agent, @Tool, Agent Runtime, memory, RAG, approvals, Agent OS, Skillgate.
Dependencies: @hazeljs/core, @hazeljs/agent, optionally @hazeljs/rag, @hazeljs/ai, @hazeljs/testing, @hazeljs/skillgate.
Related: Agent package, Agent OS, Skillgate, Support agent example, vs LangGraph.

What “production” means here

Demo chatbot	Production agent (HazelJS)
Stateless prompt loop	Rich agent state + optional Redis persistence
Unrestricted tools	`@Tool` + `requiresApproval`
No retrieval	`enableRAG` / `@hazeljs/rag`
No HTTP identity	Controllers + auth packages
Manual eval	`@hazeljs/eval` + `describeAgent`
Hope	Agent OS loops, policies, contracts, Inspector

Minimal production agent

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

@Agent({
  name: 'support-desk',
  systemPrompt: 'Resolve customer issues. Prefer tools over guessing.',
  enableMemory: true,
  enableRAG: true,
})
export class SupportDeskAgent {
  @Tool({
    description: 'Fetch order status',
    parameters: [{ name: 'orderId', type: 'string', required: true }],
  })
  async getOrder(input: { orderId: string }) {
    return { orderId: input.orderId, status: 'in_transit' };
  }

  @Tool({
    description: 'Open a refund request',
    requiresApproval: true,
    parameters: [
      { name: 'orderId', type: 'string', required: true },
      { name: 'amount', type: 'number', required: true },
    ],
  })
  async refund(input: { orderId: string; amount: number }) {
    return { status: 'pending_approval', ...input };
  }
}

Serve it from an API

Agents are providers in the same DI graph as controllers. Pattern:

Register agent class on @HazelModule
Inject / resolve Agent Runtime
POST /agents/:name/run with user message + tenant/user metadata

Concrete CSR routes and streaming: Support agent example.

Add orchestration

Pattern	Use
HCEL `.agent(...)`	Fluent pipelines with prompt + RAG + agent
`@Delegate`	Peer agent calls as tools
`AgentGraph`	DAG / conditional multi-step agents
`SupervisorAgent`	LLM-driven routing across specialists
`@hazeljs/flow`	Durable business WAIT/resume (orders, approvals)

Agent OS (beyond a single run)

When you need confidence loops, policies, contracts, recovery, DNA, durable HITL, and CI:

→ Agent OS guide

When you need curated REST → agent skills:

→ Skillgate guide

Example shape (from the product docs):

await runtime.execute('support-desk', message, {
  loop: { maxIterations: 4, successScore: 90 },
  contract: { name: 'support-slo', maxLatencyMs: 30_000, fallbackAgent: 'safe-desk' },
  recovery: { maxRetries: 2, fallbackAgent: 'safe-desk' },
});

Production checklist

Tool schemas explicit; dangerous tools require approval
Memory scoped per user/session
RAG corpus versioned; retrieval evaluated
Auth on HTTP entrypoints
Timeouts, retries, circuit breakers (@hazeljs/resilience)
Traces / Inspector timelines for LLM steps
Golden tests with @hazeljs/testing / eval