DEV Community: Nisa Fatima

Curate a CMS API into 7 Governed Agent Skills with NodeJS

Nisa Fatima — Mon, 10 Aug 2026 18:52:59 +0000

A production CMS is a sprawl of endpoints: content types, entries, media, users, webhooks, plugins, settings, admin routes. Hand an agent all of it and the agent gets worse, not better. The model's tool selection drifts as the list grows, and half the tools are things a publishing assistant should never be able to call.

The point of this post is the opposite move. Instead of exposing an API and hoping the agent behaves, you curate a small, labeled surface up front. HazelJS Skillgate does that curation from an OpenAPI spec, and that is the part we actually build and run here.

Scope, up front

This post is about curation and classification: taking a spec with many endpoints and turning a chosen slice of it into governed skills. Skillgate selects the surface, marks read versus write, and would deny destructive methods if they ever entered that surface.

Turning a write's approval flag into a real human-approval pause, and enabling an LLM to drive the skills, are runtime concerns handled elsewhere in Agent OS. This demo does not implement them, and this post does not claim it does. What it does show is the curation, and that stands on its own.

The tool-explosion problem

Point an LLM at a full CMS API and you hit four problems at once: tool selection degrades as options pile up, throughput drops while the model reasons over a long list, you lose visibility into what the agent can actually do, and dangerous operations sit one bad call away.

The demo spec here is deliberately smaller than a real CMS, 27 endpoints rather than hundreds, but the problem is identical. Even 27 is too many, and most of them are things a publishing agent has no business touching.

From REST endpoint to agent skill

Skillgate's input is an ordinary REST API described by an OpenAPI spec: the same entries, media, and user routes a CMS already exposes. Each endpoint is described in the standard OpenAPI shape, a method, a path, parameters, a description, and tags. Two representative operations from the spec look like this:

[
  {
    "operationId": "listEntries",
    "summary": "List entries",
    "method": "get",
    "path": "/api/entries",
    "tags": ["entries", "read-only", "editorial"]
  },
  {
    "operationId": "publishEntry",
    "summary": "Publish entry",
    "method": "post",
    "path": "/api/entries/{entryId}/publish",
    "tags": ["entries", "write", "editorial", "approval-required"]
  }
]

Skillgate reads each operation and generates one skill from it. The two skills it produced for those endpoints are:

[
  { "name": "listEntries", "method": "GET", "class": "read", "readOnly": true, "requiresApproval": false },
  { "name": "publishEntry", "method": "POST", "class": "write", "readOnly": false, "requiresApproval": true }
]

The mapping is direct:

The operation name and description become the skill's name and description. That text is what a model reads to decide when to reach for the skill.
Any parameters the endpoint declares become the skill's typed inputs. This demo spec keeps them minimal, but a fuller spec's path, query, and body parameters map through the same way.
The HTTP method decides the class. GET becomes read, POST, PUT, and PATCH become write and pick up the approval flag, and DELETE is destructive.
The tags decide inclusion. Only operations tagged editorial pass the opt-in filter and become skills at all.
The invoke config from the next section (base URL and headers) is how a skill runs. Calling it makes the real HTTP request to that endpoint and returns the response.

So "turning a CMS API into an agent" is concretely this: for each editorial-tagged endpoint, one tool with inputs mirrored from the spec, a risk class assigned from the method, and a live HTTP call behind it. Everything untagged never becomes a tool. The model planning over those tools is the runtime step that needs an LLM. The transformation and the curation are what Skillgate does, and the report proves both.

The configuration

Curation is a single call. This is the real config from the project:

Skillgate.fromOpenApi(cmsOpenApiSpec, {
  agentName: 'cms-publisher',
  invoke: {
    baseUrl: process.env.CMS_API_BASE_URL || 'http://localhost:5000',
    headers: {
      Authorization: 'Bearer ${CMS_API_TOKEN}',
      'Content-Type': 'application/json',
    },
    ssrfProtection: false,
  },
  include: {
    mode: 'opt-in',
    tags: ['editorial'],
  },
  warnAbove: 12,
  maxTools: 24,
  strictDescriptions: true,
})

The whole curation lives in one place: include.mode: 'opt-in' with tags: ['editorial']. Nothing becomes a skill unless it carries the editorial tag. Everything else in the spec is simply not considered.

What Skillgate produced

The spec has 27 endpoints. After the opt-in editorial filter, Skillgate registered 7 skills and denied none:

2 read-only: listEntries, getEntry
5 writes flagged for approval: createEntry, updateEntry, publishEntry, scheduleEntry, unpublishEntry

That is the entire agent surface. Twenty of the twenty-seven endpoints never enter the picture.

Where the dangerous routes went

This is the most useful thing to understand about the result, and it's a place the obvious mental model gets it slightly wrong.

The spec does contain destructive operations: deleteContentType, deleteEntry, deleteMedia, deleteUser, deleteWebhook, uninstallPlugin. None of them show up as denied in the report. They are kept away from the agent by the opt-in tag filter, because none of them carry the editorial tag, so they are never even considered for classification. The report's denied list is empty, and that is expected.

So there are two independent mechanisms protecting you, and this demo leans on the first:

The opt-in filter never lets an untagged route become a candidate.
Classification would deny a destructive method if it did become a candidate. If someone tagged a DELETE route editorial, Skillgate would class it destructive and deny it unless you set allowDestructive.

Two locks on the same door. The demo shows the tag-filter lock doing the work.

The proof: the report

Skillgate can print exactly what it curated. This is a trimmed slice of the real report() output, one read skill and one write skill:

{
  "included": [
    {
      "name": "listEntries",
      "method": "GET",
      "path": "/api/entries",
      "tags": ["entries", "read-only", "editorial"],
      "class": "read",
      "readOnly": true,
      "requiresApproval": false
    },
    {
      "name": "publishEntry",
      "method": "POST",
      "path": "/api/entries/{entryId}/publish",
      "tags": ["entries", "write", "editorial", "approval-required"],
      "class": "write",
      "readOnly": false,
      "requiresApproval": true
    }
  ],
  "denied": [],
  "warnings": []
}

The full report lists all seven skills. Every write in the set carries requiresApproval: true, which brings us to the honest limit of the demo.

The approval flag is a contract, not the enforcement

Every write here is labeled requiresApproval: true, including publish and schedule. That label is Skillgate's classification: a contract that says these operations should not run without a human in the loop.

The label is not the pause. Enforcing it, suspending the run, capturing a decision, resuming after a crash, is the Agent OS runtime's job, not Skillgate's, and it is not wired into this demo. Calling a write here does not produce a real approval pause. What the demo does prove is that the sensitive operations were separated from the safe ones and tagged as such before any model saw the list. The enforcement layer is documented in the Agent OS and Gamma links at the end.

Tool-count guardrails

warnAbove: 12 and maxTools: 24 guard against tool explosion. Skillgate warns past twelve tools and refuses past twenty-four, which forces you to justify the surface instead of dumping the whole API.

At seven skills this demo sits well under the line, so the guardrail does not fire here. It is the mechanism that would stop a careless tags filter from pulling in fifty endpoints, which is the entire reason curation is opt-in rather than opt-out.

MCP export

The project exposes an MCP export entry point, wired to skillgate.toMcpServer():

curl -s http://localhost:3001/cms/mcp/export

The idea is that the same curated, classified skills can be surfaced to an MCP client so an editor triggers them from their own tooling rather than a separate dashboard. To be clear about the state of this demo: the export entry point exists, but a working editor integration is not wired up. Treat this as the seam where that integration would attach, not as a finished feature.

Run it

npm install --legacy-peer-deps
npm run build
npm run dev

The app runs on http://localhost:3001, with the HazelJS Inspector at http://localhost:3001/__hazel.

Print the curation decision:

curl -s http://localhost:3001/cms/skillgate/report

One honest setup note, the same as the DevOps demo: no LLM provider is configured out of the box, so on boot you'll see "No AI providers configured." Skillgate performs its curation and produces the report with or without a model attached. Add a provider when you want an agent loop to actually plan over these seven skills.

Environment variables, all optional for the demo:

