QuizFeedback Agent

File	lib/agents/quizMasterAgent.ts (runQuizFeedbackAgent)
Triggered by	app/api/live-quiz/route.ts (action: "feedback")
Model	gemini-2.5-pro (Vertex AI) — LLM path only

---

What it does

Delivers spoken feedback after a child answers a quiz question. Almost always uses the fast path — the encouragement/correction text was pre-written by QuizMaster, so this agent just converts it to speech via TTS with no LLM call needed.

---

Two paths

Fast path (~200ms) — used in production

When textToSpeak is provided in the request:

1. Skip Gemini entirely
2. Call Google Cloud TTS directly on the pre-written text
3. Return base64 WAV audio

The textToSpeak comes from the encouragement or correction fields already generated by QuizMaster.

LLM path (~4–6s) — fallback only

When no textToSpeak is provided:

1. Call Gemini with context: page text, question, child's answer, correct answer, and whether it was correct
2. Agent calls submit_feedback with 1–2 sentences of feedback
3. Feedback text ends with a sound effect tag in brackets: [sparkle], [cheer], [tada], [drumroll], [oops], [boing]
4. Sound effect tag is extracted and mapped to a sound file
5. Remaining text is sent to TTS

---

Tools (LLM path only)

Tool	Parameters
submit_feedback	text: string — 1–2 sentences ending with [sound effect]

---

Sound effects

Tag	Mapped to	When used
[sparkle]	/sounds/correct.mp3	Correct answer
[cheer]	/sounds/correct.mp3	Correct answer
[tada]	/sounds/correct.mp3	Correct answer
[drumroll]	/sounds/correct.mp3	Correct answer
[oops]	/sounds/wrong.mp3	Wrong answer
[boing]	/sounds/wrong.mp3	Wrong answer

---

Flow

Child submits answer
    │
    ▼
Is answer correct? → set encouragement / correction text
    │
    ▼
POST /api/live-quiz { action: "feedback", textToSpeak: "..." }
    │
    ├── textToSpeak provided? (fast path)
    │       YES → TTS directly → base64 audio returned (~200ms)
    │
    └── NO (LLM path)
            │
            ▼
        QuizFeedback LLM call
            │
            └── submit_feedback({ text: "Great job! [sparkle]" })
                    │
                    ▼
            extract [sound effect] → play sound
            remaining text → TTS → base64 audio returned

---

Input / Output

// Input
{
  pageText: string;       // Story context
  question: string;       // The quiz question
  userAnswer: string;     // What the child answered
  correctAnswer: string;
  isCorrect: boolean;
  language?: string;      // default: "en"
  textToSpeak?: string;   // Fast path: pre-generated text to TTS directly
}

// Output
{
  text: string;           // Feedback text (sound effect tag removed)
  audioData?: string;     // base64 WAV "data:audio/wav;base64,..."
  soundEffect?: string;   // e.g. "sparkle", "oops"
}

---

Agent design note

The QuizFeedback LlmAgent does not set includeContents: "none" (unlike QuizMaster). It is instantiated fresh per call so there is no session history to accumulate.

---

Observability span

Span name: agent/QuizFeedback

Attribute	Example value
agent.name	QuizFeedback
agent.model	gemini-2.5-pro
agent.language	en
agent.isCorrect	true
agent.has_sound_effect	true
agent.feedback_length	42
agent.duration_ms	180