How KidStory Meets Challenge Requirements (Track 2: Optimize)

Navigation: README | Diagram Architecture | How It Works | Database Schema | Challenge Requirements | Deployment

Track 2: Optimize (Existing Agents)

"Got an agent that works in a sandbox but struggles with the edge cases of the real world? This track is about treating AI quality as a rigorous engineering discipline."

KidStory is a production-deployed multi-agent system at ai.kidstory.app that has been optimized for real-world reliability through simulation testing, observability, and programmatic instruction refinement.

Development Journey & Contest Eligibility

For judges: Full transparent timeline with commit evidence. The submitted system — a 9-agent ADK-based production platform — was architected and built entirely during the contest period. A pre-contest experiment informed the problem domain, but shares no code, architecture, or infrastructure with the submission.

What Is Being Submitted

The submitted project is the KidStory ADK multi-agent system — a production platform built on Google Agent Development Kit v1.0, deployed on Google Cloud Run, with 9 specialized agents, RAG with private Firestore data, OpenTelemetry observability, and a simulation test suite. This system did not exist before the contest period. It was designed, architected, and built from April 22, 2026 onward.

Pre-Contest Context (March 2026)

Before the contest opened, the developer ran a personal experiment with Google's Gemini API to explore whether AI could generate children's stories. That experiment:

Was 2 raw generateContent API calls — no agents, no ADK, no architecture
Had no quiz system, no credits, no RAG, no observability, no tests
Was English only, with no multilingual support
Was a throwaway script, not a deployable product
Shares no code, no architecture, and no infrastructure with the submitted system

This is the equivalent of a developer Googling how an API works before deciding to build a real product. It informed the problem space — but the product itself was built during the contest.

What Was Built During the Contest Period (April 22 – June 12, 2026)

The entire KidStory submission was created during the contest period:

Date	Milestone	Evidence
April 22, 2026	Contest opens — development of the ADK system begins	Contest Period starts
April 25, 2026	Received $500 Google Cloud credits — full commitment to build	Commit on credits day
April 25 – June 12, 2026	Complete system built: ADK architecture, 9 agents, RAG, observability, simulation, 21 languages, production deployment	Git history
June 12, 2026	Submission deadline	—

Everything in the submitted system was created during the contest:

ADK architecture — LlmAgent, FunctionTool, InMemoryRunner for all agents (did not exist before April 22)
9 specialized agents — SafetyGuardian, StoryWriter, Illustrator, Narrator, QuizMaster, QuizFeedback, LearningAdvisor, ParentInsights, StoryAdaptation
Agent Simulation — scripts/simulate.ts, 22 test scenarios with real Gemini calls
Agent Observability — OpenTelemetry + Cloud Trace + in-app Pipeline Dashboard
Instruction optimization — simulation-driven refinement cycle for all 3 text agents
RAG with private data — LearningAdvisor, ParentInsights, StoryAdaptation reading Firestore per-user history
Adaptive learning loop — quiz scores → StoryAdaptation → calibrated story prompt → StoryWriter
21 languages — including Tetum, Burmese, Lao, Khmer with language-aware TTS
Credit system — Free/Pro tiers, server-side enforcement via Firebase Admin SDK
Production deployment — Google Cloud Run at ai.kidstory.app
Real users — 80+ registered users, 150+ AI-generated books created during the contest

Why Track 2

Track 2 ("Optimize Existing Agents") describes exactly what happened: an early Gemini experiment that "works in a sandbox" was replaced by a properly architected ADK system and then stress-tested for production:

Agent Simulation — 22 scenarios to stress-test multi-step reasoning
Agent Observability — Cloud Trace to debug stalled logic (QuizMaster Tetum failure, tool-call loops)
Agent Optimizer — simulation-driven instruction refinement cycle
Production hardening — retry logic, fallback types, rate-limit handling, Firestore caching

This is exactly the Track 2 spirit: "treating AI quality as a rigorous engineering discipline."

