Back to Templates

Tutor Agent

Multi-subject educational assistant with specialized tutor handoffs

Get Code

The tutor-agent template is a teaching agent backed by a durable learner-state entity. Instead of answering directly, it asks questions that lead the learner toward the answer. The entity stores everything the tutor needs to adapt — topics seen, concepts the learner has struggled with, current difficulty level — so sessions days apart still feel like one continuous conversation.

What you’ll build

  • A Socratic agent that answers with guiding questions rather than direct solutions
  • A Learner entity that persists per-user state (topics covered, strengths, gaps, difficulty)
  • Adaptive difficulty that ratchets up after correct answers and eases after repeated misses
  • A replayable session log so you can review or audit any past lesson

Requirements

  • Python 3.10+
  • OPENAI_API_KEY or ANTHROPIC_API_KEY
  • The AGNT5 CLI

Install

curl -LsSf https://agnt5.com/cli.sh | bash

Setup

Scaffold the project

agnt5 create tutor_agent my-tutor
cd my-tutor

Set environment variables

export OPENAI_API_KEY=sk-...

Install dependencies

uv sync
pip install -e .

Start a tutoring session

agnt5 dev up
agnt5 invoke tutor_turn --input '{
  "learner_id": "student_42",
  "subject": "algebra",
  "message": "I don'\''t get why we move the minus across the equals sign."
}'

Invoke tutor_turn again with the same learner_id and the tutor picks up with full memory of the prior turn.

How it works

Each tutor turn runs as a short workflow. The workflow loads the Learner entity keyed by learner_id, reads the current subject, skill profile, and recent history, and hands that context to the agent as part of its system prompt. The agent then decides whether to ask a guiding question, confirm an understanding, or advance the difficulty. Before returning, the workflow updates the entity: appending the exchange to history, updating the skill profile based on the learner’s answer, and recording the new difficulty level.

The entity is what makes this feel like tutoring instead of a chatbot. It’s a keyed, durable state container with exactly-once write semantics — two concurrent turns for the same learner are serialized so the skill profile never races. And because the agent call is a ctx.step(), every turn is journaled. You can open a historical session in Studio, see exactly which model version answered each prompt, and replay the whole session with a new pedagogy prompt to compare approaches.

Use one entity per learner, not per session. Cross-session memory — “last week you worked on quadratics” — is the whole point.

Key files

  • worker.py — Registers the tutor workflow, the agent, and the Learner entity.
  • entities/learner.py — The Learner entity: subject history, skill profile, difficulty.
  • agent.py — The tutor workflow: load entity, run agent, update entity.
  • prompts/socratic.txt — System prompt that enforces the Socratic style.

Customize

Change the pedagogy. prompts/socratic.txt is the lever. Swap it for a direct-instruction prompt or a spaced-repetition coach — the entity schema doesn’t need to change.

Add subject-specific tools. Give the agent a check_equation or run_code tool and the template becomes a math or programming tutor. Tool calls journal alongside the agent step.

Extend the learner profile. Add fields to the Learner entity — learning style, pacing preferences, goals — and feed them into the prompt. Entity migrations are safe because the journal records the schema version per write.

Next steps