PORT (defaults to 3001)
CMS_API_BASE_URL (defaults to http://localhost:5000)
CMS_API_TOKEN (used in the auth header, not required for the demo)

What's real today, and what's next

Real and reproducible right now:

27 endpoints curated down to 7 via a single editorial tag filter
Read and write classes assigned automatically
Six destructive routes kept out of the surface entirely
A printable report of the whole decision
An MCP export entry point

The layers you would add next:

Enforcing the requiresApproval flags as live approval pauses
Making those pauses crash-safe with durable runs
A real MCP editor integration on top of the export
An LLM so the agent can plan and call the curated skills

Complete Project: CMS Publishing Agent

Takeaway

"Turn any API into an agent" is only honest with one word attached: curation. You do not turn every endpoint into a tool. You choose a small, labeled subset, and Skillgate makes that choice explicit, auditable, and safe by default. Here that meant 27 endpoints becoming 7, with every destructive route left outside the door. That focused surface is what keeps an agent's tool selection sharp, and it is worth building before you ever attach a model.

Learn more

HazelJS Agent OS: https://hazeljs.ai/agent-os
Skillgate guide: https://hazeljs.ai/docs/guides/skillgate
MCP package: https://hazeljs.ai/docs/packages/mcp
Agent OS Gamma (durable runs, crash-safe HITL, SQL stores): https://hazeljs.ai/blog/agent-os-gamma-durable-runs

Turn a DevOps API into Governed Agent Skills with NodeJS

Nisa Fatima — Mon, 10 Aug 2026 18:51:13 +0000

It's 3 AM. A production service is misbehaving, you're on-call, and you'd love an agent that can pull the service's health and tee up a restart for you. The catch is obvious: an agent with raw access to a DevOps API is a liability. One bad call could scale you into a huge bill or delete an incident record you needed.

So the real question isn't "can the agent reach the API." It's "which calls should it be allowed to make at all, and how should the dangerous ones be treated differently from the safe ones." That decision is what Skillgate handles, and it's the part we actually build and run in this post.

Scope, up front

This post is about the classification and curation layer: turning an OpenAPI spec into a governed set of skills. Skillgate decides which endpoints become tools, marks which are read-only, flags which writes should require approval, and denies the destructive ones outright.

Wiring an approval flag to a live human-approval pause, and making that pause survive a crash, is the job of the Agent OS runtime, not Skillgate. We link to it at the end. The demo here does not implement that runtime, and this post does not pretend it does.

The problem Skillgate solves

Point an LLM at a DevOps API and you have three bad options:

Expose nothing. The agent is useless.
Expose everything. Now the model can call DELETE and scale on a whim.
Hand-whitelist every route. It works until the API changes, then it rots.

Skillgate replaces all three with opt-in curation plus automatic risk classification. You choose a small surface, and every endpoint on it gets a class based on its method and shape.

From REST endpoint to agent skill

Skillgate's input is an ordinary REST API described by an OpenAPI spec. Nothing about the API is agent-aware. It's the same deploy, scaling, and incident routes your platform already exposes. Each endpoint is described in the standard OpenAPI shape: a method, a path, some parameters, a description, and tags. A representative operation from the DevOps spec looks like this:

{
  "operationId": "getServiceLogs",
  "summary": "Get service logs",
  "method": "get",
  "path": "/api/services/{serviceId}/logs",
  "tags": ["services", "read-only"],
  "parameters": [
    { "name": "serviceId", "in": "path", "type": "string", "required": true },
    { "name": "lines", "in": "query", "type": "integer" }
  ]
}

Skillgate reads each operation like that and generates one agent skill from it. The skill it produced for this endpoint is:

{
  "name": "getServiceLogs",
  "description": "Get service logs",
  "method": "GET",
  "path": "/api/services/{serviceId}/logs",
  "parameters": [
    { "name": "serviceId", "in": "path", "type": "string", "required": true },
    { "name": "lines", "in": "query", "type": "integer" }
  ],
  "class": "read",
  "readOnly": true,
  "requiresApproval": false
}

The mapping is direct:

The operation's name and description become the skill's name and description. That text is what a model reads to decide when to reach for the skill, which is why strictDescriptions: true in the config matters.
The endpoint's parameters become the skill's typed inputs. The model fills serviceId and lines the same way it fills any function's arguments.
The HTTP method decides the class. GET becomes a read skill, POST, PUT, and PATCH become write skills that pick up an approval flag, and DELETE is destructive.
The invoke config from the next section (base URL and headers) is how the skill runs. When the skill is called, Skillgate makes the real HTTP request to that endpoint and hands the response back.

So "turning a REST API into an agent" is concretely this: one tool per selected endpoint, with typed inputs mirrored from the spec, a risk class assigned from the method, and a live HTTP call behind it. The model planning over those tools is the runtime step that needs an LLM attached. The transformation itself is what Skillgate does, and the report later in this post is the proof of it.

The configuration

The whole setup is one call. This is the real config from the project:

Skillgate.fromOpenApi(devOpsOpenApiSpec, {
  agentName: 'devops-on-call',
  invoke: {
    baseUrl: process.env.DEVOPS_API_BASE_URL || 'http://localhost:4000',
    headers: {
      Authorization: 'Bearer ${DEVOPS_API_TOKEN}',
      'Content-Type': 'application/json',
    },
    ssrfProtection: false,
  },
  include: {
    mode: 'opt-in',
    tags: ['services', 'deployments', 'incidents'],
  },
  warnAbove: 12,
  maxTools: 24,
  strictDescriptions: true,
})

A few choices worth calling out:

include.mode: 'opt-in' with a tags filter means nothing becomes a skill unless you asked for it. Only endpoints tagged services, deployments, or incidents are considered.
warnAbove and maxTools are the tool-count guardrails. More on those below.
ssrfProtection is off here because the target is a first-party service on localhost. Turn it on when your base URL points at an external host.

The spec itself is loaded from a local TypeScript file in this demo, not fetched from a URL or a running server.

What Skillgate produced

The DevOps spec has ten endpoints: five GET, four POST, one DELETE. After the opt-in tag filter and classification, Skillgate registered:

9 included skills
1 denied skill

Of the nine included: five are read-only with no approval flag, and four are writes flagged as requiring approval. The denied one is the DELETE.

Here are the endpoints it exposed:

GET  /api/services
GET  /api/services/{serviceId}/status
GET  /api/services/{serviceId}/logs
GET  /api/services/{serviceId}/metrics
POST /api/services/{serviceId}/restart
POST /api/services/{serviceId}/scale
POST /api/deployments
POST /api/deployments/{deploymentId}/rollback
GET  /api/incidents

The proof: the report

Skillgate can print exactly what it decided. This is a trimmed slice of the real report() output, one read skill, one write skill, and the denied one:

{
  "included": [
    {
      "name": "getServiceStatus",
      "method": "GET",
      "path": "/api/services/{serviceId}/status",
      "class": "read",
      "readOnly": true,
      "requiresApproval": false
    },
    {
      "name": "restartService",
      "method": "POST",
      "path": "/api/services/{serviceId}/restart",
      "class": "write",
      "readOnly": false,
      "requiresApproval": true
    }
  ],
  "denied": [
    {
      "name": "deleteIncident",
      "method": "DELETE",
      "path": "/api/incidents/{incidentId}",
      "class": "destructive",
      "denied": true,
      "denyReason": "destructive method DELETE denied (set classify.allowDestructive to allow)"
    }
  ],
  "warnings": []
}

The full report lists all nine included skills plus the denied one. Every entry carries its class, its readOnly flag, and its requiresApproval flag, so the governance decision is visible and auditable before the model ever sees a tool.

How the classification works

The model is simple and predictable:

GET becomes a read skill. Safe, no approval flag.
POST becomes a write skill with requiresApproval: true.
DELETE is classed destructive and denied unless you set allowDestructive.

One honest detail about admin and internal routes. In this demo they aren't denied by an explicit rule, they're simply never tagged into the opt-in surface, so the tag filter leaves them out. Both paths get you to the same place: they don't become tools.

The flag is a contract, not the enforcement

This is the part the first draft of this post got wrong, so it's worth being precise.

requiresApproval: true is metadata that Skillgate attaches to a skill. It's the contract that says "this operation should not run unhelped." The enforcement, pausing a run, capturing a human decision, and resuming after a crash, lives in the Agent OS runtime, not in Skillgate.

So in this demo, Skillgate has already done the valuable part: it separated the safe operations from the sensitive ones and blocked the destructive one, before any model touched the list. Turning the approval flag into a real pause is the next layer, covered in the Agent OS and Gamma docs linked at the end.

Tool-count guardrails

warnAbove: 12 and maxTools: 24 exist to stop tool explosion. Models pick poorly once the tool list gets long, so Skillgate warns past twelve tools and refuses past twenty-four.

With nine skills, this demo sits comfortably under the line, so the guardrail doesn't fire here. It's the same mechanism that would stop you dumping a two-hundred-endpoint API onto a model, which is the whole subject of the companion CMS post.

Run it

npm install --legacy-peer-deps
npm run build
npm run dev

The app runs on http://localhost:3000, with the HazelJS Inspector at http://localhost:3000/__hazel.

Print the governance decision:

curl -s http://localhost:3000/devops/skillgate/report

One honest setup note: no LLM provider is configured out of the box. On boot you'll see "No AI providers configured. Set API keys or enable Ollama with OLLAMA_ENABLED=true." That means this runs as a classification demo. Skillgate does its curation and produces the report whether or not a model is attached. Add a provider when you want to drive an actual agent loop against these skills.

Relevant environment variables, all optional for the demo:

PORT (defaults to 3000)
DEVOPS_API_BASE_URL (defaults to http://localhost:4000)
DEVOPS_API_TOKEN (used in the auth header, not required for the demo)

What's real today, and what's next

Real and reproducible right now:

OpenAPI in, curated and classified skills out
Read, write, and destructive classes assigned automatically
The destructive DELETE denied by default, with a clear reason
A printable report of every decision

The runtime layer you would add next:

Turning the requiresApproval flag into a live human-approval pause
Making that pause crash-safe with durable runs and SQL-backed state
Attaching an LLM so the agent can actually plan and call these skills

Complete Project: DevOPs on call Agent

Takeaway

HazelJS Skillgate is the gate that decides which endpoints become tools and how each one is classed, before the model touches anything. That curation and classification is genuinely useful on its own: it's the difference between handing an agent a raw API and handing it a short, labeled, pre-governed set of skills. The enforcement of those labels is a separate and well-documented layer, and that's exactly how it should be.

Learn more

HazelJS Agent OS: https://hazeljs.ai/agent-os
Skillgate guide: https://hazeljs.ai/docs/guides/skillgate
Agent OS Gamma (durable runs, crash-safe HITL, SQL stores): https://hazeljs.ai/blog/agent-os-gamma-durable-runs

Building an Escape Room Puzzle Designer in typescript with NodeJS

Nisa Fatima — Wed, 29 Jul 2026 17:33:20 +0000

Escape rooms have become increasingly popular as interactive entertainment experiences. The key to a great escape room lies in its puzzles—they need to be challenging enough to be engaging, but not so difficult that players become frustrated. In this post, we'll build an Escape Room Puzzle Designer using HazelJS that helps create balanced puzzles, provide progressive hints, and track player solutions.

The Problem

Escape room designers face several challenges:

Puzzle Creation: Designing engaging puzzles with clear solutions
Difficulty Balancing: Ensuring puzzles are appropriately challenging for the target audience
Hint Management: Providing progressive hints that guide without spoiling
Solution Tracking: Verifying solutions and analyzing player performance

Our agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered puzzle search, and intelligent difficulty balancing.

Architecture Overview

The Escape Room Puzzle Designer uses a multi-agent architecture where each agent specializes in a specific aspect of puzzle design:

PuzzleDesignerAgent: Designs escape room puzzles with type, difficulty, theme, and solution
DifficultyBalancerAgent: Balances puzzle difficulty and estimated time for optimal player experience
HintProviderAgent: Provides progressive hints for puzzles based on hint level
SolutionTrackerAgent: Tracks puzzle solutions, verifies correctness, and analyzes performance
PuzzleManagerAgent: Orchestrates the workflow using supervisor routing

This separation allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them.

RAG-Powered Puzzle Search

One of the key features of our agent is the ability to search through a database of puzzles using Retrieval-Augmented Generation (RAG). We maintain a knowledge base of puzzles with metadata including:

Type (logic, pattern, riddle, physical, code-breaking)
Difficulty (easy, medium, hard, expert)
Estimated time to solve
Theme (detective, sci-fi, fantasy, horror, adventure)
Required items

When a designer asks about puzzles, the PuzzleDesignerAgent uses semantic search to find relevant puzzles based on their query. For example, a query like "Find logic puzzles with detective theme" would return puzzles matching those criteria.

The RAG implementation uses HazelJS's RAGPipeline with a MemoryVectorStore for efficient semantic search:

@Service()
export class PuzzleKnowledgeBaseService {
  private readonly embeddings = new LocalPuzzleEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.search(query, topK);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        type: source.metadata?.type,
        difficulty: source.metadata?.difficulty,
        theme: source.metadata?.theme,
        estimatedTime: source.metadata?.estimatedTime,
      })),
    };
  }
}

Intelligent Difficulty Balancing

The DifficultyBalancerAgent takes a puzzle and adjusts its parameters to match target difficulty and time constraints. It considers:

Current vs. target difficulty: Calculates the adjustment needed (increase or decrease complexity)
Time constraints: Adjusts puzzle elements to fit within target time
Hint count: Adjusts the number of hints based on difficulty level
Complexity analysis: Provides complexity descriptions for each difficulty level

The balancer provides detailed analysis including difficulty adjustment recommendations, time adjustment suggestions, and complexity descriptions. This helps designers create puzzles that are appropriately challenging for their target audience.

Progressive Hint System

The HintProviderAgent implements a progressive hint system that guides players without spoiling the solution. It provides:

Hint levels: Subtle (level 1), moderate (level 2), direct (level 3), and solution (level 4)
Context-aware hints: Hints are tailored to the specific puzzle and current progress
Hint progression: Tracks which hints have been provided and what remains
Remaining hints: Shows how many hints are still available

This progressive approach ensures that players get the right level of help at the right time, maintaining the challenge while preventing frustration.

Solution Verification

The SolutionTrackerAgent verifies player solutions using similarity scoring. It:

Verifies correctness: Compares proposed solutions against the actual solution
Similarity scoring: Uses edit distance to calculate similarity for partial matches
Performance tracking: Tracks attempts, hints used, and time taken
Performance analysis: Provides performance ratings based on attempts and difficulty

The agent maintains solution history for each puzzle, allowing designers to analyze which puzzles are too easy or too difficult based on player performance data.

Supervisor Routing

The PuzzleManagerAgent uses HazelJS's supervisor routing to coordinate between the specialist agents. When a designer makes a request, the supervisor analyzes the request and routes it to the appropriate specialist:

Puzzle design requests go to PuzzleDesignerAgent
Difficulty balancing requests go to DifficultyBalancerAgent
Hint requests go to HintProviderAgent
Solution tracking requests go to SolutionTrackerAgent

The supervisor continues delegating until it has gathered enough information to provide a comprehensive puzzle package, then synthesizes the results into a cohesive puzzle design.

Production-Ready Features

Despite being a demo, the agent includes production-ready features:

Observability: OpenTelemetry integration for monitoring agent performance
Resilience: Retry logic and circuit breaker patterns for reliability
Rate limiting: Prevents abuse and ensures fair resource usage
Guardrails: PII redaction and content safety for secure operation
Metrics: Built-in metrics for tracking agent performance

Running the Agent

The agent can be run with:

npm install
npm run build
npm run dev

The app runs on http://localhost:3000 with the HazelJS Inspector available at /__hazel for real-time monitoring and debugging.

Try It Out

You can test the agent with a curl request:

curl -s -X POST http://localhost:3000/puzzle/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Design a logic puzzle with detective theme, medium difficulty, 10 minutes. Balance the difficulty and provide hints.","userId":"puzzle-designer-1"}'

The agent will analyze your request, design a puzzle, balance its difficulty, provide progressive hints, and set up solution tracking—all coordinated through the supervisor routing system.

Complete Project: Escape Room Puzzle Designer
HazelJS Documentation: Docs

Key Takeaways

The Escape Room Puzzle Designer demonstrates several key HazelJS capabilities:

Multi-agent architecture: Each agent specializes in a specific aspect of puzzle design
RAG integration: Semantic search over puzzle database
Supervisor routing: Intelligent delegation to specialist agents
Production-ready patterns: Observability, resilience, and guardrails
Local LLM provider: Deterministic behavior without requiring API keys

