DEV Community: Nisa Fatima

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

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