A Travel Itinerary Planner Agent in Typescript with HazelJS

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!

推荐订阅源

DEV Community