This agent shows how HazelJS can be used to build fun, engaging applications that solve complex creative challenges while maintaining production-grade quality and reliability. The multi-agent approach makes it easy to extend the system with additional specialists (like theme generators or narrative designers) as needed.

Building a Legal Document Analyzer in typescript with NodeJS

Nisa Fatima — Wed, 29 Jul 2026 17:30:41 +0000

Legal documents are notoriously complex, filled with specialized terminology, hidden risks, and critical obligations. Lawyers and legal professionals spend countless hours reviewing contracts, agreements, and other legal documents to identify key terms, assess risks, and summarize obligations. In this post, we'll build a Legal Document Analyzer using HazelJS that automates document parsing, term extraction, risk analysis, and obligation summarization.

The Problem

Legal document analysis presents several challenges:

Document Parsing: Extracting structure, key sections, and metadata from unstructured legal text
Term Extraction: Identifying legal terms and providing definitions with context
Risk Assessment: Identifying potential risks with severity levels and mitigation strategies
Obligation Tracking: Extracting obligations with deadlines and responsible parties

Our agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered document search, and intelligent risk analysis.

Architecture Overview

The Legal Document Analyzer uses a multi-agent architecture where each agent specializes in a specific aspect of legal document analysis:

DocumentParserAgent: Parses legal documents to extract structure, key sections, and metadata
TermExtractorAgent: Extracts legal terms, definitions, and context from documents
RiskAnalyzerAgent: Analyzes legal documents for risks and provides mitigation strategies
ObligationSummarizerAgent: Summarizes legal obligations, deadlines, and responsible parties
LegalManagerAgent: Orchestrates the workflow using supervisor routing

This separation allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them.

RAG-Powered Document Search

One of the key features of our agent is the ability to search through a database of legal documents using Retrieval-Augmented Generation (RAG). We maintain a knowledge base of legal documents with metadata including:

Category (contract, intellectual-property, employment, corporate, real-estate)
Risk type (liability, compliance, financial, operational, reputational)
Severity level (low, medium, high, critical)
Key clauses and provisions

When a legal professional asks about a document, the DocumentParserAgent uses semantic search to find relevant documents based on their query. For example, a query like "Find indemnification clauses in contracts" would return documents containing indemnification provisions.

The RAG implementation uses HazelJS's RAGPipeline with a MemoryVectorStore for efficient semantic search:

@Service()
export class LegalKnowledgeBaseService {
  private readonly embeddings = new LocalLegalEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.search(query, topK);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        category: source.metadata?.category,
        riskType: source.metadata?.riskType,
        severity: source.metadata?.severity,
      })),
    };
  }
}

Intelligent Document Parsing

The DocumentParserAgent extracts structure and metadata from legal documents. It identifies:

Document type: Contract, agreement, NDA, employment, lease
Key sections: Preamble, terms and conditions, signatures
Key clauses: Indemnification, confidentiality, non-compete, force majeure, payment terms
Metadata: Presence of specific clauses, estimated complexity, word/character counts

This structured extraction provides a foundation for deeper analysis by other agents in the system.

Legal Term Extraction

The TermExtractorAgent identifies legal terms within documents and provides:

Term definitions: Clear explanations of legal terminology
Context: How the term is typically used in legal contexts
Category: Legal category (contract, intellectual-property, employment, etc.)
Cross-references: Related terms and concepts

This helps legal professionals quickly understand specialized language and ensures consistent interpretation across documents.

Risk Assessment

The RiskAnalyzerAgent analyzes documents for potential risks and provides:

Risk identification: Identifies liability, compliance, financial, operational, and reputational risks
Severity assessment: Rates risks as low, medium, high, or critical
Impact analysis: Describes the potential impact of each risk
Mitigation strategies: Provides actionable recommendations for addressing risks
Priority assignment: Suggests timeframes for addressing each risk

The agent calculates overall risk levels and provides comprehensive risk summaries, helping legal professionals prioritize their review efforts.

Obligation Summarization

The ObligationSummarizerAgent extracts and organizes obligations from legal documents:

Obligation types: Payment, delivery, performance, compliance, reporting
Deadlines: Specific timeframes for each obligation
Responsible parties: Identifies who is responsible for each obligation
Urgency assessment: Categorizes obligations by urgency
Timeline generation: Creates a chronological timeline of obligations

This systematic approach ensures that no obligations are overlooked and provides a clear roadmap for compliance.

Supervisor Routing

The LegalManagerAgent uses HazelJS's supervisor routing to coordinate between the specialist agents. When a legal professional makes a request, the supervisor analyzes the request and routes it to the appropriate specialist:

Document parsing requests go to DocumentParserAgent
Term extraction requests go to TermExtractorAgent
Risk analysis requests go to RiskAnalyzerAgent
Obligation summarization requests go to ObligationSummarizerAgent

The supervisor continues delegating until it has gathered enough information to provide a comprehensive legal analysis, then synthesizes the results into a cohesive report.

Production-Ready Features

Despite being a demo, the agent includes production-ready features:

Observability: OpenTelemetry integration for monitoring agent performance
Resilience: Retry logic and circuit breaker patterns for reliability
Rate limiting: Prevents abuse and ensures fair resource usage
Guardrails: PII redaction and content safety for secure document processing
Metrics: Built-in metrics for tracking agent performance

Running the Agent

The agent can be run with:

npm install
npm run build
npm run dev

The app runs on http://localhost:3000 with the HazelJS Inspector available at /__hazel for real-time monitoring and debugging.

Try It Out

You can test the agent with a curl request:

curl -s -X POST http://localhost:3000/legal/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Analyze this contract: Indemnification Clause: Party A agrees to indemnify and hold harmless Party B from any claims arising from negligence. Extract terms, analyze risks, and summarize obligations.","userId":"legal-analyst-1"}'

The agent will analyze your request, parse the document, extract legal terms, identify risks, summarize obligations, and synthesize everything into a comprehensive legal analysis—all coordinated through the supervisor routing system.

Complete Project: Legal Document Analyzer
HazelJS Documentation: Docs

Key Takeaways

The Legal Document Analyzer demonstrates several key HazelJS capabilities:

Multi-agent architecture: Each agent specializes in a specific aspect of legal document analysis
RAG integration: Semantic search over legal document database
Supervisor routing: Intelligent delegation to specialist agents
Production-ready patterns: Observability, resilience, and guardrails
Local LLM provider: Deterministic behavior without requiring API keys

This agent shows how HazelJS can be used to build professional applications that solve complex domain-specific challenges while maintaining production-grade quality and reliability. The multi-agent approach makes it easy to extend the system with additional specialists (like compliance checkers or jurisdiction analyzers) as needed.

Building an Event Planning Coordinator Agent in typescript with HazelJS

Nisa Fatima — Tue, 14 Jul 2026 19:17:57 +0000

Planning an event—whether it's a birthday party, corporate meeting, or wedding—requires coordinating multiple moving parts simultaneously. From finding the right venue to managing guest lists, arranging logistics, and staying within budget, event planning is a complex orchestration challenge. In this post, we'll build an Event Planning Coordinator Agent using HazelJS that streamlines this process through intelligent venue search, guest coordination, and logistics planning.

The Problem

Event planners face several coordination challenges:

Venue Selection: Finding venues that match capacity, type, and budget requirements
Guest Management: Tracking RSVPs, dietary restrictions, and communication
Logistics Coordination: Arranging catering, decoration, entertainment, and transportation
Budget Optimization: Balancing quality with available budget
Timeline Planning: Creating realistic schedules for all event components

Our agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered venue search, and intelligent logistics planning.

Architecture Overview

The Event Planning Coordinator Agent uses a multi-agent architecture where each agent specializes in a specific aspect of event planning:

EventIntakeAgent: Extracts event type, guest count, budget, date, and venue preferences
VenueSearchAgent: Retrieves venues from a knowledge base using RAG
GuestCoordinatorAgent: Manages guest lists, RSVP tracking, and communication plans
LogisticsPlannerAgent: Plans event logistics including catering, decoration, entertainment, and transportation
EventManagerAgent: Orchestrates the workflow using supervisor routing

This separation allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them.

RAG-Powered Venue Search

A critical component of event planning is finding the right venue. Our agent maintains a knowledge base of venues with metadata including:

Type (indoor, outdoor, hybrid)
Capacity
Price per hour
Available amenities (audio-visual, lighting, kitchen access, etc.)
Location
Availability patterns

When an event planner asks about venues, the VenueSearchAgent uses semantic search to find suitable options based on their query. For example, a query like "Find indoor venues for 100 guests" would return venues that match those criteria, ranked by relevance.

The RAG implementation uses HazelJS's RAGPipeline with a MemoryVectorStore for efficient semantic search:

@Service()
export class EventKnowledgeBaseService {
  private readonly embeddings = new LocalEventEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.search(query, topK);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        type: source.metadata?.type,
        capacity: source.metadata?.capacity,
        pricePerHour: source.metadata?.pricePerHour,
        location: source.metadata?.location,
        amenities: source.metadata?.amenities,
      })),
    };
  }
}

Guest Coordination

Managing guests is another complex aspect of event planning. The GuestCoordinatorAgent handles:

Guest List Generation: Creating structured guest lists with contact information
RSVP Tracking: Setting up tracking systems for confirmed, declined, and pending guests
Communication Planning: Creating communication schedules (save-the-date, formal invitation, reminders)
Dietary Restrictions: Tracking special dietary requirements for catering

The agent generates a comprehensive guest management plan including communication methods, estimated costs, and RSVP deadlines. This ensures no guest is forgotten and communication happens at the right times.

Logistics Planning

The LogisticsPlannerAgent creates comprehensive logistics plans covering:

Catering: Food and beverage arrangements scaled to guest count
Decoration: Theme-appropriate decoration packages
Entertainment: Music, DJs, or other entertainment options
Transportation: Shuttle services or transportation coordination
Equipment: Audio-visual equipment, lighting, and other technical needs

The planner considers:

Budget constraints: Filters logistics items that fit within the budget
Guest count: Scales quantities appropriately
Event type: Tailors logistics to the specific event type (corporate vs. party)
Timeline: Creates realistic schedules for each logistics component

The agent provides a detailed logistics timeline showing when each component should be arranged, along with cost breakdowns and category summaries.

Supervisor Routing

The EventManagerAgent uses HazelJS's supervisor routing to coordinate between the specialist agents. When an event planner makes a request, the supervisor analyzes the request and routes it to the appropriate specialist:

Event analysis requests go to EventIntakeAgent
Venue questions go to VenueSearchAgent
Guest coordination requests go to GuestCoordinatorAgent
Logistics planning requests go to LogisticsPlannerAgent

The supervisor continues delegating until it has gathered enough information to provide a comprehensive event plan, then synthesizes the results into a cohesive recommendation.

Production-Ready Features

Despite being a demo, the agent includes production-ready features:

Observability: OpenTelemetry integration for monitoring agent performance
Resilience: Retry logic and circuit breaker patterns for reliability
Rate limiting: Prevents abuse and ensures fair resource usage
Guardrails: PII redaction and content safety for secure operation
Metrics: Built-in metrics for tracking agent performance

Running the Agent

The agent can be run with:

npm install
npm run build
npm run dev

The app runs on http://localhost:3000 with the HazelJS Inspector available at /__hazel for real-time monitoring and debugging.

Try It Out

You can test the agent with a curl request:

curl -s -X POST http://localhost:3000/event/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Planning a party for 50 guests, budget $5000, indoor venue. Plan my event.","userId":"event-planner-1"}'

The agent will analyze your request, extract your event profile, search for suitable venues, coordinate guest management, plan logistics, and synthesize everything into a comprehensive event plan—all coordinated through the supervisor routing system.

Complete Project: Event Planner Agent

Key Takeaways

The Event Planning Coordinator Agent demonstrates several key HazelJS capabilities:

Multi-agent architecture: Each agent specializes in a specific aspect of event planning
RAG integration: Semantic search over venue database
Supervisor routing: Intelligent delegation to specialist agents
Production-ready patterns: Observability, resilience, and guardrails
Local LLM provider: Deterministic behavior without requiring API keys

This agent shows how HazelJS can be used to build practical, everyday applications that solve complex coordination problems while maintaining production-grade quality and reliability. The multi-agent approach makes it easy to extend the system with additional specialists (like budget analyzers or timeline optimizers) as needed.

Building a Home Maintenance Scheduler Agent in typescript with HazelJS

