DEV Community: Nisa Fatima

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

Building an Intelligent Business Intelligence Dashboard with HazelJS

Nisa Fatima — Mon, 18 May 2026 13:13:19 +0000

In today's data-driven world, businesses need more than just static reports—they need intelligent, real-time insights that drive decision-making. Enter the HazelJS Business Intelligence system, a powerful agent-based platform that transforms raw business data into actionable intelligence.

What is HazelJS?

HazelJS is a modern framework for building agent-based applications. It provides a robust foundation for creating intelligent systems that can analyze data, generate insights, and provide recommendations—all orchestrated through a clean, TypeScript-based architecture.

The Business Intelligence system built on HazelJS demonstrates the framework's capabilities by creating a fully interactive dashboard that combines:

Data ingestion from multiple sources
AI-powered analysis through specialized agents
Real-time visualization with interactive charts
Automated recommendations based on business metrics

Architecture Overview

The system is built around three core agents, each with a specific responsibility:

DataInsightsAgent
This agent analyzes business data to identify trends, opportunities, and anomalies. It processes sales, customer, and operational data to surface meaningful patterns that might otherwise go unnoticed.

ReportGeneratorAgent
Once insights are identified, this agent compiles them into comprehensive reports suitable for executive review. It summarizes findings, highlights critical issues, and provides context for decision-makers.

RecommendationEngineAgent
The most actionable component, this agent transforms insights into concrete recommendations. It prioritizes actions based on potential impact and provides estimated ROI and timeline information.

BusinessIntelligenceOrchestrator
The orchestrator coordinates all agents, ensuring they work together seamlessly. It manages the flow of data from raw input through analysis to final recommendations.

Key Features

Interactive Dashboard
The dashboard provides a modern, tabbed interface with four main sections:

Dashboard Tab

Real-time KPI cards showing Total Sales, Active Customers, Average Efficiency, and Insights Generated
Interactive sales trend chart powered by Chart.js
Filterable insights with search, category, and impact filters
Business recommendations with priority indicators

Data Entry Tab

Forms for adding sales records with amount and customer information
Customer entry forms with segmentation options
Operations data input for efficiency tracking
Clear data functionality for fresh starts

Scenarios Tab

Pre-built business scenarios for testing and demonstration
Quick data population for development and testing

Reports Tab

Executive report generation with summary metrics
CSV and JSON export functionality for data portability

Real-Time Updates
The dashboard automatically refreshes every 30 seconds, ensuring that KPIs, charts, and insights stay current. This live update capability is crucial for monitoring rapidly changing business metrics.

Advanced Filtering
Insights can be filtered by:

Search terms - Find specific insights by keyword
Category - Filter by trends, opportunities, anomalies, or risks
Impact level - Focus on critical, high, medium, or low impact items

Data Export
Users can export business data in two formats:

CSV - Spreadsheet-compatible format with separate sections for sales, customers, and operations
JSON - Structured format for integration with other systems

Getting Started

Prerequisites

Node.js >= 18.0.0
npm or yarn package manager

Installation

Clone the HazelJS repository or copy the hazeljs-business-intelligence directory
Navigate to the project directory
Install dependencies:

npm install

Note: If running outside the HazelJS monorepo, ensure your package.json includes all required dependencies:

{
  "dependencies": {
    "@hazeljs/agent": "^0.8.7",
    "@hazeljs/core": "^0.8.7",
    "@hazeljs/eval": "^0.8.7",
    "reflect-metadata": "^0.2.2"
  }
}

Running the Application

npm run dev

The dashboard will be available at http://localhost:3000/business-intelligence

Code Example: Adding a Custom Agent

The HazelJS framework makes it easy to extend the system with custom agents. Here's how you might add a new agent for inventory analysis:

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

interface InventoryInsight {
  lowStockItems: string[];
  overstockItems: string[];
  reorderRecommendations: string[];
}

class InventoryAgent extends Agent<<InventoryInsight> {
  constructor(config: AgentConfig) {
    super(config);
  }

  async analyze(data: any): Promise<<InventoryInsight> {
    const lowStock = data.inventory.filter(item => item.quantity < item.reorderPoint);
    const overstock = data.inventory.filter(item => item.quantity > item.maxStock);

    return {
      lowStockItems: lowStock.map(item => item.name),
      overstockItems: overstock.map(item => item.name),
      reorderRecommendations: lowStock.map(item => 
        `Reorder ${item.name}: ${item.reorderQuantity} units`
      )
    };
  }
}

Use Cases

Sales Performance Monitoring
Track sales trends in real-time, identify seasonal patterns, and receive recommendations for inventory adjustments based on historical data.

Customer Insights
Analyze customer segments, identify at-risk customers, and get recommendations for retention strategies based on purchase patterns.

Operational Efficiency
Monitor operational metrics, identify bottlenecks, and receive recommendations for process improvements based on efficiency data.

Executive Reporting
Generate comprehensive reports for stakeholders with automated insights and prioritized recommendations for strategic planning.

Technical Highlights

Type Safety
Built entirely in TypeScript, the system provides full type safety and excellent IDE support for development.

Decorator-Based Routing
The HazelJS framework uses decorators for clean, declarative routing:

@Controller('/business-intelligence')
class BusinessIntelligenceController {
  @Get('/insights')
  async getInsights(@Res() res: any) {
    // Handler logic
  }

  @Post('/add-sale')
  async addSale(@Body() body: { amount?: number; customerName?: string }, @Res() res: any) {
    // Handler logic
  }
}

Dependency Injection
The framework provides robust dependency injection for managing services and agents.

Modular Architecture
Each component is designed to be modular and reusable, making it easy to extend or customize for specific business needs.

Future Enhancements
The system is designed to be extensible. Potential future enhancements include:

Integration with external data sources (databases, APIs)
Machine learning models for predictive analytics
Multi-tenant support for SaaS applications
Advanced visualization options with more chart types
Real-time notifications and alerts
Integration with popular BI tools

Conclusion

The HazelJS Business Intelligence system demonstrates the power of agent-based architectures for building intelligent business applications. By combining real-time data processing, AI-powered analysis, and interactive visualization, it provides a comprehensive solution for modern business intelligence needs.

Whether you're monitoring sales performance, analyzing customer behavior, or optimizing operations, this system provides the tools you need to turn data into actionable intelligence—all built on the robust HazelJS framework.

Ready to get started? Clone the repository, install the dependencies, and start building your intelligent business intelligence dashboard today!
Repo: hazeljs-business-intelligence