Overview
Sprout uses seven autonomous AI agents powered by Claude that observe student data, reason about learning patterns, act on the knowledge graph, and verify their own changes. All agents share a common agent loop architecture that enables multi-turn tool calling, retry logic, and reasoning visibility.Agent Loop
Shared foundation for all agents with tool calling and reasoning
Topic Agent
Generates learning paths of 6-10 concepts for any topic
Subconcept Agent
Builds diagnostic questions and subconcept DAGs
Refinement Agent
Personalizes learning paths using the ORAV loop
Tutor Agent
Teaches concepts chunk-by-chunk with exercises
Grading Agent
Evaluates diagnostic answers with semantic understanding
Agent architecture
All agents follow a consistent pattern:Tool-calling loop
Agents use Claude’s native tool calling to interact with the database and learning graph. Each agent has access to specialized tools for its domain.
Reasoning visibility
Claude’s reasoning text between tool calls is captured and streamed as
agent_reasoning SSE events, providing transparency into the agent’s decision-making process.Error handling
Rate limits are automatically retried with exponential backoff (2s, 4s, 8s). Failed operations are logged and reported via SSE events.
The seven agents
Primary agents
These agents handle the core learning pathway generation and adaptation:1. Topic Agent
1. Topic Agent
Purpose: Design a learning path of concepts for any topic.Process:
- Analyzes the topic and uploaded documents
- Generates 6-10 concept nodes (or 1-2 in small mode)
- Extracts relevant document context for each concept
- Creates prerequisite edges between concepts
sprout-backend/src/agents/topic-agent.ts2. Subconcept Bootstrap Agent
2. Subconcept Bootstrap Agent
Purpose: Build the learning structure for a single concept.Process:
- Creates 5-10 diagnostic questions (MCQ + open-ended)
- Generates 8-12 subconcept nodes as a DAG
- Wires dependency edges between subconcepts
sprout-backend/src/agents/subconcept-bootstrap-agent.ts3. Concept Refinement Agent
3. Concept Refinement Agent
Purpose: Personalize the subconcept graph after diagnostics.Process (Observe-Reason-Act-Verify loop):
- Grade diagnostic answers
- Observe current graph and student history
- Reason about gaps and misconceptions
- Act by adding/removing subconcepts
- Verify graph integrity
- Verify again after fixes
sprout-backend/src/agents/concept-agent.ts4. Tutor Agent
4. Tutor Agent
Purpose: Teach subconcepts interactively with exercises.Process:
- Checks diagnostic results and prerequisite mastery
- Breaks subconcept into 3-6 chunks
- For each chunk: explain → ask question → evaluate answer
- Records exercise results and updates mastery scores
- Marks complete when all chunks are covered
sprout-backend/src/agents/tutor-chat.tsSupporting agents
These agents provide specialized functionality:5. Grade Answers Agent
5. Grade Answers Agent
Purpose: Grade diagnostic answers with semantic understanding.Process:
- MCQ answers: Direct correctness check
- Open-ended answers: Semantic evaluation against rubric
- Returns correctness, score (0-1), and detailed feedback
sprout-backend/src/agents/grade-answers.ts6. Generate Diagnostic Agent
6. Generate Diagnostic Agent
Purpose: Create diagnostic questions for concept assessment.Process:
- Generates 5-10 questions per concept
- Mixes MCQ and open-ended formats
- Varies difficulty levels (1-5 scale)
- Includes grading rubrics for open-ended questions
sprout-backend/src/agents/generate-diagnostic.ts7. Review Learning Path Agent
7. Review Learning Path Agent
Purpose: Post-completion path enrichment and remediation.Process:
- Reviews student mastery across all concepts
- Identifies areas for enrichment or reinforcement
- Decides whether to insert additional concepts/subconcepts
sprout-backend/src/agents/review-learning-path.tsAgent orchestration
Agents are orchestrated through SSE streaming endpoints:Topic generation pipeline
- Topic Agent generates concepts (streamed via SSE)
- Subconcept Bootstrap Agents run in parallel (max 3 concurrent) for each concept
Concept refinement
- Phase 1 (no answers yet): Returns diagnostic questions as JSON
- Phase 2 (answers submitted): Streams concept refinement agent via SSE
Interactive tutoring
Path review
SSE events
All streaming endpoints emit real-time events:| Event | Data | Description |
|---|---|---|
agent_start | { agent } | Agent has started |
agent_reasoning | { agent, text } | Claude’s reasoning between tool calls |
tool_call | { tool, input } | Tool invocation |
tool_result | { tool, summary } | Tool result (truncated to 200 chars) |
node_created | { node } | New node persisted to DB |
edge_created | { edge } | New edge persisted to DB |
node_removed | { nodeId } | Node deleted |
edge_removed | { sourceNodeId, targetNodeId } | Edge deleted |
agent_done | { agent, ... } | Agent completed successfully |
agent_error | { agent, message } | Agent failed |
SSE events provide real-time visibility into agent operations, allowing the frontend to update the 3D graph as nodes and edges are created.
Complete learning flow
Here’s how all agents work together:Topic creation
User creates a topic and uploads documents. Topic Agent generates 6-10 concept nodes.
Subconcept generation
Subconcept Bootstrap Agents run in parallel (max 3 concurrent) to create diagnostics and subconcept DAGs for each concept.
Diagnostic assessment
User answers 5-10 diagnostic questions. Grade Answers Agent evaluates responses.
Path adaptation
Concept Refinement Agent personalizes the subconcept graph using the ORAV loop based on diagnostic performance.
Interactive learning
User learns subconcepts with the Tutor Agent, which teaches chunk-by-chunk and records mastery scores.
Next steps
Agent Loop Implementation
Dive into the shared agent loop architecture
Refinement Agent
Learn about the ORAV loop and graph adaptation