Building a Peer Tutoring Matching Agent: Connecting Students for Study Groups

Why Peer Tutoring Works

Research consistently shows that peer tutoring benefits both the tutor and the tutee. Tutors deepen their understanding by explaining concepts, while tutees receive relatable, accessible help. The challenge is logistics — matching students with complementary skills, coordinating schedules, and ensuring quality. An AI matching agent solves these coordination problems at scale.

Peer Tutoring Data Model

from dataclasses import dataclass, field
from enum import Enum
from datetime import datetime, date, time
from typing import Optional

class SkillLevel(Enum):
    BEGINNER = 1
    INTERMEDIATE = 2
    ADVANCED = 3
    EXPERT = 4

class SessionStatus(Enum):
    SCHEDULED = "scheduled"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    CANCELLED = "cancelled"
    NO_SHOW = "no_show"

class DayOfWeek(Enum):
    MON = "Monday"
    TUE = "Tuesday"
    WED = "Wednesday"
    THU = "Thursday"
    FRI = "Friday"
    SAT = "Saturday"
    SUN = "Sunday"

@dataclass
class TimeBlock:
    day: DayOfWeek
    start_time: time
    end_time: time

@dataclass
class SubjectSkill:
    subject: str
    course_code: str
    skill_level: SkillLevel
    can_tutor: bool  # True if they can tutor this subject
    wants_help: bool  # True if they need help

@dataclass
class StudentTutor:
    student_id: str
    name: str
    email: str
    major: str
    year: int
    skills: list[SubjectSkill] = field(default_factory=list)
    availability: list[TimeBlock] = field(default_factory=list)
    preferred_group_size: int = 2
    preferred_mode: str = "in_person"  # in_person, online, either
    rating_as_tutor: float = 0.0
    total_sessions_tutored: int = 0
    total_sessions_as_tutee: int = 0

@dataclass
class TutoringSession:
    session_id: str
    tutor_id: str
    tutee_ids: list[str]
    subject: str
    course_code: str
    scheduled_time: datetime
    duration_minutes: int = 60
    status: SessionStatus = SessionStatus.SCHEDULED
    location: str = ""
    feedback: list[dict] = field(default_factory=list)
    notes: str = ""

Matching Algorithm

The matching algorithm considers subject expertise gaps, schedule overlap, and tutor quality ratings.

flowchart LR
    CALLER(["Student or Parent"])
    subgraph TEL["Telephony"]
        SIP["Twilio SIP and PSTN"]
    end
    subgraph BRAIN["Education AI Agent"]
        STT["Streaming STT<br/>Deepgram or Whisper"]
        NLU{"Intent and<br/>Entity Extraction"}
        TOOLS["Tool Calls"]
        TTS["Streaming TTS<br/>ElevenLabs or Rime"]
    end
    subgraph DATA["Live Data Plane"]
        CRM[("CRM and Notes")]
        CAL[("Calendar and<br/>Schedule")]
        KB[("Knowledge Base<br/>and Policies")]
    end
    subgraph OUT["Outcomes"]
        O1(["Enrollment captured"])
        O2(["Tour scheduled"])
        O3(["Counselor callback"])
    end
    CALLER --> SIP --> STT --> NLU
    NLU -->|Lookup| TOOLS
    TOOLS <--> CRM
    TOOLS <--> CAL
    TOOLS <--> KB
    NLU --> TTS --> SIP --> CALLER
    NLU -->|Resolved| O1
    NLU -->|Schedule| O2
    NLU -->|Escalate| O3
    style CALLER fill:#f1f5f9,stroke:#64748b,color:#0f172a
    style NLU fill:#4f46e5,stroke:#4338ca,color:#fff
    style O1 fill:#059669,stroke:#047857,color:#fff
    style O2 fill:#0ea5e9,stroke:#0369a1,color:#fff
    style O3 fill:#f59e0b,stroke:#d97706,color:#1f2937

STUDENTS: dict[str, StudentTutor] = {}
SESSIONS: list[TutoringSession] = []

