Skip to content

agents.md

Latest commit

 

History

History
156 lines (120 loc) · 4.98 KB

agents.md

File metadata and controls

156 lines (120 loc) · 4.98 KB
Raw

AI Agents

This document describes the AI agents that power the LearnPath webapp. Each agent has a clearly scoped responsibility so the system remains modular and easy to extend.

1. Onboarding Agent

Trigger: User registration / first login
Model: LLM (e.g. GPT-4o)

Responsibility

Conducts a structured interview with the new user to understand:

  • Current knowledge level per macro-area (e.g., Web, Databases, AI/ML, Systems, Cloud …)
  • Learning goals (generalist engineer, AI-focused, DevOps specialist …)
  • Available time per week and preferred session length (30 min / 1 h)
  • Learning style (theory-first vs hands-on)

Output

A UserProfile JSON object that is stored in the database and used by the Path Planner Agent and the Session Agent.

{
  "userId": "...",
  "knownTopics": ["html", "css", "javascript-basics"],
  "goals": ["generalist", "ai-engineering"],
  "weeklyHours": 5,
  "sessionDuration": 45,
  "learningStyle": "hands-on"
}

2. Path Planner Agent

Trigger: After onboarding, or whenever the user asks to regenerate the path
Model: LLM + structured output parser

Responsibility

Given the UserProfile and the full TopicCatalog, it generates a personalised, ordered learning path:

  • Picks topics the user does not yet know
  • Respects prerequisite dependencies between topics (DAG traversal)
  • Groups topics into weekly blocks that fit the user's available time
  • Balances breadth (generalist coverage) and depth (key specialisations)

Output

A LearningPath document:

{
  "userId": "...",
  "generatedAt": "2026-01-01T00:00:00Z",
  "phases": [
    {
      "week": 1,
      "topics": ["git-basics", "linux-cli", "networking-fundamentals"]
    }
  ]
}

3. Session Agent (Chatbot)

Trigger: User starts a learning session
Model: LLM with streaming (e.g. GPT-4o)

Responsibility

Runs an interactive learning session for a single topic (30–60 minutes):

  1. Introduction – brief overview and why the topic matters
  2. Core concepts – explains key ideas with examples
  3. Prompt suggestions – proposes follow-up questions the user can ask to deepen understanding
  4. Mini-challenge – poses a small exercise or quiz to consolidate learning
  5. Summary – recap of what was covered and what to study next

The agent tracks which concepts within a topic have been covered so sessions can be resumed.

Prompt suggestion format

At each step the agent displays 2–4 clickable prompt suggestions, e.g.:

  • "Show me a concrete Redis caching example in Node.js"
  • "Explain the difference between Redis Pub/Sub and Streams"
  • "What are the most common Redis pitfalls?"

4. Catalog Updater Agent

Trigger: Scheduled (weekly cron) or manually by an admin
Model: LLM + web search / curated RSS feeds

Responsibility

Keeps the TopicCatalog up-to-date:

  • Discovers new technologies, frameworks, patterns and tools
  • Suggests additions to the catalog with metadata (category, prerequisites, difficulty)
  • Flags outdated topics (e.g. deprecated libraries) for review
  • All suggestions go through a human-review queue before publication

Output

Draft catalog entries:

{
  "id": "langchain-agents",
  "label": "Building Agents with LangChain",
  "category": "AI Engineering",
  "area": "Artificial Intelligence",
  "difficulty": "intermediate",
  "prerequisites": ["python-basics", "llm-fundamentals"],
  "estimatedMinutes": 60,
  "addedAt": "2026-03-15T00:00:00Z"
}

5. Progress Analyser Agent

Trigger: On-demand or after completing a session
Model: LLM (lightweight) + analytics queries

Responsibility

Analyses the user's learning history and produces:

  • Completion percentages per category and macro-area
  • Weak spots and knowledge gaps
  • Recommended next sessions based on progress and calendar availability
  • Motivational insights ("You're 80 % done with Databases!")

Output

A ProgressReport shown on the user's dashboard.

Agent Communication Overview

User
 │
 ├─► Onboarding Agent  ──► UserProfile ──► Path Planner Agent ──► LearningPath
 │                                                                       │
 ├─► Session Agent  ◄─────────────────────────────────────────────────── │
 │        │
 │        └─► Progress Analyser Agent ──► ProgressReport ──► Dashboard
 │
 └─► Catalog Updater Agent  ──► (admin review) ──► TopicCatalog

Technical Notes

  • All agents are implemented as LangChain chains/agents or OpenAI Assistants (configurable via env var AI_PROVIDER).
  • Agents communicate through the application database and event bus — they are not directly coupled.
  • Every agent call is logged with input/output for debugging and cost tracking.
  • System prompts for each agent live in src/agents/prompts/ and are version-controlled.