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.

Homeowners face several challenges when it comes to maintenance:

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

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

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

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:

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,
      })),
    };
  }
}

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

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.

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

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.

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

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

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:

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

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

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.

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

The Home Maintenance Scheduler Agent demonstrates several key HazelJS capabilities:

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