The Tutor Agent provides interactive, personalized instruction for each subconcept. It breaks learning into digestible chunks, asks checkpoint questions, and records mastery scores.Location: sprout-backend/src/agents/tutor-chat.ts
The tutor follows a chunk-based teaching methodology:
1
Check prerequisites
Verifies that prerequisite subconcepts have been mastered before teaching.
2
Break into chunks
Divides the subconcept into 3-6 digestible learning units.
3
Teach each chunk
For each chunk: explain concept → ask checkpoint question → evaluate answer.
4
Record progress
After exercises, calls record_exercise_result to update mastery scores.
5
Mark complete
When all chunks are covered and mastery threshold (0.7) is reached, marks subconcept complete.
The tutor uses Socratic method - guiding students to discover answers rather than directly telling them. It asks leading questions and provides hints when students struggle.
{ "exercise": { "prompt": "Write a function to delete a node from a BST", "type": "code", "starter_code": "def delete_node(root, key):\n # Your code here\n pass", "test_cases": [ { "input": "[10,5,20,3,7], key=5", "expected": "[10,7,20,3]" } ], "hints": [ "Consider three cases: no children, one child, two children", "For two children, find the in-order successor" ] }}
Explain: Three cases - leaf node, one child, two children.Question: “Which case is simplest to handle?”Expected: “Leaf node - just remove it.”
2
Chunk 2: Leaf node deletion
Explain: Find node, set parent pointer to null.Question: “What happens if the node to delete is the root and it’s a leaf?”Expected: “The tree becomes empty (root = null).”
3
Chunk 3: One child deletion
Explain: Replace node with its child.Question: “Why can we directly replace the node with its child?”Expected: “Because the child subtree already satisfies BST property.”
4
Chunk 4: Two children deletion
Explain: Find in-order successor, swap values, delete successor.Question: “Why use in-order successor instead of predecessor?”Expected: “Either works, but successor (smallest in right subtree) is convention.”
5
Chunk 5: Code implementation
Exercise: Write deletion function (code question).Evaluation: Run test cases, provide feedback.
6
Chunk 6: Edge cases
Exercise: Handle deletion when tree has only root (draw question).Evaluation: Check diagram correctness.
Chunk count varies based on subconcept complexity. Simple concepts might have 3 chunks, complex ones up to 6.
{ "type": "code", "prompt": "Write a function to search for a value in a BST.", "starter_code": "def search(root, target):\n pass", "test_cases": [ { "input": "[10,5,15], target=5", "expected": true }, { "input": "[10,5,15], target=7", "expected": false } ]}
Evaluation: Run test cases (Python exec or JavaScript eval).
{ "type": "draw", "prompt": "Draw the BST after inserting [10, 5, 15, 3, 7].", "evaluation_criteria": [ "Root is 10", "Left child of 10 is 5", "Right child of 10 is 15", "5 has children 3 (left) and 7 (right)" ]}
Evaluation: Claude analyzes the drawing (base64 image from Excalidraw) against criteria.
The Excalidraw integration allows students to draw tree diagrams directly in the learning interface. The tutor evaluates structure correctness.
export async function runTutorAgent({ sessionId, subconceptId, userId, studentMessage, sseWriter}: TutorAgentParams): Promise<TutorResponse> { // Load subconcept and progress const subconcept = await db.query.nodes.findFirst({ where: eq(nodes.id, subconceptId) }); const progress = await db.query.userNodeProgress.findFirst({ where: and( eq(userNodeProgress.userId, userId), eq(userNodeProgress.nodeId, subconceptId) ) }); // System prompt const systemPrompt = ` You are an expert AI tutor teaching: ${subconcept.title} ${subconcept.desc} Student's current mastery: ${progress?.masteryScore || 0} Teaching approach: 1. Break into 3-6 chunks 2. For each chunk: explain → ask question → evaluate 3. Use Socratic method - guide students to discover answers 4. Record exercise results to update mastery 5. Mark [COMPLETE] when mastery ≥ 0.7 `; // Run agent loop (5 iterations for tutor) const result = await agentLoop({ systemPrompt, userMessage: studentMessage, tools: tutorTools, maxIterations: 5, callbacks: { onThinking: (text) => sseWriter?.send("agent_reasoning", { agent: "tutor", text }), onToolCall: (tool, input) => sseWriter?.send("tool_call", { tool, input }), onToolResult: (tool, result) => sseWriter?.send("tool_result", { tool, result }) } }); return { content: result.finalText, isComplete: result.finalText.includes("[COMPLETE]"), toolsUsed: result.toolCalls.map(tc => tc.name), reasoning: result.conversationHistory };}
The tutor uses only 5 iterations (vs 15 for other agents) to keep interactions snappy. If students need more guidance, they can send additional messages.
{ "message": "I'm ready to learn about BST deletion.", "subconceptId": "sub5-deletion", "userId": "user-uuid-456"}
Response:
{ "content": "Great! Let's break down BST deletion into chunks. There are three cases to consider: deleting a leaf node, a node with one child, and a node with two children. Which case do you think is simplest?", "isComplete": false, "toolsUsed": ["check_student_progress", "check_prerequisite_mastery"], "reasoning": [ "Student is ready to learn deletion", "Prerequisites (searching, insertion) are mastered", "Starting with overview chunk" ]}
Student: “I’m ready to learn BST deletion.”Tutor: “Great! Let’s start. There are three cases: leaf, one child, two children. Which is simplest?”
2
Student responds
Student: “Leaf node?”Tutor: “Exactly! For a leaf, we just remove it. Now, what if the node has one child?”
3
Student asks for clarification
Student: “[CLARIFICATION] What if the node is the root?”Tutor: “Good question! If the root is a leaf, the tree becomes empty. If it has one child, that child becomes the new root.”
4
Tutor gives exercise
Tutor: “Let’s practice. Write a function to delete a leaf node.”Uses create_exercise tool
5
Student submits code
Student: (submits code)Tutor: Evaluates, calls record_exercise_result“Nice work! Your mastery is now 0.65. Let’s continue to two-children deletion.”
6
Completion
After several exercises:Tutor: “Excellent! You’ve mastered BST deletion (mastery: 0.75). [COMPLETE]“