Mandatory Technologies ✅

Requirement	Implementation
Intelligence: Gemini API	Gemini 2.5 on Vertex AI — all 9 agents
Orchestration: ADK or supported framework	Google Agent Development Kit (ADK) v1.0 — `LlmAgent`, `FunctionTool`, `InMemoryRunner`
Infrastructure: Google Cloud	Deployed on Cloud Run, Firestore, Cloud Storage, Cloud TTS

What We Optimized

1. Agent Simulation (Stress-testing multi-step reasoning)

Tool: scripts/simulate.ts — 22 test scenarios with real Gemini calls

Agent	Scenarios	What's tested
SafetyGuardian	11	Over-blocking edge cases ("fighting for friendship" = safe), under-blocking, keyword bypass
StoryWriter	4	Language compliance, page count accuracy, imagePrompt always in English
QuizMaster	7	Question type rotation, answer-in-options constraint, deduplication, multilingual

Edge cases discovered and fixed:

SafetyGuardian over-blocked "fighting for friendship" → refined instruction to distinguish context
QuizMaster fill_blank fails in Tetum/rare languages → added fallback to multiple_choice
StoryWriter sometimes ignored page count → strengthened instruction with "exactly N pages"

2. Agent Observability (Debugging stalled logic)

Tool: OpenTelemetry + Google Cloud Trace

Every agent call produces a span with:

agent.name, agent.model, agent.language
agent.duration_ms — latency tracking
agent.success — pass/fail per call
agent.blocked (SafetyGuardian) — false positive tracking
Full LLM request/response in ADK spans (gcp.vertex.agent.llm_request)

Real debugging example:

QuizMaster in Tetum: traced a stuck quiz to the model responding with plain text instead of calling submit_fill_blank
Visible in Cloud Trace: the call_llm span showed the response was just "Ida ne'e mak quiz ida ba ó!" (text, no tool call)
Fix: added fallback retry with multiple_choice type when fill_blank exhausts retries

Approach: Simulation-driven instruction iteration

Run simulate.ts → identify failures
    │
    ▼
Analyze failure reason (over-block? wrong type? wrong language?)
    │
    ▼
Refine system instruction in agent code
    │
    ▼
Re-run simulate.ts → verify fix doesn't break other scenarios
    │
    ▼
Deploy → monitor via Cloud Trace

Specific optimizations made:

SafetyGuardian: Added explicit "SAFE to approve" examples for edge cases
StoryWriter: Added CHARACTER CONSISTENCY RULES and IMAGE PROMPT SAFETY RULES
QuizMaster (+ LearningAdvisor, ParentInsights, StoryAdaptation): Added includeContents: "none" to prevent infinite tool-call loops
QuizMaster: Added pre-generated encouragement/correction fields to eliminate feedback LLM calls (200ms vs 4-6s)

Judging Criteria Alignment

Technical Implementation

Multi-Agent Collaboration

KidStory is not a single agent with tools — it is a network of 9 specialized agents that actively collaborate, with results from one agent feeding into another:

Child submits prompt
        │
        ▼
[1] SafetyGuardian ──blocked──▶ reject (0 credits charged)
        │ approved
        ▼
[2] StoryWriter
        │ title + pages + imagePrompts
        ▼
[3a] IllustratorAgent ◀─── parallel ───▶ [3b] NarratorAgent
     (Gemini Flash Image)                  (Gemini TTS, story language)
     watercolor per page                   audio per page
        │                                       │
        └──────────────┬────────────────────────┘
                       ▼
              Complete storybook saved
                       │
        ┌──────────────┴────────────────────────┐
        ▼                                        ▼
