Agent Documentation — Storybook for Kids

Most agents use Google ADK v1.0 (LlmAgent + FunctionTool) with Gemini 2.5 Pro on Vertex AI, traced via OpenTelemetry (lib/observability/tracer.ts).

Exception: Illustrator and Narrator bypass ADK entirely — they call GCP services (generateImage, synthesizeSpeech) directly as plain async functions. This eliminates ~3–5s of LLM routing overhead per page since their tool selection is 100% deterministic.

---

Agents

Agent	Doc	File	Triggered by
SafetyGuardian	safety-guardian.md	lib/agents/safetyGuardian.ts	Every story generation
StoryWriter	story-writer.md	lib/agents/storyWriter.ts	After safety approved
Illustrator	illustrator.md	lib/agents/illustratorAgent.ts	Per-page image generation
Narrator	narrator.md	lib/agents/narratorAgent.ts	Per-page audio narration
QuizMaster	quiz-master.md	lib/agents/quizMasterAgent.ts	Quiz generation (×5 parallel)
QuizFeedback	quiz-feedback.md	lib/agents/quizMasterAgent.ts	Quiz answer feedback
LearningAdvisor	learning-advisor.md	lib/agents/learningAgent.ts	Dashboard recommendation (on load)
ParentInsights	parent-insights.md	lib/agents/parentInsightsAgent.ts	Parent Insights page + email report
StoryAdaptation	story-adaptation.md	lib/agents/adaptationAgent.ts	Parent Insights → AI Story tab (on load)

---

Pipeline flow

For the full step-by-step pipeline with timing, credit logic, and caching details, see How KidStory Works.

Summary:

[SafetyGuardian] → [StoryWriter] → [Illustrator × N] + [Narrator × N] → [Cover] → Firestore
                                                                             │
                               [QuizMaster × 5 parallel] + [QuizFeedback]  ← child taps Quiz
                                                                             │
         Dashboard: [LearningAdvisor]  ← RAG from quiz history
Parent Insights: [ParentInsights] + [StoryAdaptation]  ← RAG from quiz history

---

Simulation

npm run simulate

Runs 22 scenarios across SafetyGuardian, StoryWriter, and QuizMaster. See scripts/simulate.ts.