def find_tutor_matches(
    student_id: str, subject: str, course_code: str
) -> list[dict]:
    student = STUDENTS.get(student_id)
    if not student:
        return []

    # Verify student needs help in this subject
    needs_help = any(
        s.course_code == course_code and s.wants_help
        for s in student.skills
    )
    if not needs_help:
        return []

    student_availability = set(
        (tb.day, tb.start_time, tb.end_time)
        for tb in student.availability
    )

    matches = []
    for tutor_id, tutor in STUDENTS.items():
        if tutor_id == student_id:
            continue

        # Check if tutor can teach this subject
        tutor_skill = None
        for skill in tutor.skills:
            if skill.course_code == course_code and skill.can_tutor:
                tutor_skill = skill
                break
        if not tutor_skill:
            continue

        # Check schedule overlap
        tutor_availability = set(
            (tb.day, tb.start_time, tb.end_time)
            for tb in tutor.availability
        )
        common_times = student_availability & tutor_availability
        if not common_times:
            continue

        # Check mode compatibility
        if (student.preferred_mode != "either"
                and tutor.preferred_mode != "either"
                and student.preferred_mode != tutor.preferred_mode):
            continue

        # Calculate match score
        score = 0.0
        score += tutor_skill.skill_level.value * 0.3
        score += min(tutor.rating_as_tutor / 5.0, 1.0) * 0.3
        score += min(len(common_times) / 5, 1.0) * 0.2
        score += min(tutor.total_sessions_tutored / 20, 1.0) * 0.2

        matches.append({
            "tutor_id": tutor_id,
            "tutor_name": tutor.name,
            "skill_level": tutor_skill.skill_level.name,
            "rating": tutor.rating_as_tutor,
            "sessions_completed": tutor.total_sessions_tutored,
            "common_available_slots": len(common_times),
            "match_score": round(score, 2),
            "mode": tutor.preferred_mode,
        })

    matches.sort(key=lambda m: m["match_score"], reverse=True)
    return matches[:5]

def find_study_group(
    subject: str, course_code: str, max_size: int = 5
) -> list[dict]:
    """Find students interested in forming a study group."""
    interested = []
    for student in STUDENTS.values():
        for skill in student.skills:
            if skill.course_code == course_code and skill.wants_help:
                interested.append({
                    "student_id": student.student_id,
                    "name": student.name,
                    "skill_level": skill.skill_level.name,
                    "availability_slots": len(student.availability),
                })
                break

    interested.sort(key=lambda s: s["availability_slots"], reverse=True)
    return interested[:max_size]

Feedback and Quality Tracking

def submit_session_feedback(
    session_id: str,
    reviewer_id: str,
    rating: int,
    comment: str,
    was_helpful: bool,
) -> dict:
    session = None
    for s in SESSIONS:
        if s.session_id == session_id:
            session = s
            break
    if not session:
        return {"error": "Session not found"}

    feedback_entry = {
        "reviewer_id": reviewer_id,
        "rating": min(max(rating, 1), 5),
        "comment": comment,
        "was_helpful": was_helpful,
        "submitted_at": datetime.now().isoformat(),
    }
    session.feedback.append(feedback_entry)

    # Update tutor rating
    tutor = STUDENTS.get(session.tutor_id)
    if tutor:
        all_ratings = [
            fb["rating"] for s in SESSIONS
            if s.tutor_id == session.tutor_id
            for fb in s.feedback
        ]
        if all_ratings:
            tutor.rating_as_tutor = round(
                sum(all_ratings) / len(all_ratings), 2
            )

    return {"status": "Feedback submitted", "tutor_new_rating": tutor.rating_as_tutor if tutor else None}

Agent Assembly

from agents import Agent, function_tool, Runner
import json

@function_tool
def find_tutors(
    student_id: str, subject: str, course_code: str
) -> str:
    """Find matching tutors for a student in a specific subject."""
    matches = find_tutor_matches(student_id, subject, course_code)
    return json.dumps(matches) if matches else "No tutors available."

@function_tool
def find_group(subject: str, course_code: str) -> str:
    """Find students interested in a study group for a course."""
    group = find_study_group(subject, course_code)
    return json.dumps(group) if group else "No students available."

@function_tool
def submit_feedback(
    session_id: str,
    reviewer_id: str,
    rating: int,
    comment: str,
    was_helpful: bool,
) -> str:
    """Submit feedback after a tutoring session."""
    result = submit_session_feedback(
        session_id, reviewer_id, rating, comment, was_helpful
    )
    return json.dumps(result)

tutoring_agent = Agent(
    name="Peer Tutoring Coordinator",
    instructions="""You are a peer tutoring matching agent. Help
    students find tutors, join study groups, and provide feedback
    on sessions. When matching, explain why each tutor is a good
    fit. Encourage students to try tutoring subjects they excel
    in. After sessions, always ask for feedback. If a student
    reports a poor experience, escalate to program staff.""",
    tools=[find_tutors, find_group, submit_feedback],
)

FAQ

How does the agent prevent scheduling conflicts?

Before confirming a match, the agent checks both the tutor and tutee existing session schedule to avoid double-booking. It presents only mutually available time slots. If a popular tutor is overbooked, the agent suggests alternative tutors or waitlist options.

What happens when a tutor receives consistently low ratings?

The quality tracking system flags tutors whose rolling average drops below 3.0 out of 5. The agent stops recommending them for new matches and notifies the tutoring program coordinator who can offer coaching or remove them from the tutor pool. The system distinguishes between subject-specific and general ratings.

Can the agent handle group tutoring with multiple tutees?

Yes. The TutoringSession.tutee_ids field supports multiple tutees. The matching algorithm can assemble groups where all members need help with the same topic and share overlapping availability. The agent caps group size at the tutor preferred limit and the student preferred group size.

#AIAgents #EdTech #PeerTutoring #Python #StudentMatching #AgenticAI #LearnAI #AIEngineering