[4] QuizMasterAgent                   [5a] LearningAdvisorAgent
    5 questions in parallel                RAG: reads last 10 quiz
    (Promise.all)                          scores from Firestore
    pre-generated feedback                 → recommends difficulty
    (200ms vs 4–6s)                        + themes for next story
                                      [5b] ParentInsightsAgent
                                           RAG: reads stories + scores
                                           → child progress report
                                           → optional email to parent
                                      [5c] StoryAdaptationAgent  ← NEW
                                           RAG: reads last 3 quizzes
                                           → adapted story prompt
                                           → vocabulary level + page count
                                           → CTA: "Start This Story"
                                           cached in Firestore

Key collaboration patterns:

Sequential gating — SafetyGuardian must approve before StoryWriter runs; credits only deducted after gate passes
Parallel execution — Illustrator and Narrator receive StoryWriter's output simultaneously; QuizMaster generates all 5 questions concurrently via Promise.all
RAG handoff — LearningAdvisor, ParentInsights, and StoryAdaptation query Firestore at runtime for private per-user data (quiz history, story list) to ground their responses
Adaptive loop — StoryAdaptation closes the learning loop: quiz scores → adapted prompt → StoryWriter → new story at the right level

See the Multi-Agent Collaboration Graph → for the full visual diagram.

RAG with Private Firestore Data

Two agents use Retrieval-Augmented Generation (RAG) over private, per-user data stored in Firestore — not static knowledge, but real usage history retrieved at query time:

LearningAdvisorAgent (/api/learning-recommendation):

Firestore query: users/{uid}/stories  (last 100, filtered to those with lastQuizScore set, take 10)
        │
        ▼
Fetched at runtime → injected into LLM context
        │
        ▼
Gemini analyzes score trend (improving? plateau? struggling?)
        │
        ▼
Returns: { difficulty: "easier|same|harder", themes: [...], encouragement, readingInsight }

Grounded in actual quiz performance — not a generic recommendation
Cached: if latestQuizDate unchanged, returns previous response without a new Gemini call (0 tokens)

ParentInsightsAgent (/api/parent-insights):

Firestore queries:
  • users/{uid}/stories         (full story list with titles + prompts)
  • users/{uid}/stories         (filtered to those with quiz scores)
        │
        ▼
Both collections fetched → injected into LLM context
        │
        ▼
Gemini synthesizes: topics enjoyed, quiz highlights, encouragement tips
        │
        ▼
Returns parent-readable summary → optionally emailed via Nodemailer

Grounded in the child's actual reading and quiz history — personalized per child
Demonstrates the challenge criterion: "Strategically employ RAG with private data to enhance agent knowledge"

StoryAdaptationAgent (/api/adapt-story):

Firestore query: users/{uid}/stories (last 30, filtered to quiz-completed, take 3)
        │
        ▼
Quiz records fetched → avgScore + trend computed → injected into LLM context
        │
        ▼
Gemini generates: adaptedPrompt + vocabularyLevel + pageCount + focusTheme
        │
        ▼
Saved to: users/{uid}/adaptations (cache)
        │
        ▼
Shown as: AdaptedStoryCard in Parent Insights → AI Story tab
        │
        └── "Start This Story" → /create?prompt=<adaptedPrompt>

Grounded in the child's actual quiz performance trend (not generic recommendations)
Closes the adaptive learning loop: quiz results drive the next story prompt, which feeds StoryWriter
Cache: returns immediately if no new quiz since last adaptation (0 tokens)

Summary of ADK agents with Gemini 2.5 on Vertex AI (9 agents total):

Multi-agent orchestration: SafetyGuardian → StoryWriter → Illustrator + Narrator (parallel)
RAG with private Firestore data (LearningAdvisor, ParentInsights, StoryAdaptation)
Adaptive learning loop: QuizMaster → StoryAdaptation → StoryWriter
OpenTelemetry observability with Cloud Trace + Agent Observability Dashboard
Simulation test suite (22 scenarios)
Retry logic with exponential backoff + type fallback
Deployed on Cloud Run with production traffic

Business Case

