Building a Home Maintenance Scheduler Agent in typescript with HazelJS

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.