DEV Community: Nisa Fatima

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