Building a Personal Learning Path Agent in typescript with HazelJS

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.

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.