Nisa Fatima — Tue, 14 Jul 2026 19:17:40 +0000

Home maintenance is one of those tasks that everyone knows they should do regularly, but few actually manage to keep up with. Between changing HVAC filters, cleaning gutters, inspecting roofs, and coordinating service providers, it's easy for important maintenance tasks to slip through the cracks. In this post, we'll build a Home Maintenance Scheduler Agent using HazelJS that helps homeowners stay on top of their maintenance needs through intelligent task scheduling, provider matching, and reminder coordination.

The Problem

Homeowners face several challenges when it comes to maintenance:

Task Discovery: Knowing what maintenance tasks are needed and when
Scheduling: Creating realistic timelines that fit with seasonal requirements
Budget Management: Balancing maintenance needs with available budget
Provider Selection: Finding reliable service providers for professional tasks
Reminder Coordination: Remembering when tasks are due

Our agent will address these challenges using HazelJS's multi-agent architecture, RAG-powered task search, and intelligent scheduling capabilities.

Architecture Overview

The Home Maintenance Scheduler Agent uses a multi-agent architecture where each agent specializes in a specific aspect of maintenance planning:

MaintenanceIntakeAgent: Extracts home type, maintenance needs, budget, DIY preference, and scheduling preferences
TaskSearchAgent: Retrieves maintenance tasks from a knowledge base using RAG
TaskSchedulerAgent: Creates maintenance schedules with task prioritization and timeline planning
ProviderSearchAgent: Finds service providers based on category, rating, and availability
ReminderCoordinatorAgent: Coordinates maintenance reminders and notifications
HomeManagerAgent: Orchestrates the workflow using supervisor routing

This separation of concerns allows each agent to focus on its specialty while the supervisor ensures smooth coordination between them.

RAG-Powered Task Search

One of the key features of our agent is the ability to search through a database of maintenance tasks using Retrieval-Augmented Generation (RAG). We maintain a knowledge base of maintenance tasks with metadata including:

Category (plumbing, electrical, HVAC, landscaping, etc.)
Frequency (monthly, quarterly, annual, as-needed)
Difficulty (DIY, professional, either)
Estimated duration and cost
Seasonal requirements
Priority level

When a homeowner asks about maintenance needs, the TaskSearchAgent uses semantic search to find relevant tasks based on their query. For example, a query like "Find HVAC maintenance tasks" would return tasks related to HVAC filter replacement, system inspections, and seasonal maintenance.

The RAG implementation uses HazelJS's RAGPipeline with a MemoryVectorStore for efficient semantic search:

@Service()
export class MaintenanceKnowledgeBaseService {
  private readonly embeddings = new LocalMaintenanceEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.search(query, topK);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        category: source.metadata?.category,
        frequency: source.metadata?.frequency,
        difficulty: source.metadata?.difficulty,
        season: source.metadata?.season,
        priority: source.metadata?.priority,
      })),
    };
  }
}

Intelligent Task Scheduling

The TaskSchedulerAgent takes the retrieved tasks and creates a realistic maintenance schedule based on:

Budget constraints: Filters tasks that fit within the homeowner's budget
DIY preference: Considers whether the homeowner prefers DIY or professional services
Seasonal requirements: Schedules tasks during appropriate seasons
Priority: Prioritizes high-priority tasks like smoke detector maintenance

The scheduler calculates optimal dates for each task and provides a summary including total estimated duration, cost, and number of high-priority tasks. It also generates maintenance tips specific to the category of maintenance being scheduled.

Provider Matching

For tasks that require professional services, the ProviderSearchAgent finds suitable service providers based on:

Category match (plumbing, electrical, HVAC, etc.)
Rating and reviews
Availability
Pricing

The agent ranks providers by rating and provides contact information, services offered, and pricing details. This helps homeowners make informed decisions when hiring professionals for maintenance tasks.

Reminder Coordination

The ReminderCoordinatorAgent sets up automated reminders for maintenance tasks. It considers:

Task frequency (monthly, quarterly, annual)
Preferred notification methods (email, SMS, push)
Advance notice requirements

The agent generates a reminder schedule with notification settings, ensuring homeowners never miss important maintenance deadlines.

Supervisor Routing

The HomeManagerAgent uses HazelJS's supervisor routing to coordinate between the specialist agents. When a homeowner makes a request, the supervisor analyzes the request and routes it to the appropriate specialist:

Maintenance analysis requests go to MaintenanceIntakeAgent
Task questions go to TaskSearchAgent
Scheduling requests go to TaskSchedulerAgent
Provider search requests go to ProviderSearchAgent
Reminder requests go to ReminderCoordinatorAgent

The supervisor continues delegating until it has gathered enough information to provide a comprehensive response, then synthesizes the results into a cohesive maintenance plan.

Production-Ready Features

Despite being a demo, the agent includes production-ready features:

Observability: OpenTelemetry integration for monitoring agent performance
Resilience: Retry logic and circuit breaker patterns for reliability
Rate limiting: Prevents abuse and ensures fair resource usage
Guardrails: PII redaction and content safety for secure operation
Metrics: Built-in metrics for tracking agent performance

Running the Agent

The agent can be run with:

npm install
npm run build
npm run dev

The app runs on http://localhost:3000 with the HazelJS Inspector available at /__hazel for real-time monitoring and debugging.

Try It Out

You can test the agent with a curl request:

curl -s -X POST http://localhost:3000/maintenance/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"I have a house, need plumbing maintenance, budget $500, prefer DIY. Schedule my maintenance.","userId":"homeowner-1"}'

The agent will analyze your request, extract your maintenance profile, search for relevant tasks, create a schedule, find providers if needed, and set up reminders—all coordinated through the supervisor routing system.

Complete Project: Home Maintenance Scheduler Agent

Key Takeaways

The Home Maintenance Scheduler Agent demonstrates several key HazelJS capabilities:

Multi-agent architecture: Each agent specializes in a specific aspect of maintenance planning
RAG integration: Semantic search over maintenance task database
Supervisor routing: Intelligent delegation to specialist agents
Production-ready patterns: Observability, resilience, and guardrails
Local LLM provider: Deterministic behavior without requiring API keys

This agent shows how HazelJS can be used to build practical, everyday applications that solve real problems while maintaining production-grade quality and reliability.

Building a Personal Learning Path Agent in typescript with HazelJS

Nisa Fatima — Sun, 05 Jul 2026 16:14:13 +0000

Learning new skills is one of the most rewarding activities we can undertake, but it's also notoriously difficult to do effectively. The internet offers endless resources—courses, books, tutorials, videos—but finding the right path through this abundance is overwhelming. Traditional learning platforms provide static curricula, but they struggle with personalization, adaptation, and motivation.

This is where agentic AI can make a real difference. In this post, we'll build a personal learning path agent using HazelJS that demonstrates how multi-agent systems can solve the complex problem of personalized education.

The Learning Challenge

When someone decides to learn a new skill, they face multiple interconnected challenges:

Goal definition: What does success look like? Career advancement? Personal interest? Certification?
Skill assessment: What's their current level? What prerequisites do they have?
Resource discovery: Among thousands of options, which resources are actually good?
Curriculum planning: How do you sequence learning activities logically?
Progress tracking: How do you measure improvement and stay motivated?

A single AI model trying to handle all these aspects often produces generic recommendations. Agentic AI, by contrast, allows us to create specialized agents that excel at specific tasks while collaborating seamlessly—much like how a real educational team works.

Why Agentic AI for Learning?

Agentic AI is particularly well-suited for learning path planning because:

Domain expertise: Different aspects of learning require different knowledge—pedagogy for curriculum design, resource databases for discovery, psychology for motivation
Iterative refinement: A learning path isn't static; it evolves as users progress, discover new interests, or encounter obstacles
Multi-modal reasoning: Combining skill databases, user preferences, progress data, and learning science requires different reasoning approaches
Human-in-the-loop: Users need to provide feedback, adjust goals, and report progress continuously

HazelJS makes this natural by providing the building blocks for multi-agent systems: the @Agent decorator for defining agents, @Tool for capabilities, and @Delegate for orchestration.

Architecture Overview

Our learning path agent uses five specialized agents, each with a clear responsibility:

LearningIntakeAgent: Extracts structured information from natural language—skills, goals, time availability, learning style
ResourceSearchAgent: Uses RAG to find learning resources matching specific criteria from a knowledge base
CurriculumPlannerAgent: Creates week-by-week curricula with milestones, activities, and logical progression
ProgressTrackerAgent: Calculates metrics, unlocks achievements, and provides improvement recommendations
LearningCoachAgent: Orchestrates the workflow using supervisor routing, delegating to specialists as needed

This separation of concerns makes each agent simpler, more testable, and easier to improve independently. When we want better resource recommendations, we only need to enhance the ResourceSearchAgent without touching curriculum planning logic.

HazelJS Features in Action

Multi-Agent Orchestration

HazelJS's @Delegate decorator makes agent collaboration straightforward. The LearningCoachAgent doesn't need to know how to search resources or track progress—it simply delegates to specialists:

@Delegate({
  agent: 'ResourceSearchAgent',
  description: 'Retrieve resources based on skills, difficulty, and format.',
  inputField: 'input',
})
async getResources(input: string): Promise<string> {
  return '';
}

This declarative approach means the orchestrator stays focused on coordination while specialists handle domain expertise.

RAG for Resource Discovery

Finding the right learning resource isn't just keyword matching—it requires understanding skill levels, prerequisites, formats, and topics. We use HazelJS's RAG capabilities with a MemoryVectorStore for semantic search:

const rag = new RAGPipeline({
  vectorStore: this.vectorStore,
  embeddingProvider: this.embeddings,
  topK: 3,
});

When a user asks for "JavaScript beginner courses," the RAG system understands the semantic meaning and returns relevant resources like JavaScript Fundamentals, even if the exact phrase doesn't appear in the resource description.

Production Resilience

Learning apps need to be reliable—users depend on them for their educational goals. HazelJS provides built-in resilience patterns:

Circuit breaker: Prevents cascading failures when external services are down
Retry logic: Handles transient failures gracefully
Rate limiting: Protects against abuse and ensures fair usage
Observability: Built-in metrics and tracing for monitoring

These features are configured once in the AgentModule and apply across all agents automatically.

Guardrails for Safety

Learning apps often handle personal information about users' goals and progress. HazelJS's guardrails provide:

PII redaction: Automatically removes personal information from logs
Injection blocking: Prevents prompt injection attacks
Toxicity filtering: Ensures recommendations remain appropriate

This is especially important when users might share sensitive career information or personal learning challenges.

Implementation Highlights

Structured Data Extraction

The LearningIntakeAgent transforms natural language into structured data. Instead of parsing "I want to learn JavaScript, beginner level, 10 hours per week for 8 weeks" manually, we use tool-based extraction:

@Tool({
  name: 'extractLearningProfile',
  description: 'Extract structured learning planning information from a user request.',
  parameters: [
    { name: 'message', type: 'string', description: 'The raw user request', required: true },
  ],
})
async extractLearningProfile(input: { message: string }) {
  return {
    skill: this.extractSkill(input.message),
    currentLevel: this.extractCurrentLevel(input.message),
    timeAvailable: this.extractTimeAvailable(input.message),
    // ... more fields
  };
}

This structured output becomes the foundation for all subsequent agents, ensuring consistency across the workflow.

Goal-Aware Curriculum Planning

The CurriculumPlannerAgent doesn't just pick random resources—it considers the user's goals and skill level:

Beginner level: Focuses on fundamentals, prerequisites, and basic concepts
Intermediate level: Emphasizes practical application and project-based learning
Advanced level: Centers on mastery, optimization, and teaching others

The agent also balances resources across weeks, ensures adequate progression, and provides milestones (like "Complete mid-course assessment" or "Build first project") to keep learners motivated.

Progress Tracking with Achievements

The ProgressTrackerAgent goes beyond simple logging—it calculates meaningful metrics and unlocks achievements:

const achievements = [
  {
    id: 'first-resource',
    title: 'First Resource',
    description: 'Completed your first learning resource',
    unlocked: true,
  },
  {
    id: 'consistent-learner',
    title: 'Consistent Learner',
    description: 'Maintained learning streak for 7 days',
    unlocked: false,
  },
];

Gamification elements like achievements keep users motivated, while metrics provide concrete feedback on progress.

Real-World Applications

This architecture extends beyond personal learning:

Corporate training: Companies can provide personalized learning paths for employees
Educational institutions: Schools can create adaptive curricula for students
Professional development: Organizations can design skill progression for teams
Career coaching: Coaches can create personalized development plans

The multi-agent approach makes these adaptations straightforward—swap the resource knowledge base, adjust the goal categories, and the same architecture works.

Running the Project

npm install --legacy-peer-deps
npm run build
npm run eval
npm run dev

The eval tests verify each agent works correctly before integration. The development server starts on port 3000 with the HazelJS Inspector available at /__hazel for real-time monitoring.

Testing the API

# Learning intake
curl -s -X POST http://localhost:3000/learning/intake \
  -H 'content-type: application/json' \
  -d '{"message":"I want to learn JavaScript, beginner level, 10 hours per week for 8 weeks"}'

# Supervisor orchestration
curl -s -X POST http://localhost:3000/learning/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"I want to learn JavaScript, beginner level, 10 hours per week for 8 weeks. Plan my learning path."}'

The supervisor endpoint demonstrates the full workflow: intake → resource search → curriculum planning → progress tracking, all orchestrated automatically.

Complete Project: Personal Learning Agent

Key Takeaways

Specialization beats generalization: Multiple focused agents produce better results than one monolithic agent
RAG enables semantic understanding: Resource search works because it understands intent, not just keywords
Resilience is essential: Learning apps need to be reliable—built-in circuit breakers and retries matter
Observability drives improvement: The HazelJS Inspector makes debugging and optimization straightforward
Guardrails protect users: Safety features are non-negotiable when handling personal learning data
Progress tracking maintains engagement: Metrics and achievements keep users motivated long-term
Curriculum structure matters: Logical progression with milestones prevents overwhelm and dropout

What's Next?

For production deployment, consider:

Real LLM integration: Replace the local provider with OpenAI or Anthropic for more sophisticated reasoning
Persistent storage: Use @hazeljs/memory to save user preferences and learning history
Advanced workflows: Implement @hazeljs/flow for complex multi-step learning processes
Notifications: Add @hazeljs/pubsub for learning reminders and progress updates
Real resource APIs: Connect to comprehensive learning platforms like Coursera, Udemy, or edX
Monitoring: Use @hazeljs/observability for OpenTelemetry integration with monitoring platforms

Conclusion

This personal learning path agent demonstrates how HazelJS enables building sophisticated AI applications with production-ready patterns. The multi-agent architecture, RAG-powered search, and built-in resilience features make it possible to create reliable, observable, and scalable learning applications.

More importantly, it shows that agentic AI isn't just theoretical—it solves real problems better than traditional approaches. By breaking complex tasks into specialized components that collaborate, we get systems that are more maintainable, more testable, and ultimately more effective.

Building a Fitness Workout Planner Agent in typescript with HazelJS

Nisa Fatima — Sat, 04 Jul 2026 17:05:32 +0000

Fitness planning is inherently complex. It requires understanding individual goals, physical capabilities, available equipment, and creating progressive workout plans that adapt over time. Traditional fitness apps often provide static templates, but they struggle with personalization and adaptation. This is where agentic AI shines.

In this post, we'll build an intelligent fitness workout planner using HazelJS that demonstrates how multi-agent systems can solve real-world problems more effectively than monolithic approaches.

The Fitness Planning Challenge

When someone asks for a workout plan, they're not just requesting exercises. They need:

Goal alignment: Weight loss, muscle gain, endurance, or flexibility require different approaches
Personalization: Fitness level, injuries, and available equipment vary dramatically
Progression: Plans must evolve as users get stronger
Motivation: Tracking progress and celebrating achievements keeps users engaged
Safety: Exercises must match ability levels to prevent injury

A single AI model trying to handle all these aspects often produces generic recommendations. Agentic AI, however, allows us to create specialized agents that excel at specific tasks while collaborating seamlessly.

Why Agentic AI for Fitness Planning?

Agentic AI is particularly well-suited for fitness planning because:

Specialized expertise: Different aspects of fitness require different knowledge bases—exercise physiology, nutrition science, progress tracking methodologies
Iterative refinement: A fitness plan isn't created in one step; it requires intake, research, planning, and tracking
Human-in-the-loop: Users need to provide feedback, adjust goals, and report progress
Multi-modal reasoning: Combining exercise databases, user preferences, and progress data requires different reasoning approaches

HazelJS makes this natural by providing the building blocks for multi-agent systems: the @Agent decorator for defining agents, @Tool for capabilities, and @Delegate for orchestration.

Architecture Overview

Our fitness planner uses five specialized agents, each with a clear responsibility:

FitnessIntakeAgent: Extracts structured information from natural language—goals, fitness level, equipment, time constraints
ExerciseSearchAgent: Uses RAG to find exercises matching specific criteria from a knowledge base
WorkoutPlannerAgent: Creates day-by-day workout plans with balanced exercises, proper rest, and logical progression
ProgressTrackerAgent: Calculates metrics, unlocks achievements, and provides improvement recommendations
FitnessCoachAgent: Orchestrates the workflow using supervisor routing, delegating to specialists as needed

This separation of concerns makes each agent simpler, more testable, and easier to improve independently. When we want better exercise recommendations, we only need to enhance the ExerciseSearchAgent without touching the workout planning logic.

HazelJS Features in Action

Multi-Agent Orchestration

HazelJS's @Delegate decorator makes agent collaboration straightforward. The FitnessCoachAgent doesn't need to know how to search exercises or track progress—it simply delegates to specialists:

@Delegate({
  agent: 'ExerciseSearchAgent',
  description: 'Retrieve exercises based on goals, muscle groups, and equipment.',
  inputField: 'input',
})
async getExercises(input: string): Promise<string> {
  return '';
}

This declarative approach means the orchestrator stays focused on coordination while specialists handle domain expertise.

RAG for Exercise Discovery

Finding the right exercise isn't just keyword matching—it requires understanding muscle groups, equipment needs, and difficulty levels. We use HazelJS's RAG capabilities with a MemoryVectorStore for semantic search:

const rag = new RAGPipeline({
  vectorStore: this.vectorStore,
  embeddingProvider: this.embeddings,
  topK: 3,
});

When a user asks for "chest exercises without equipment," the RAG system understands the semantic meaning and returns relevant exercises like push-ups, even if the exact phrase doesn't appear in the exercise description.

Production Resilience

Fitness apps need to be reliable. HazelJS provides built-in resilience patterns:

Circuit breaker: Prevents cascading failures when external services are down
Retry logic: Handles transient failures gracefully
Rate limiting: Protects against abuse and ensures fair usage
Observability: Built-in metrics and tracing for monitoring

These features are configured once in the AgentModule and apply across all agents automatically:

AgentModule.forRoot({
  runtime: {
    enableRetry: true,
    enableCircuitBreaker: true,
    rateLimitPerMinute: 120,
    enableObservability: true,
  },
})

Guardrails for Safety

Fitness recommendations can have real-world consequences if incorrect. HazelJS's guardrails provide:

PII redaction: Automatically removes personal information from logs
Injection blocking: Prevents prompt injection attacks
Toxicity filtering: Ensures recommendations remain appropriate

This is especially important for fitness apps where users might share sensitive health information.

Implementation Highlights

Structured Data Extraction

The FitnessIntakeAgent transforms natural language into structured data. Instead of parsing "I want to lose weight, beginner level, 30 min workouts, no equipment" manually, we use tool-based extraction:

@Tool({
  name: 'extractFitnessProfile',
  description: 'Extract structured fitness planning information from a user request.',
  parameters: [
    { name: 'message', type: 'string', description: 'The raw user request', required: true },
  ],
})
async extractFitnessProfile(input: { message: string }) {
  return {
    goal: this.extractGoal(input.message),
    fitnessLevel: this.extractFitnessLevel(input.message),
    equipment: this.extractEquipment(input.message),
    // ... more fields
  };
}

This structured output becomes the foundation for all subsequent agents, ensuring consistency across the workflow.

Goal-Aware Workout Planning

The WorkoutPlannerAgent doesn't just pick random exercises—it considers the user's goals:

Weight loss: Prioritizes cardio and high-intensity intervals
Muscle gain: Focuses on compound movements with progressive overload
Endurance: Emphasizes steady-state cardio and duration progression
Flexibility: Centers on stretching and mobility work

The agent also balances exercises across muscle groups, ensures adequate rest periods, and provides notes for each day (like "Start with proper warm-up" or "Active recovery day").

Progress Tracking with Achievements

The ProgressTrackerAgent goes beyond simple logging—it calculates meaningful metrics and unlocks achievements:

const achievements = [
  {
    id: 'first-workout',
    title: 'First Workout',
    description: 'Completed your first workout session',
    unlocked: true,
  },
  {
    id: 'consistent-week',
    title: 'Consistent Week',
    description: 'Completed workouts for 7 days',
    unlocked: false,
  },
];

Gamification elements like achievements keep users motivated, while metrics provide concrete feedback on progress.

Real-World Applications

This architecture extends beyond personal fitness:

Corporate wellness programs: Companies can provide personalized fitness plans to employees
Physical therapy: Therapists can create progressive rehabilitation plans
Sports coaching: Coaches can design sport-specific training programs
Senior fitness: Adapted plans for different age groups and mobility levels

The multi-agent approach makes these adaptations straightforward—swap the exercise knowledge base, adjust the goal categories, and the same architecture works.

Running the Project

npm install --legacy-peer-deps
npm run build
npm run eval
npm run dev

The eval tests verify each agent works correctly before integration. The development server starts on port 3000 with the HazelJS Inspector available at /__hazel for real-time monitoring.

Testing the API

# Fitness intake
curl -s -X POST http://localhost:3000/fitness/intake \
  -H 'content-type: application/json' \
  -d '{"message":"I want to lose weight, beginner level, 30 min workouts, no equipment"}'

# Supervisor orchestration
curl -s -X POST http://localhost:3000/fitness/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"I want to lose weight, beginner level, 30 min workouts, no equipment. Plan my week."}'

The supervisor endpoint demonstrates the full workflow: intake → exercise search → workout planning → progress tracking, all orchestrated automatically.

Complete Project: Fitness workout Planner Agent

Key Takeaways

Specialization beats generalization: Multiple focused agents produce better results than one monolithic agent
RAG enables semantic understanding: Exercise search works because it understands intent, not just keywords
Resilience is essential: Fitness apps need to be reliable—built-in circuit breakers and retries matter
Observability drives improvement: The HazelJS Inspector makes debugging and optimization straightforward
Guardrails protect users: Safety features are non-negotiable when health recommendations are involved
Progress tracking maintains engagement: Metrics and achievements keep users motivated long-term

What's Next?

For production deployment, consider:

Real LLM integration: Replace the local provider with OpenAI or Anthropic for more sophisticated reasoning
Persistent storage: Use @hazeljs/memory to save user preferences and workout history
Advanced workflows: Implement @hazeljs/flow for complex multi-step processes
Notifications: Add @hazeljs/pubsub for workout reminders and progress updates
Real exercise APIs: Connect to comprehensive exercise databases for dynamic content
Monitoring: Use @hazeljs/observability for OpenTelemetry integration with Datadog or New Relic

Conclusion

This fitness workout planner demonstrates how HazelJS enables building sophisticated AI applications with production-ready patterns. The multi-agent architecture, RAG-powered search, and built-in resilience features make it possible to create reliable, observable, and scalable fitness applications.

A Travel Itinerary Planner Agent in Typescript with HazelJS

Nisa Fatima — Sun, 14 Jun 2026 17:57:56 +0000

In this post, we'll build an intelligent travel itinerary planner using HazelJS. This agent helps users discover destinations, create personalized itineraries, and get logistics suggestions—all while demonstrating HazelJS's powerful agent orchestration, RAG capabilities, and production-ready patterns.

What We're Building

Our travel itinerary planner handles the complete travel planning workflow:

Travel Intake: Extracts destination, dates, budget, interests, and travel style
Destination Research: Finds destinations using RAG over a travel database
Itinerary Building: Creates day-by-day itineraries with balanced activities
Logistics Suggestions: Recommends flights, accommodations, and transportation
Travel Advisory: Orchestrates the entire workflow via supervisor routing

Why HazelJS?

HazelJS provides a production-ready framework for building AI-native applications. For this project, we leverage:

