Back to Templates

Tutor Agent

Multi-subject educational assistant with specialized tutor handoffs

Get Code

The tutor-agent template demonstrates the agent handoff pattern: a triage agent reads the student’s question, decides which subject it belongs to, and hands the conversation off to a specialist agent that answers it end to end.

What you’ll build

  • A triage_agent that classifies an incoming question by subject
  • A history_tutor_agent and a math_tutor_agent, each with domain-specific instructions
  • Handoffs wired with handoff() so the triage agent can transfer control without the caller managing routing logic
  • A single chat workflow that drives the whole exchange

Requirements

  • Python 3.12+ or Node.js 22+
  • OPENAI_API_KEY
  • The AGNT5 CLI

Install

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

Setup

Scaffold the project

agnt5 create —template python/tutor_agent my-tutor
cd my-tutor
agnt5 create —template typescript/tutor_agent my-tutor
cd my-tutor

Set environment variables

cp .env.example .env

Install dependencies

uv sync
pip install -e .
npm install

Start the AGNT5 dev server

agnt5 dev

How it works

The chat workflow runs the triage agent with the incoming message. The triage agent’s instructions tell it to classify the question - history, math, or general - and hand off to the matching specialist when appropriate. Each specialist is registered as a handoff target on the triage agent. Once a handoff fires, the specialist agent answers the question directly using its own domain-specific instructions; the workflow doesn’t need to know which specialist ultimately responded.

Passing the workflow’s context into the triage agent’s run call means the whole handoff chain - the triage turn and whichever specialist responds - checkpoints through the workflow’s durable context.

Tip:

The handoff contract is just a description string plus a target agent. Adding a third subject means writing one more specialist agent and one more handoff entry on the triage agent - no branching logic to maintain.

Key files

app.py                       - Worker entry point
src/tutor_agent/workflows.py - tutor_chat_workflow: a thin wrapper that runs the triage agent with context=ctx
src/tutor_agent/agents.py    - triage_agent, history_tutor_agent, math_tutor_agent, and their handoff wiring
app.ts            - Worker entry point
src/workflows.ts  - tutorChatWorkflow: a thin wrapper that runs the triage agent with ctx
src/agents.ts     - getHistoryTutorAgent(), getMathTutorAgent(), getTutorAgent(), and their handoff wiring

Customize

Add a subject. Write a new specialized Agent with its own instructions, then add a handoff(...) entry for it on triage_agent and mention the trigger criteria in the triage instructions.

Change the triage criteria. The decision logic lives entirely in the triage agent’s instructions in agents.py/agents.ts - no code branches to update.

Give a specialist tools. Pass a tools=[...] list to history_tutor_agent or math_tutor_agent (e.g. a check_equation tool for math) - handoffs preserve whatever tools the target agent defines.

Next steps