Skip to main content
Agent endpoints use Server-Sent Events (SSE) to stream real-time updates as AI agents generate personalized learning content.

​
Topic Agent

curl -X POST http://localhost:8000/api/agents/topics/abc123/run \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "small": false
  }'
POST /api/agents/topics/:topicNodeId/run Generate a complete learning path for a topic:
  1. Topic Agent creates a sequence of concepts
  2. Subconcept Bootstrap Agents (parallel) create subconcepts + diagnostic questions for each concept

​
Body Parameters

​
userId
string
required
User UUID
​
small
boolean
Generate a smaller learning path for testing (1-2 concepts, 2-3 subconcepts each). Default: false

​
SSE Events

​
agent_start
event
Agent has started
{ "agent": "topic" }
​
agent_reasoning
event
Claude’s reasoning between tool calls
{ "agent": "topic", "text": "I'll design a learning path with 6 concepts..." }
​
tool_call
event
Tool invocation
{ "tool": "save_concept", "input": { "title": "Variables", "desc": "..." } }
​
tool_result
event
Tool result (truncated to 200 chars)
{ "tool": "save_concept", "summary": "Created concept node id=abc123" }
​
node_created
event
New node persisted to DB
{ "node": { "id": "abc123", "title": "Variables", "type": "concept" } }
​
edge_created
event
New edge persisted to DB
{ "edge": { "source": "Variables", "target": "Functions" } }
​
agent_done
event
Agent completed successfully
{ "agent": "topic", "conceptCount": 6, "rationale": "..." }
​
agent_error
event
Agent failed
{ "agent": "topic", "message": "Rate limit exceeded" }

​
Concept Diagnostic

GET /api/agents/concepts/:conceptNodeId/diagnostic?userId=USER_ID Retrieve the diagnostic assessment for a concept (optional survey before refinement).

​
Response

​
agent
string
"concept"
​
status
string
"diagnostic_ready"
​
conceptNodeId
string
Concept node UUID
​
assessment
object
Assessment object
​
questions
array
Array of question objects
​
answeredCount
number
Number of answered questions
​
requiredAnswers
number
Total questions
​
isComplete
boolean
Whether all questions are answered

​
Concept Refinement Agent

curl -X POST http://localhost:8000/api/agents/concepts/abc123/run \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000"
  }'
POST /api/agents/concepts/:conceptNodeId/run Personalize the subconcept graph based on diagnostic answers. Flow:
  1. Bootstrap subconcepts if missing
  2. GRADE diagnostic answers
  3. OBSERVE current subconcepts + student history
  4. REASON about gaps and mastery
  5. ACT - add/remove subconcepts, insert prerequisite/follow-up concepts
  6. VERIFY graph integrity

​
Body Parameters

​
userId
string
required
User UUID

​
SSE Events

​
diagnostic_status
event
Diagnostic status summary
{
  "conceptNodeId": "abc123",
  "assessment": { ... },
  "answeredCount": 3,
  "requiredAnswers": 5
}
​
agent_reasoning
event
Agent’s reasoning steps
{
  "agent": "concept_refinement",
  "text": "Student struggled with closures (score 0.4). I'll add a bridge subconcept..."
}
​
node_created
event
New subconcept added
​
node_removed
event
Subconcept removed
{ "nodeId": "xyz789" }
​
edge_created
event
Dependency edge created
​
edge_removed
event
Dependency edge removed
{ "sourceNodeId": "abc", "targetNodeId": "def" }

​
Path Review Agent

curl -X POST http://localhost:8000/api/agents/nodes/abc123/review \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "00000000-0000-0000-0000-000000000000",
    "overview": "Student completed this concept quickly",
    "maxAdditions": 3
  }'
POST /api/agents/nodes/:nodeId/review Post-completion review - decide if enrichment nodes should be added to the learning path.

​
Body Parameters

​
userId
string
required
User UUID
​
overview
string
Optional context about the student’s performance
​
maxAdditions
number
Maximum number of nodes to add (default varies by agent)

​
Response

​
agent
string
"path_review"
​
status
string
"no_change" or "updated"
​
nodeId
string
Reviewed node UUID
​
level
string
"concept" or "subconcept"
​
decision
object
Agent’s decision object (includes should_add, notes, additions)
​
insertedNodes
array
Array of newly created nodes
​
createdEdges
array
Array of newly created edges

​
Agent Tools

Agents use structured tools to observe, reason, act, and verify:

​
Topic Agent Tools

  • extract_all_concept_contexts - Batch-extract document sections for concepts
  • save_concept - Create concept node
  • save_concept_edge - Create dependency edge

​
Subconcept Bootstrap Tools

  • save_diagnostic_question - Create diagnostic question (MCQ or open-ended)
  • save_subconcept - Create subconcept node
  • save_subconcept_edge - Create dependency edge

​
Concept Refinement Tools

  • grade_student_answers - Grade diagnostic answers via sub-agent
  • get_current_subconcepts - View subconcept graph
  • check_student_history - Cross-concept performance
  • add_subconcept - Add bridge/remedial subconcept
  • remove_subconcept - Remove mastered subconcept
  • add_prerequisite_concept - Insert concept before current
  • add_followup_concept - Insert concept after current
  • validate_graph - Check for orphans/cycles via BFS

Build docs developers (and LLMs) love

Get started for freeTalk to us