Multi-agent orchestration with @Agent, @Tool, and @Delegate decorators
RAG (Retrieval-Augmented Generation) for semantic destination search
Supervisor routing to delegate tasks to specialized agents
Production resilience with retries, circuit breakers, and rate limiting
Built-in observability via the HazelJS Inspector
Guardrails for safer travel recommendations

Project Architecture

travel-itinerary-agent/
├── src/
│   ├── agents/              # Agent implementations
│   │   ├── travel-intake.agent.ts
│   │   ├── destination-research.agent.ts
│   │   ├── itinerary-builder.agent.ts
│   │   ├── logistics.agent.ts
│   │   └── travel-advisor.agent.ts
│   ├── providers/           # LLM and embedding providers
│   │   ├── travel-planning-llm.provider.ts
│   │   └── local-embedding.provider.ts
│   ├── data/                # Travel fixtures
│   │   └── travel-fixtures.ts
│   ├── travel/              # Controllers and services
│   │   ├── travel.controller.ts
│   │   └── travel-kb.service.ts
│   ├── app.module.ts
│   ├── health.controller.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Agent Implementation

Travel Intake Agent

The TravelIntakeAgent extracts structured information from natural language:

@Agent({
  name: 'TravelIntakeAgent',
  description: 'Extracts destination, dates, budget, interests, travel style, and group size.',
  systemPrompt: 'You are a travel intake specialist. Extract the traveler profile before any itinerary is created.',
  maxSteps: 4,
  temperature: 0,
})
@Service()
export class TravelIntakeAgent {
  @Tool({
    name: 'extractTravelProfile',
    description: 'Extract structured travel planning information from a user request.',
    parameters: [
      { name: 'message', type: 'string', description: 'The raw user request', required: true },
      { name: 'userId', type: 'string', description: 'User id when available', required: false },
    ],
  })
  async extractTravelProfile(input: { message: string; userId?: string }) {
    const destination = this.extractDestination(input.message);
    const days = this.extractDays(input.message);
    const budget = this.extractBudget(input.message);
    const interests = this.extractInterests(input.message);
    const travelStyle = this.extractTravelStyle(input.message);

    return {
      userId: input.userId ?? 'traveler-demo',
      destination,
      days,
      budget,
      interests,
      travelStyle,
      // ... more fields
    };
  }
}

Destination Research Agent with RAG

The DestinationResearchAgent uses RAG to find destinations semantically:

@Agent({
  name: 'DestinationResearchAgent',
  description: 'Retrieves destination information from the knowledge base based on interests, budget, and season.',
  systemPrompt: 'You are a destination research specialist. Use retrieved context only and cite source ids.',
  enableRAG: true,
  ragTopK: 3,
  maxSteps: 4,
  temperature: 0,
})
@Service()
export class DestinationResearchAgent {
  constructor(private readonly knowledgeBase: TravelKnowledgeBaseService) {}

  @Tool({
    name: 'searchDestinations',
    description: 'Search destinations based on interests, budget, season, and travel style.',
    parameters: [
      { name: 'query', type: 'string', description: 'The destination search query', required: true },
      { name: 'topK', type: 'number', description: 'Number of destinations to retrieve', required: false },
    ],
  })
  async searchDestinations(input: { query: string; topK?: number }) {
    return this.knowledgeBase.answer(input.query, input.topK ?? 3);
  }
}

Itinerary Builder Agent

The ItineraryBuilderAgent creates realistic daily itineraries:

@Agent({
  name: 'ItineraryBuilderAgent',
  description: 'Creates realistic daily itineraries with balanced activities and travel time.',
  systemPrompt: 'You are an itinerary planning specialist. Create balanced plans with variety, rest periods, and logical routing.',
  maxSteps: 5,
  temperature: 0,
})
@Service()
export class ItineraryBuilderAgent {
  @Tool({
    name: 'createItinerary',
    description: 'Create a day-by-day itinerary from travel constraints and interests.',
    parameters: [
      { name: 'destination', type: 'string', description: 'Destination city or country', required: true },
      { name: 'days', type: 'number', description: 'Number of days to plan', required: true },
      { name: 'budget', type: 'number', description: 'Total trip budget', required: true },
      { name: 'interests', type: 'array', description: 'Travel interests and preferences', required: true },
    ],
  })
  async createItinerary(input: {
    destination: string;
    days: number;
    budget: number;
    interests: string[];
  }) {
    const filteredAttractions = this.filterAttractions(input.interests);
    const itinerary = Array.from({ length: input.days }, (_, index) => {
      const day = index + 1;
      const date = this.getDateForDay(day);
      const dayActivities = this.selectActivitiesForDay(filteredAttractions, input.budget / input.days, day);

      return {
        day,
        date,
        activities: dayActivities.activities,
        estimatedCost: dayActivities.estimatedCost,
        notes: this.generateDayNotes(day, input.days, input.destination),
      };
    });

    return {
      destination: input.destination,
      days: input.days,
      budget: input.budget,
      interests: input.interests,
      itinerary,
      tripSummary: this.calculateTripSummary(itinerary),
      travelTips: this.generateTravelTips(input.destination),
    };
  }
}

Logistics Agent

The LogisticsAgent provides practical suggestions for flights, accommodations, and transportation:

@Agent({
  name: 'LogisticsAgent',
  description: 'Suggests flights, accommodations, and transportation options based on budget and travel style.',
  systemPrompt: 'You are a logistics specialist. Provide practical suggestions for flights, hotels, and local transportation.',
  maxSteps: 4,
  temperature: 0,
})
@Service()
export class LogisticsAgent {
  @Tool({
    name: 'suggestLogistics',
    description: 'Generate logistics suggestions for flights, accommodation, and transportation.',
    parameters: [
      { name: 'destination', type: 'string', description: 'Destination city or country', required: true },
      { name: 'days', type: 'number', description: 'Number of days of travel', required: true },
      { name: 'budget', type: 'number', description: 'Total trip budget', required: true },
      { name: 'travelStyle', type: 'string', description: 'Travel style (budget, balanced, luxury, adventure, relaxed)', required: true },
    ],
  })
  async suggestLogistics(input: {
    destination: string;
    days: number;
    budget: number;
    travelStyle: string;
  }) {
    const suggestions = this.generateSuggestions(input.destination, input.days, input.budget, input.travelStyle);

    return {
      destination: input.destination,
      days: input.days,
      budget: input.budget,
      travelStyle: input.travelStyle,
      suggestions,
      totalEstimatedLogisticsCost: suggestions.reduce((sum, s) => sum + s.estimatedCost, 0),
      bookingTimeline: this.generateBookingTimeline(input.days),
    };
  }
}

Travel Advisor with Supervisor

The TravelAdvisorAgent orchestrates the workflow using delegation:

@Agent({
  name: 'TravelAdvisorAgent',
  description: 'Coordinates travel intake, destination research, itinerary building, and logistics suggestions.',
  systemPrompt: 'You are the travel advisor orchestrator. Extract constraints, retrieve destinations, build itineraries, and suggest logistics.',
  maxSteps: 8,
  temperature: 0,
})
@Service()
export class TravelAdvisorAgent {
  @Delegate({
    agent: 'TravelIntakeAgent',
    description: 'Extract destination, dates, budget, interests, and travel style from a user request.',
    inputField: 'input',
  })
  async analyzeTravelRequest(input: string): Promise<string> {
    return '';
  }

  @Delegate({
    agent: 'DestinationResearchAgent',
    description: 'Retrieve destinations based on interests, budget, and season.',
    inputField: 'input',
  })
  async getDestinations(input: string): Promise<string> {
    return '';
  }

  @Delegate({
    agent: 'ItineraryBuilderAgent',
    description: 'Build a day-by-day itinerary from the user request.',
    inputField: 'input',
  })
  async buildItinerary(input: string): Promise<string> {
    return '';
  }

  @Delegate({
    agent: 'LogisticsAgent',
    description: 'Suggest logistics for flights, accommodation, and transportation.',
    inputField: 'input',
  })
  async suggestLogistics(input: string): Promise<string> {
    return '';
  }
}

RAG Implementation

We use MemoryVectorStore and RAGPipeline for semantic destination search:

@Service()
export class TravelKnowledgeBaseService {
  private readonly embeddings = new LocalTravelEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.rag.retrieve(query, { topK }, RetrievalStrategy.HYBRID);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        country: source.metadata?.country,
        region: source.metadata?.region,
        bestSeason: source.metadata?.bestSeason,
        averageDailyCost: source.metadata?.averageDailyCost,
        tags: source.metadata?.tags,
      })),
    };
  }
}

Production Configuration

The AgentModule is configured with production-ready features:

@HazelModule({
  imports: [
    ConfigModule.forRoot({ envFilePath: ['.env', '.env.local'], isGlobal: true }),
    CacheModule.forRoot({ strategy: 'memory', isGlobal: true }),
    InspectorModule.forRoot({ inspectorBasePath: '/__hazel', developmentOnly: true }),
    GuardrailsModule.forRoot({
      redactPIIByDefault: true,
      blockInjectionByDefault: true,
      blockToxicityByDefault: true,
    }),
    AIModule,
    RAGModule,
    AgentModule.forRoot({
      runtime: {
        llmProvider: new TravelPlanningLocalLLMProvider(),
        defaultMaxSteps: 8,
        defaultTimeout: 15000,
        enableObservability: true,
        enableMetrics: true,
        enableRetry: true,
        enableCircuitBreaker: true,
        rateLimitPerMinute: 120,
      },
    }),
  ],
  controllers: [HealthController, TravelController],
  providers: [
    TravelKnowledgeBaseService,
    TravelIntakeAgent,
    DestinationResearchAgent,
    ItineraryBuilderAgent,
    LogisticsAgent,
    TravelAdvisorAgent,
  ],
})
export class AppModule {}

Running the Project

# Install dependencies
npm install --legacy-peer-deps

# Build the project
npm run build

# Run eval tests
npm run eval

# Start development server
npm run dev

Testing the API

# Health check
curl http://localhost:3000/health

# Travel intake
curl -s -X POST http://localhost:3000/travel/intake \
  -H 'content-type: application/json' \
  -d '{"message":"Planning a 5-day trip to Tokyo in June. Budget $2000. Love food, anime, and temples.","userId":"traveler-1"}'

# Destination research with RAG
curl -s -X POST http://localhost:3000/travel/destinations \
  -H 'content-type: application/json' \
  -d '{"message":"Find destinations with temples and anime culture"}'

# Supervisor orchestration
curl -s -X POST http://localhost:3000/travel/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Planning a 5-day trip to Tokyo in June. Budget $2000. Love food, anime, and temples. Prefer walking over taxis.","userId":"traveler-1"}'

HazelJS Inspector

Access the built-in inspector at http://localhost:3000/__hazel for:

Real-time agent execution traces
Tool call logs
Performance metrics
Circuit breaker status
Rate limiter status

Key Takeaways

Multi-agent architecture: Each agent has a focused responsibility, making the system maintainable and testable
RAG for knowledge retrieval: Semantic search over travel database provides accurate, context-aware destination recommendations
Supervisor routing: The orchestrator agent delegates tasks to specialists, enabling complex workflows
Production resilience: Built-in retries, circuit breakers, and rate limiting ensure reliability
Observability: The inspector provides deep insights into agent behavior and performance
Guardrails: PII redaction and content safety protect users from inappropriate recommendations
Activity balancing: Itineraries include rest periods and logical routing for realistic travel plans

What's Next?

For a production deployment, you would:

Replace the local LLM provider with OpenAI, Anthropic, or Google Generative AI
Add persistent storage with @hazeljs/memory for user preferences and travel history
Implement @hazeljs/flow for advanced workflow orchestration
Add @hazeljs/pubsub for async travel notifications and booking confirmations
Connect to real travel APIs (flights, hotels, attractions) for dynamic content
Implement @hazeljs/data with TypeORM or Prisma for comprehensive travel data management

Comparison with Meal Planning Agent that i built before

Both projects demonstrate the same HazelJS patterns but for different domains:

Feature	Meal Planning Agent	Travel Itinerary Agent
Domain	Food & nutrition	Travel & destinations
Knowledge Base	Recipe database	Destination database
Output	Meal plans, shopping lists	Itineraries, logistics
Similarities	Multi-agent, RAG, supervisor	Multi-agent, RAG, supervisor

This consistency shows how HazelJS patterns scale across different use cases while maintaining code structure and best practices.

Conclusion