Problem: Children's screen time is passive; parents want educational engagement
Solution: AI-powered interactive storytelling that makes reading fun and measurable
Market: EdTech for kids (ages 5-12) — global market worth $30B+
Differentiation: Multi-agent system (not just a chatbot), 21 languages, character photos, quiz-based learning
Revenue model: Freemium with actual pricing — Free tier (30 credits/month, ~6 stories) and Pro tier (150 credits/$4.99/month, ~30 stories). Story = 5 credits, Quiz = 1 credit. Server-side enforcement via Firebase Admin SDK. Upgrade page →
Physical product: Print Book pre-order (Coming Soon) — $9 USD per printed book, delivery to Dili, Timor-Leste (1-2 weeks)
Unit economics: ~$0.14 per story generation cost (Gemini API), tracked via dev-only cost logger
Traction: Deployed at ai.kidstory.app, real users

Innovation & Creativity

Voice-first input for kids who can't type well
Character reference photos for personalized illustrations
Pre-generated quiz feedback (200ms fast path vs 4-6s LLM path)
Credit/freemium system with server-side enforcement — credits deducted only after safety check passes, preventing abuse
Adaptive learning loop — quiz scores automatically drive the next story's vocabulary level, page count, and prompt (StoryAdaptation agent)
Agent Observability Dashboard — real-time view of all 9 agents, call counts, avg scores, and last-used timestamps; shown in Parent Insights → Pipeline tab
Parent Insights redesign — two-column sidebar layout with 4 tabs (Progress, AI Story, Pipeline, Report), matching dark/light theme as main dashboard
Story Map — visual world exploration from story keywords
Character Collection — gallery extracted from imagePrompt metadata
3D page flip animation for immersive reading
Print Book pre-order (Coming Soon) — physical printed book from AI-generated content ($9 USD, delivery to Dili, Timor-Leste)
Cost tracking with per-story breakdown (~$0.14/story) — dev-only observability for token usage optimization
Caching strategy: 0 Gemini tokens on repeat visits (Firestore-based cache for all 3 RAG agents)

Demo and Presentation

Live demo at ai.kidstory.app
Full documentation in docs.kidstory.app/
Agent documentation with flow diagrams, observability spans, and simulation test cases

Key Differentiators for Track 2

Real production deployment — not a sandbox prototype
Documented optimization journey — before/after instruction refinements with measurable results
Multi-language edge cases — optimized for 21 languages including Tetum (low-resource)
Cost optimization — caching eliminates repeat Gemini calls, pre-generated feedback avoids LLM round-trips
Graceful degradation — quiz fallback types, retry with backoff, null-question filtering
Closed adaptive learning loop — StoryAdaptation agent converts quiz performance directly into a calibrated story prompt, closing the feedback loop between reading and learning
Agent Observability Dashboard — parents can see the full agent pipeline with live call counts and performance metrics; demonstrates Track 2's "Agent Observability" criterion in a user-facing UI
ADK tool-loop fix documented — discovered and fixed a Gemini re-invocation bug in ADK FunctionTool.execute (returning { ...args, status: "submitted" } prevents infinite loops); applied to all 3 ADK agents

How KidStory Meets Challenge Requirements (Track 2: Optimize) ​

Track 2: Optimize (Existing Agents) ​

Development Journey & Contest Eligibility ​

What Is Being Submitted ​

Pre-Contest Context (March 2026) ​

What Was Built During the Contest Period (April 22 – June 12, 2026) ​

Why Track 2 ​

Mandatory Technologies ✅ ​

What We Optimized ​

1. Agent Simulation (Stress-testing multi-step reasoning) ​

2. Agent Observability (Debugging stalled logic) ​

3. Agent Optimizer (Programmatic instruction refinement) ​

Judging Criteria Alignment ​

Technical Implementation ​

Multi-Agent Collaboration ​

RAG with Private Firestore Data ​

Business Case ​

Innovation & Creativity ​

Demo and Presentation ​

Key Differentiators for Track 2 ​