KidTok Classroom

Turn any question a child asks into a narrated educational cartoon in minutes.
Architecture Chart

Inspiration

KidTok started as a real product: an app where parents generate short, age-appropriate AI lessons for kids aged 5–8. Running it in production taught me a hard lesson: generating good children's content isn't one AI call; it's a pipeline of specialized steps (scripting, visual planning, safety gating, narration). The bottleneck is never the model, but the prompts. Historically, I've been manually reviewing traces and hand-tuning prompts after every batch of lessons.

That was the spark for this hackathon: What if the pipeline reviewed its own traces and tuned its own prompts in a closed loop?

Furthermore, generic content fails to engage children over the long term. Education needs to feel personal. So we took it a step further: what if we could merge active self-improvement with deep child personalization—injecting a child's name, age, specific interests (like dinosaurs, space, or baking), and visual art styles (like claymation or watercolors) directly into the agent reasoning flow? An agent system that doesn't just generate cartoons, but observes its own success, tailors its stories directly to each child, and ships a better version of itself for the next episode.

What it does

A parent logs in and selects or creates a Child Profile (e.g., Zosia, age 5, interests: dinosaurs, volcanoes, and cookies, preferred style: crayon sketch). This profile overrides standard settings. Six agents, orchestrated by Google's Agent Development Kit (ADK), then take over:

ScriptAgent
Reads the child's profile, addresses the child directly by name (as both a welcoming hook and a joyful summary), and dynamically weaves their interests into the educational story (e.g., explaining volcanic magma flows using cookie-baking analogies) while enforcing strict child-safety checks.
ScenePlannerAgent
Fetches the latest scene-prompt template from Arize Phoenix prompt management via MCP, plans one consistent cartoon visual per scene, and overrides the visual prompt tokens with the child's selected art style (crayon sketch, claymation, retro cartoon, or watercolor).
SceneImageAgent
Sanitizes each prompt, generates illustrations with Gemini image generation on Agent Platform (Vertex), runs them through a visual safety gate, and uploads them to Cloud Storage.
NarrationAgent
Cleans the narration text and voices it with Google Cloud TTS or ElevenLabs (child-friendly voice, gentle pace).
AssemblyAgent
Compiles the manifest: images, audio, captions, Ken Burns–style animations, and overlays a loopable, gentle background melody bed (synchronized with play/pause and capped at an ultra-soft -0.08 bed volume to avoid overpowering the narrator) into a playable episode in Supabase.
QualityReviewerAgent
The self-improvement loop. The entire pipeline is instrumented with OpenInference/OpenTelemetry exporting to Arize Phoenix. After assembly, this agent calls the Phoenix MCP server at runtime (get-spans) to read its own telemetry, evaluates latency, retries, alignment, and critically scores the Personalization Fit of the episode. When it detects a weakness, it publishes an improved scene-prompt via upsert-prompt—which the very next episode picks up automatically.

The 🌱 AI Self-Improvement Portal

To make this loop transparent, we added a dedicated page /self-improvement (accessible via the profile dropdown) that features two targeted dashboards:

Parent View: Friendly, high-level metrics (e.g., 98.4% Episode Success Rate, Clarity at "Excellent") and an interactive AI Self-Correction Log demonstrating how parent ratings are consumed by the Quality Reviewer under the hood.
Developer View: Displays raw telemetry diagnostic indicators (average latency, prompt retries, active safety filters), hosts the Active Prompt-Steering Panel (saving developer instructions to local storage to steer subsequent reviews), and displays a Prompt Version History Timeline. It uses a custom Longest Common Subsequence (LCS) word-diff engine to highlight additions in green and removals in red directly in the browser.

How I built it

Agents: Six LlmAgent definitions on the official @google/adk (TypeScript), run through ADK's InMemoryRunner, with one central ClassroomOrchestrator—sub-agents never call each other directly.
Models: Gemini for reasoning/scripting and Gemini image generation, both exclusively via Agent Platform.
Observability + Self-Improvement: OpenInference tracing into Arize Phoenix. We engineered a Synchronous Telemetry Bootstrap (instrumentation.ts) inside our Express gateway to capture clean, perfectly nested tracing hierarchies from cold-start.
Custom LCS Diff Engine: Built a client-side word-by-word comparison engine in React and TypeScript to render precise prompt diffs on the Self-Improvement page.
Infra: Cloud Run (scale-to-zero), Supabase Postgres for episode state, manifests, child profiles, and indexing, Cloud Storage for media, Secret Manager for Phoenix credentials, Cloud TTS and ElevenLabs for narration, and an audio mixer engine for loopable background music beds.
Frontend: React + Vite + TypeScript, polling a REST API with live pipeline status, a pre-seeded/customizable glassmorphic Child Profiles Carousel, and the premium Dual-View Self-Improvement Portal.

Challenges I ran into

Making the MCP integration real, not decorative: Getting an agent to consume its own spans through MCP, act on them, and close the loop from telemetry → critique → prompt version → next episode required careful schema work.
Balancing depth and simplicity in telemetry visualization: Developers want to see raw spans and prompt-steering panels, while parents want clear, encouraging indicators of how the AI is safe-guarding and refining lessons. Designing the dual-audience portal with custom parent logs and native LCS word-diffs solved this beautifully.
Ensuring continuous trace hierarchies: Tracing asynchronous multi-agent setups can result in orphaned spans. Extracting cold-start bootstrapping into instrumentation.ts was essential to ensure 100% trace cohesion in Phoenix.
Cohesive prompt engineering across agent boundaries: Ensuring that the ScriptAgent addresses the child by name and injects interests, while the ScenePlanner forces a matching visual aesthetic (like watercolor or claymation) without leaking or degrading instructions, required rigid schema boundaries.

What I learned

ADK's agent abstractions held up: Spanning six agents with a deterministic orchestrator was less code than my production queue-based pipeline in another product.
MCP is the missing link: Phoenix as a passive dashboard is nice; Phoenix as a tool the agent calls changes what the system is. Traces aren't just post-mortem logs—they are a first-class memory and runtime database for self-improving agents.
Self-improvement doesn't need RL: Prompt versioning combined with trace-aware evaluation gets you a meaningful quality flywheel today.

What's next for KidTok Classroom

Parallel scene generation, richer animation (image-to-video via Omni), scaling child profiles to support classroom-level group cohorts, and promoting the reviewer from prompt-tuner to full evaluator running automated Phoenix experiments across episode batches.