This travel itinerary planner demonstrates how HazelJS enables building sophisticated AI applications with production-ready patterns. The combination of multi-agent orchestration, RAG, and resilience features makes it easy to create reliable, observable, and scalable AI-native applications for travel planning.

Complete project: Travel Planner
Try it out and explore how HazelJS can accelerate your AI development!

A Meal Planner & Grocery Shopping Agent in Typescript with HazelJS

Nisa Fatima — Sat, 13 Jun 2026 16:33:41 +0000

In this post, we'll build a practical AI-powered meal planning agent using HazelJS. This agent helps users create personalized meal plans, discover recipes, and generate shopping lists—all while demonstrating HazelJS's powerful agent orchestration, RAG capabilities, and production-ready patterns.

What We're Building

Our meal planning agent handles the complete meal planning workflow:

Dietary Intake: Extracts dietary restrictions, budget, cooking time, and preferences
Recipe Search: Finds recipes using RAG over a recipe database
Meal Planning: Creates day-by-day meal plans with balanced nutrition
Shopping Lists: Generates organized grocery lists with cost estimates
Nutrition Coaching: Orchestrates the entire workflow via supervisor routing

Why HazelJS?

HazelJS provides a production-ready framework for building AI-native applications. For this project, we leverage:

Multi-agent orchestration with @Agent, @Tool, and @Delegate decorators
RAG (Retrieval-Augmented Generation) for semantic recipe search
Supervisor routing to delegate tasks to specialized agents
Production resilience with retries, circuit breakers, and rate limiting
Built-in observability via the HazelJS Inspector
Guardrails for safer AI recommendations

Project Architecture

meal-planning-agent/
├── src/
│   ├── agents/              # Agent implementations
│   │   ├── dietary-intake.agent.ts
│   │   ├── recipe-search.agent.ts
│   │   ├── meal-plan.agent.ts
│   │   ├── shopping-list.agent.ts
│   │   └── nutrition-coach.agent.ts
│   ├── providers/           # LLM and embedding providers
│   │   ├── meal-planning-llm.provider.ts
│   │   └── local-embedding.provider.ts
│   ├── data/                # Recipe fixtures
│   │   └── recipe-fixtures.ts
│   ├── meal/                # Controllers and services
│   │   ├── meal.controller.ts
│   │   └── recipe-kb.service.ts
│   ├── app.module.ts
│   ├── health.controller.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Agent Implementation

Dietary Intake Agent

The DietaryIntakeAgent extracts structured information from natural language:

@Agent({
  name: 'DietaryIntakeAgent',
  description: 'Extracts dietary restrictions, budget, cooking time, cuisine preferences, and nutritional goals.',
  systemPrompt: 'You are a dietary intake specialist. Extract the user profile before any meal plan is created.',
  maxSteps: 4,
  temperature: 0,
})
@Service()
export class DietaryIntakeAgent {
  @Tool({
    name: 'extractDietaryProfile',
    description: 'Extract structured dietary planning information from a user request.',
    parameters: [
      { name: 'message', type: 'string', description: 'The raw user request', required: true },
      { name: 'userId', type: 'string', description: 'User id when available', required: false },
    ],
  })
  async extractDietaryProfile(input: { message: string; userId?: string }) {
    const dietaryRestrictions = this.extractDietaryRestrictions(input.message);
    const budget = this.extractBudget(input.message) ?? 150;
    const cookingTime = this.extractCookingTime(input.message) ?? 30;

    return {
      userId: input.userId ?? 'user-demo',
      dietaryRestrictions,
      budget,
      cookingTime,
      // ... more fields
    };
  }
}

Recipe Search Agent with RAG

The RecipeSearchAgent uses RAG to find recipes semantically:

@Agent({
  name: 'RecipeSearchAgent',
  description: 'Retrieves recipes from the knowledge base based on dietary restrictions, cuisine, and nutritional goals.',
  systemPrompt: 'You are a recipe search specialist. Use retrieved context only and cite source ids.',
  enableRAG: true,
  ragTopK: 3,
  maxSteps: 4,
  temperature: 0,
})
@Service()
export class RecipeSearchAgent {
  constructor(private readonly knowledgeBase: RecipeKnowledgeBaseService) {}

  @Tool({
    name: 'searchRecipes',
    description: 'Search recipes based on dietary preferences, cuisine, and nutritional goals.',
    parameters: [
      { name: 'query', type: 'string', description: 'The recipe search query', required: true },
      { name: 'topK', type: 'number', description: 'Number of recipes to retrieve', required: false },
    ],
  })
  async searchRecipes(input: { query: string; topK?: number }) {
    return this.knowledgeBase.answer(input.query, input.topK ?? 3);
  }
}

Nutrition Coach with Supervisor

The NutritionCoachAgent orchestrates the workflow using delegation:

@Agent({
  name: 'NutritionCoachAgent',
  description: 'Coordinates dietary intake, recipe retrieval, meal planning, and shopping list creation.',
  systemPrompt: 'You are the nutrition coach orchestrator. Extract constraints, retrieve recipes, build meal plans, and create shopping lists.',
  maxSteps: 8,
  temperature: 0,
})
@Service()
export class NutritionCoachAgent {
  @Delegate({
    agent: 'DietaryIntakeAgent',
    description: 'Extract dietary restrictions, budget, cooking time, and preferences from a user request.',
    inputField: 'input',
  })
  async analyzeMealRequest(input: string): Promise<string> {
    return '';
  }

  @Delegate({
    agent: 'RecipeSearchAgent',
    description: 'Retrieve recipes based on dietary preferences and nutritional goals.',
    inputField: 'input',
  })
  async getRecipes(input: string): Promise<string> {
    return '';
  }
  // ... more delegates
}

RAG Implementation

We use MemoryVectorStore and RAGPipeline for semantic recipe search:

@Service()
export class RecipeKnowledgeBaseService {
  private readonly embeddings = new LocalMealEmbeddingProvider();
  private readonly vectorStore = new MemoryVectorStore(this.embeddings);
  private readonly rag = new RAGPipeline({
    vectorStore: this.vectorStore,
    embeddingProvider: this.embeddings,
    topK: 3,
  });

  async answer(query: string, topK = 3) {
    const sources = await this.rag.retrieve(query, { topK }, RetrievalStrategy.HYBRID);
    return {
      answer: sources.map((source) => source.content).join('\n\n'),
      sources: sources.map((source) => ({
        id: source.id,
        score: Number(source.score.toFixed(3)),
        cuisine: source.metadata?.cuisine,
        dietary: source.metadata?.dietary,
        // ... more metadata
      })),
    };
  }
}

Production Configuration

The AgentModule is configured with production-ready features:

@HazelModule({
  imports: [
    ConfigModule.forRoot({ envFilePath: ['.env', '.env.local'], isGlobal: true }),
    CacheModule.forRoot({ strategy: 'memory', isGlobal: true }),
    InspectorModule.forRoot({ inspectorBasePath: '/__hazel', developmentOnly: true }),
    GuardrailsModule.forRoot({
      redactPIIByDefault: true,
      blockInjectionByDefault: true,
      blockToxicityByDefault: true,
    }),
    AIModule,
    RAGModule,
    AgentModule.forRoot({
      runtime: {
        llmProvider: new MealPlanningLocalLLMProvider(),
        defaultMaxSteps: 8,
        defaultTimeout: 15000,
        enableObservability: true,
        enableMetrics: true,
        enableRetry: true,
        enableCircuitBreaker: true,
        rateLimitPerMinute: 120,
      },
    }),
  ],
  controllers: [HealthController, MealController],
  providers: [
    RecipeKnowledgeBaseService,
    DietaryIntakeAgent,
    RecipeSearchAgent,
    MealPlanAgent,
    ShoppingListAgent,
    NutritionCoachAgent,
  ],
})
export class AppModule {}

Running the Project

# Install dependencies
npm install --legacy-peer-deps

# Build the project
npm run build

# Run eval tests
npm run eval

# Start development server
npm run dev

Testing the API

# Health check
curl http://localhost:3000/health

# Dietary intake
curl -s -X POST http://localhost:3000/meal/intake \
  -H 'content-type: application/json' \
  -d '{"message":"I am vegetarian, have a $150 weekly budget, can cook 30 mins per meal.","userId":"user-1"}'

# Recipe search with RAG
curl -s -X POST http://localhost:3000/meal/recipes \
  -H 'content-type: application/json' \
  -d '{"message":"Find high-protein vegetarian recipes"}'

# Supervisor orchestration
curl -s -X POST http://localhost:3000/meal/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"I am vegetarian, have a $150 weekly budget, can cook 30 mins per meal. Plan my week with high-protein options.","userId":"user-1"}'

HazelJS Inspector

Access the built-in inspector at http://localhost:3000/__hazel for:

Real-time agent execution traces
Tool call logs
Performance metrics
Circuit breaker status
Rate limiter status

Key Takeaways

Multi-agent architecture: Each agent has a focused responsibility, making the system maintainable and testable
RAG for knowledge retrieval: Semantic search over recipe database provides accurate, context-aware results
Supervisor routing: The orchestrator agent delegates tasks to specialists, enabling complex workflows
Production resilience: Built-in retries, circuit breakers, and rate limiting ensure reliability
Observability: The inspector provides deep insights into agent behavior and performance
Guardrails: PII redaction and content safety protect users from inappropriate recommendations

What's Next?

For a production deployment, you would:

Replace the local LLM provider with OpenAI, Anthropic, or Google Generative AI
Add persistent storage with @hazeljs/memory for user preferences and meal history
Implement @hazeljs/flow for advanced workflow orchestration
Add @hazeljs/pubsub for async meal planning notifications
Connect to real recipe APIs for dynamic content

Conclusion

This meal planning agent demonstrates how HazelJS enables building sophisticated AI applications with production-ready patterns. The combination of multi-agent orchestration, RAG, and resilience features makes it easy to create reliable, observable, and scalable AI-native applications.

Complete project is available here: Meal Planning Agent
See you next time!

Building a Personal Study Planner Agent in typescript with HazelJS

Nisa Fatima — Sun, 07 Jun 2026 18:54:46 +0000

AI agents become more useful when they are not just chatbots, but small systems that can understand a request, call tools, retrieve knowledge, and return structured results.

For this example, we built a Personal Study Planner Agent with HazelJS.

The goal is simple:

A student gives their exam date, available study time, and weak topics. The agent creates a realistic study plan.

This is an easy project, but it still shows important HazelJS agent patterns.

What the Project Includes

The project uses:

@hazeljs/core for modules, controllers, and services
@hazeljs/agent for agents, tools, delegation, and supervisor routing
@hazeljs/rag for study-method retrieval
@hazeljs/guardrails for safer input/output handling
@hazeljs/eval for golden tests
@hazeljs/inspector for the /__hazel web view

The app has four agents:

StudyIntakeAgent
StudyResourceAgent
StudyScheduleAgent
StudyCoachAgent

Each agent has a focused job.

Why This Example Works Well

A study planner is simple enough to understand quickly, but it still has a real workflow:

Extract study constraints
Find useful study methods
Build a schedule
Return a clear plan

That makes it a good beginner-friendly HazelJS agent example.

A sample request looks like this:

I have 10 days before my algebra exam. I can study 60 minutes daily. Weak topics are quadratic equations and word problems.

The system can extract the exam, timeline, daily capacity, weak topics, and urgency.

Agent 1: Study Intake

The first agent is StudyIntakeAgent.

Its job is to understand the student’s request.

@Agent({
  name: 'StudyIntakeAgent',
  description: 'Extracts exam goals, time constraints, weak topics, learning style, and urgency.',
})
@Service()
export class StudyIntakeAgent {
  @Tool({
    name: 'extractStudyProfile',
    description: 'Extract structured study planning information from a student request.',
  })
  async extractStudyProfile(input: { message: string; studentId?: string }) {
    // Extract exam, days, minutes, weak topics, and urgency
  }
}

This keeps profile extraction separate from schedule creation.

That is a good agent design pattern: one agent, one responsibility.

Agent 2: Study Resources with RAG

The second agent is StudyResourceAgent.

It uses HazelJS RAG to retrieve study methods like:

active recall
spaced repetition
interleaving
exam review
healthy study breaks

@Agent({
  name: 'StudyResourceAgent',
  description: 'Retrieves evidence-based study methods and review tactics.',
  enableRAG: true,
})
@Service()
export class StudyResourceAgent {
  @Tool({
    name: 'searchStudyMethods',
    description: 'Search study method guidance for planning, review, recall, and exam preparation.',
  })
  async searchStudyMethods(input: { query: string; topK?: number }) {
    return this.knowledgeBase.answer(input.query, input.topK ?? 3);
  }
}

This is better than asking the model to invent study advice. The agent retrieves known study methods and uses those as context.

Agent 3: Study Schedule

The third agent is StudyScheduleAgent.

It creates the actual day-by-day plan.

@Agent({
  name: 'StudyScheduleAgent',
  description: 'Creates realistic daily study plans with review checkpoints.',
})
@Service()
export class StudyScheduleAgent {
  @Tool({
    name: 'createStudySchedule',
    description: 'Create a day-by-day study schedule from exam constraints and weak topics.',
  })
  async createStudySchedule(input: {
    exam: string;
    daysUntilExam: number;
    minutesPerDay: number;
    weakTopics: string[];
  }) {
    // Build daily schedule
  }
}

The tool returns a structured plan with:

day number
focus topic
study minutes
activities
checkpoint

This makes the output easier to use in a real app.

Agent 4: Study Coach Orchestrator

The StudyCoachAgent coordinates the other agents.

It uses HazelJS @Delegate:

@Delegate({
  agent: 'StudyIntakeAgent',
  description: 'Extract exam, timeline, weak topics, capacity, and urgency.',
  inputField: 'input',
})
async analyzeStudyRequest(input: string): Promise<string> {
  return '';
}

It can delegate to:

StudyIntakeAgent
StudyResourceAgent
StudyScheduleAgent

This keeps orchestration clean without putting everything into one giant prompt.

Supervisor Routing

The project also uses HazelJS supervisor routing.

const supervisor = runtime.createSupervisor({
  name: 'study-planner-supervisor',
  workers: ['StudyIntakeAgent', 'StudyResourceAgent', 'StudyScheduleAgent'],
  maxRounds: 4,
});

The supervisor decides which agent should handle the request.

For example, a schedule request is routed to StudyScheduleAgent.

A method question is routed to StudyResourceAgent.

This is useful when the app does not know ahead of time which specialist should run.

Runtime Safety and Observability

The app configures the HazelJS agent runtime with production-friendly settings:

AgentModule.forRoot({
  runtime: {
    defaultMaxSteps: 8,
    defaultTimeout: 15000,
    enableObservability: true,
    enableMetrics: true,
    enableRetry: true,
    enableCircuitBreaker: true,
    rateLimitPerMinute: 120,
  },
})

This gives the agent system:

step limits
timeouts
retries
circuit breaker protection
metrics
rate limiting
observability

Even for a small demo, these are good habits.

Guardrails

The app enables HazelJS guardrails:

GuardrailsModule.forRoot({
  redactPIIByDefault: true,
  blockInjectionByDefault: true,
  blockToxicityByDefault: true,
})

This helps keep inputs and outputs safer.

For a study planner, guardrails are useful because users may paste personal details, stress-related messages, or unsafe instructions.

Testing with Evals

The project includes golden evals with @hazeljs/eval.

The evals check:

whether the intake agent calls extractStudyProfile
whether the resource agent retrieves the right study methods
whether the schedule agent calls createStudySchedule

Example:

{
  "id": "schedule-biology",
  "input": "Build a plan for my biology exam in 14 days with 90 minutes daily. Weak topics are photosynthesis and genetics.",
  "expectedOutput": "Study schedule complete",
  "expectedToolCalls": ["createStudySchedule"]
}

Run:

npm run eval

Expected result:

[hazeljs/eval] personal-study-planner-agent@2026.06 avg=0.944 passed=true

This proves the project is not only returning text, but also using the right tools.

Running the Project

Install dependencies:

npm install

Run evals:

npm run eval

Start the app:

npm run dev

Test the supervisor endpoint:

curl -s -X POST http://localhost:3000/study/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"I have 10 days before my algebra exam. I can study 60 minutes daily. Weak topics are quadratic equations and word problems.","userId":"student-2"}'

Open the HazelJS inspector:

http://localhost:3000/__hazel

You can also inspect registered agents and tools:

http://localhost:3000/study/runtime

Why Use a Local Provider?

The demo uses a deterministic local provider.

That means:

no API key is required
outputs are stable
evals are repeatable
readers can run the project immediately

In production, you can replace it with a real model provider through HazelJS AI integrations.

Final Thoughts

This project is intentionally simple, but it shows strong HazelJS agent patterns:

focused agents
scoped tools
RAG-backed knowledge
delegation
supervisor routing
guardrails
runtime observability
evals

That makes the Personal Study Planner Agent a good beginner-friendly example for learning how to build practical AI agents with HazelJS.
Repo: Personal Study Planner

Building Production-Ready AI Agents in typescript with HazelJS

Nisa Fatima — Mon, 01 Jun 2026 06:03:42 +0000

AI agents are easy to demo but harder to ship.

A real agent system needs more than a prompt and a few tools. It needs clear responsibilities, safe tool execution, retrieval, observability, approvals, and tests.

To demonstrate these best practices, we built an AI Support Operations Desk with HazelJS.

The project includes:

TriageAgent for classifying customer requests
KnowledgeAgent for RAG-based policy lookup
ActionAgent for order, ticket, and refund tools
SupportOrchestratorAgent for delegation
Supervisor routing across specialist agents
Guardrails for safer input/output handling
Human approval for refunds
Runtime metrics, traces, and health checks
Golden evals with @hazeljs/eval

Why a Support Desk?

A support request often requires multiple steps:

Customer CUST-1001 asks where order ORD-1001 is and whether it can still be refunded.

To handle this safely, an agent system must:

Understand the intent
Check the order
Retrieve refund policy
Decide whether approval is required
Call the right tool
Return a safe response

That makes support operations a strong example for production-ready agents.

1. Use Focused Agents

Avoid one giant agent that does everything.

In this project, each agent has one responsibility:

TriageAgent classifies the request
KnowledgeAgent retrieves policy context
ActionAgent performs support actions
SupportOrchestratorAgent coordinates the flow

Example:

@Agent({
  name: 'TriageAgent',
  description: 'Classifies support requests by intent, urgency, safety risk, and next best worker.',
  systemPrompt:
    'You are a support triage specialist. Classify the request before any action is taken.',
})
@Service()
export class TriageAgent {
  @Tool({
    name: 'classifySupportIntent',
    description: 'Classify a customer support message.',
  })
  async classifySupportIntent(input: { message: string; customerId?: string }) {
    // classification logic
  }
}

This keeps the system easier to test, debug, and extend.

2. Keep Tools Narrow

Tools should be specific and auditable.

Instead of a broad tool like:

executeCustomerRequest(input: string)

use focused tools:

@Tool({
  name: 'lookupOrder',
  description: 'Look up order status, shipment details, refund eligibility, and amount.',
})
async lookupOrder(input: { orderId: string }) {
  // order lookup
}

The ActionAgent exposes separate tools:

lookupOrder
createSupportTicket
requestRefundApproval

This makes every agent action visible in the trace.

3. Require Approval for Sensitive Actions

Refunds should not happen silently.

HazelJS tools can require approval:

@Tool({
  name: 'requestRefundApproval',
  description: 'Queue an eligible refund for human approval.',
  requiresApproval: true,
  policy: 'refunds_over_100_require_human_approval',
})
async requestRefundApproval(input: {
  orderId: string;
  amount: number;
  reason: string;
}) {
  // refund request
}

The agent can prepare the refund, but HazelJS pauses execution until a human approves it.

That is the right model for high-risk actions.

4. Use RAG for Policy Knowledge

Support agents should not guess policies.

The KnowledgeAgent uses HazelJS RAG:

import { MemoryVectorStore, RAGPipeline, RetrievalStrategy } from '@hazeljs/rag';

The app builds a small support knowledge base and exposes it as a tool:

@Tool({
  name: 'searchKnowledgeBase',
  description: 'Search support policies, runbooks, and response macros.',
})
async searchKnowledgeBase(input: { query: string; topK?: number }) {
  return this.knowledgeBase.answer(input.query, input.topK ?? 3);
}

This grounds answers in known policy documents.

5. Delegate Between Agents

HazelJS supports @Delegate, which lets one agent call another agent as a tool.

@Delegate({
  agent: 'TriageAgent',
  description: 'Classify support request intent, urgency, and safety risk.',
  inputField: 'input',
})
async triageCustomerRequest(input: string): Promise<string> {
  return '';
}

The orchestrator delegates to:

TriageAgent
KnowledgeAgent
ActionAgent

This keeps prompts and responsibilities clean.

6. Use Supervisor Routing

Some workflows are dynamic. A request may need triage, knowledge lookup, or action.

HazelJS can create a supervisor:

const supervisor = runtime.createSupervisor({
  name: 'support-ops-supervisor',
  workers: ['TriageAgent', 'KnowledgeAgent', 'ActionAgent'],
  maxRounds: 4,
  systemPrompt:
    'Route classification tasks to TriageAgent, policy questions to KnowledgeAgent, and order, ticket, or refund actions to ActionAgent.',
});

The supervisor decides which worker should handle the next step.

Example response:

{
  "rounds": [
    {
      "round": 1,
      "worker": "ActionAgent",
      "action": "delegate"
    },
    {
      "round": 2,
      "worker": "supervisor",
      "action": "finish"
    }
  ]
}

7. Enable Production Runtime Features

The app configures the HazelJS agent runtime like this:

AgentModule.forRoot({
  runtime: {
    defaultMaxSteps: 8,
    defaultTimeout: 15000,
    enableObservability: true,
    enableMetrics: true,
    enableRetry: true,
    enableCircuitBreaker: true,
    rateLimitPerMinute: 120,
  },
})

These features help prevent common production problems:

Infinite loops
Hanging executions
Provider failures
Rate spikes
Invisible errors

8. Add Guardrails

The app enables HazelJS guardrails:

GuardrailsModule.forRoot({
  redactPIIByDefault: true,
  blockInjectionByDefault: true,
  blockToxicityByDefault: true,
})

Guardrails help with:

PII redaction
Prompt injection detection
Toxicity blocking
Safer tool input/output handling

Prompts are useful, but guardrails give you enforceable protection.

9. Expose Traces

The support API returns execution steps:

{
  "steps": [
    {
      "step": 1,
      "state": "using_tool",
      "tool": "lookupOrder",
      "toolInput": {
        "orderId": "ORD-1001"
      }
    },
    {
      "step": 2,
      "state": "using_tool",
      "tool": "requestRefundApproval"
    }
  ]
}

This makes debugging much easier.

You can see which tool was called, what input was passed, and what the tool returned.

The project also exposes:

GET /support/runtime

This shows registered agents, tools, metrics, health, rate limiter status, and circuit breaker state.

10. Test with Evals

The project includes golden evals with @hazeljs/eval.

Example case:

{
  "id": "action-approved-refund",
  "input": "Customer CUST-1001 asks to refund order ORD-1001.",
  "expectedOutput": "Refund workflow complete",
  "expectedToolCalls": ["lookupOrder", "requestRefundApproval"]
}

The eval runner checks both:

Final output
Tool trajectory

That matters because an agent can say the right thing while calling the wrong tools.

Run evals:

npm run eval

Expected result:

[hazeljs/eval] support-ops-desk@2026.05 avg=1.000 passed=true

Running the Demo

Install dependencies:

npm install --legacy-peer-deps

Run evals:

npm run eval

Start the app:

npm run dev

Try the supervisor endpoint:

curl -s -X POST http://localhost:3010/support/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Customer CUST-1001 asks where order ORD-1001 is and whether it can still be refunded.","userId":"cust-1001","autoApprove":true}'

Open the HazelJS inspector:

http://localhost:3010/__hazel

Why the Demo Uses a Local Provider

The project uses a deterministic local LLM provider so anyone can run it without an API key.

That makes the demo:

Easy to install
Free to run
Stable for screenshots
Reliable for evals

In production, you can replace it with HazelJS AI provider integration for OpenAI, Anthropic, Gemini, Cohere, or Ollama.

Final Thoughts

Production agents need structure.

The most important patterns are:

Split work across focused agents
Keep tools narrow
Require approval for sensitive actions
Use RAG for domain knowledge
Delegate between specialists
Use supervisor routing
Enable guardrails and observability
Test behavior with evals

HazelJS makes these patterns feel like normal backend engineering, not agent glue code.
Github repo: support-ops-desk