The Invisible Classroom: Turning Everyday Objects into Safe, Supervised Lessons with Strands Agents, Amazon Bedrock and Kiro
A hackathon build story: multi-agent orchestration where the safety checks are code, not prompts
The idea
Millions of children learn in places without worksheets, tablets or a trained teacher nearby. What they usually do have is a parent, caregiver or community volunteer, and a handful of everyday things: stones, leaves, bottle caps, spoons.
The Invisible Classroom turns those objects into a short, hands-on lesson. A Facilitator (the adult) picks an age band (6-8, 9-10 or 11-12), a subject (counting and arithmetic, or introductory measurement) and types the objects they have. A team of specialist agents built with the Strands Agents SDK then produces a 5 to 10 minute adventure with three graded activities, a baseline question and an end check. The child answers one challenge at a time, gets supportive feedback, and the next activity adapts if a misconception shows up.
A few constraints shaped everything else:
- Adult-mediated. There are no child accounts, and the app never asks for a name, birthday, address, school or email.
- Grounded. A lesson may only use objects the Facilitator listed.
- Safe. Hazardous activities are blocked before a child sees anything.
- Honest. This is a prototype. It makes no claim that it improves learning, and mastery numbers are labeled "provisional".
Architecture at a glance
The system is a modular monolith: one FastAPI backend and a React/TypeScript single-page app. I chose a monolith on purpose. For a hackathon-sized product it keeps deployment, debugging and tracing simple, and the module boundaries (API, services, agents, adapters) leave room to split later.
The agents
Agent | Job |
|---|---|
Orchestrator | Coordinates the specialists under hard budgets for depth, calls, tokens and time |
Environment | Turns the object list into a safe inventory with affordances (what each object can be used for) |
Curriculum | Picks a learning objective and three graded challenge intents for the age band |
Storytelling | Writes the three-activity adventure with short instructions, rubric and hints |
Assessment | Gives rubric-based feedback and scaffolds, but only when deterministic grading cannot decide |
Each specialist is a Strands agent with a narrow system prompt, no tools and a typed output. The orchestrator calls them in sequence and validates every handoff against a versioned Pydantic contract before moving on.
The part I care about most: gates are code, not models
Model output is untrusted. So after generation, a set of Validation Gates written in ordinary Python decides whether a lesson reaches a child:
- Schema: strict Pydantic v2 models with enums, length limits and schema versions.
- Grounding: every object mentioned must be in the approved inventory.
- Safety: a taxonomy that blocks fire, blades, electricity, chemicals, ingestion, heights, strangers and dangerous water.
- Age vocabulary and readability checks.
- PII redaction for anything that gets logged.
One failing activity rejects the whole lesson. The system retries up to twice, then falls back to a curated, clearly labeled safe template. Arithmetic is graded deterministically first. The Assessment specialist is only called when there is no deterministic verdict, which makes grading cheaper, faster and more predictable.
AWS services and how they were used
Amazon Bedrock, through the Strands Agents SDK
All four specialists call foundation models on Amazon Bedrock through the Strands
BedrockModel and structured output. The model ID and Region come from environment variables ( IC_MODEL_ID , IC_AWS_REGION ), so switching models is a configuration change, not a code change. Credentials come from the standard AWS credential chain, and in deployment that means an IAM role. No secrets live in the repository.A thin adapter wraps the model call with a per-call timeout and bounded retries. The adapter has a second implementation, a deterministic stub, selected with
IC_USE_STUB_MODEL=true . That one design choice made the rest of the project testable without an AWS account.Amazon DynamoDB
Session state lives in a table named
InvisibleClassroomSessions , partitioned on session_id . How it is used:- TTL: an
expires_atepoch attribute lets DynamoDB expire sessions after 24 hours. Because TTL deletion is asynchronous, the application also rejects expired reads immediately, so the app's check is the authoritative gate.
- Conditional writes: session creation and state transitions use condition expressions with a
versionattribute for optimistic concurrency. This keeps the session state machine consistent under retries and double-clicks.
- Data minimization: only
SessionRecordfields are serialized, so a forbidden attribute (such as a child's name) cannot reach the table by accident.
- Capability tokens: the client gets a high-entropy bearer token, and only its hash is stored.
For local development and tests, an in-memory repository implements the same interface, and
boto3 is imported lazily so the DynamoDB path is optional.Hosting, observability and cost controls (design intent)
The design targets containers on AWS App Runner or Amazon ECS on Fargate, a static frontend on Amazon S3 with CloudFront, and redacted logs and spans in Amazon CloudWatch with least-privilege IAM (Bedrock invoke, the one DynamoDB table, CloudWatch writes). In this repository, the application emits redacted diagnostic records (correlation ID, stage status, latency, error category, usage estimate) and the Bedrock and DynamoDB adapters are implemented. I did not include infrastructure-as-code or a recorded cloud deployment, so I treat the hosting layer as designed rather than delivered.
Best practices built in
Security and privacy
- Capability-based access with hashed tokens, CORS allowlist, request size limits, rate limiting, concurrency limits and idempotency keys on mutations.
- Treating object descriptions and learner answers as untrusted input, with scoped prompts and no tools for the specialists (no browser, shell or external writes).
- Escaped React rendering and no raw HTML for model text, to reduce XSS risk.
- Logs that exclude prompts, reasoning, credentials and learner free text.
- Error responses with a stable code, a safe message and a correlation ID, never a raw exception.
- Learner view never receives
expected_answeror the full rubric before answering.
Reliability and cost
- A
RequestBudgetthat caps orchestration depth (2), specialist calls (8), tokens (20,000) and deadlines (45 s generation, 15 s assessment).
- Bounded retries, then a labeled fallback instead of an open-ended loop.
- A state machine with legal transitions only, enforced by conditional writes.
Engineering discipline
- Dependency injection for model, store and clock, so tests are deterministic.
- Property-based tests (Hypothesis on the backend, fast-check on the frontend) alongside unit tests.
- An evaluation harness of 69 synthetic cases: 36 lessons, 10 scripted-misconception scaffold cases and 23 adversarial prompt-injection and compromised-output cases.
- CI that runs Ruff, mypy, tests, a gitleaks secret scan,
pip-audit, a CycloneDX SBOM and the build, with pinned lockfiles.
- Playwright end-to-end tests plus axe accessibility checks, keyboard-only navigation and a 320 px reflow check.
Honest labeling
- Every lesson carries a
source(generated,safe_templateordemo_fallback), and the UI showsDemo fallback — no live agent executionwhen pre-recorded data is playing.
- Results are tagged measured or illustrative. Stub-model latency and cost figures are explicitly marked illustrative.
How Kiro shaped the build
I used Kiro's spec-driven workflow. Requirements were written in EARS format (for example, "IF an answer is ambiguous, THE SYSTEM SHALL request clarification instead of confidently marking it incorrect"), a technical design followed, and then a task list in which each task cites requirement IDs, has a testable completion condition and lists its dependencies. Priorities were kept strict: P0 for the MVP, P1 (photo input, Hindi) and P2 as stretch items that never touch the critical path.
Release gates G1 to G5 turned "are we done?" into a checklist with evidence: real Strands specialist calls visible in a sanitized trace, gates passing, no critical security findings, mobile and keyboard flows tested, and live versus fallback clearly distinguished.
What went well
- Gates as code. Because safety and grounding are plain Python, they can be unit tested, property tested and attacked with adversarial cases. In the stubbed evaluation suite, the 23 adversarial cases produced zero gate bypasses.
- The stub model. Running the real Orchestrator and gates against a deterministic stub meant the full flow, including E2E tests, ran offline and repeatably, with no AWS bill.
- Typed handoffs. Versioned contracts between agents made failures local and easy to diagnose, rather than producing vague bad lessons.
- Spec-first with Kiro. Requirement IDs threaded through design, tasks and tests, so traceability was a by-product rather than extra paperwork.
- A demo that cannot embarrass you. Demo_Mode runs five visible stages (understand objects, choose objective, create story, assess answer, adapt next activity) and falls back to labeled seed data if the live path fails or takes more than 10 seconds.
What I learned
- Don't ask the model to police itself. Prompts reduce risk, but only deterministic checks give a guarantee you can test. Keep the model for creativity and the code for rules.
- Determinism first, model second. Exact arithmetic doesn't need an LLM. Reserving the Assessment specialist for ambiguous answers cut calls and made behavior more predictable.
- Budgets are a feature. Limits on depth, calls, tokens and time protect cost and latency, and force a decision about what happens when they run out.
- Labels matter as much as code. It is easy to blur live, stubbed and pre-recorded behavior in a demo. Building the distinction into the data model (
source) and the UI kept the project honest.
- Test data can fight your own rules. My first seed used five identical "stone" lines, and the normalizer's case-insensitive deduplication collapsed them to one. The seed now uses
Stone 1toStone 5, and a test fails if the frontend preset drifts from the seed file.
- Pin your SDK assumptions. The design says to check agent and structured-output signatures against the installed, pinned Strands version rather than trusting memory or examples.
- Be clear about what you haven't proven. The live Bedrock path was not exercised by the automated tests, so I don't report live latency, cost or quality. Pass rates measured on a stub show the gates behave as coded, not that a real model writes safe lessons. Release gate G1 stays open until a live run is recorded.
Limits and what's next
This is a facilitator-supervised aid, not a diagnostic or validated assessment tool. The baseline and end-of-lesson check is for observation only and carries a not-validated warning. Manual testing with assistive technologies has not been done yet.
Next steps:
- Record and publish a live Bedrock run to close gate G1, with latency and cost reported under a separate
LIVElabel.
- Add infrastructure as code (AWS CDK or Terraform) and deploy to App Runner or ECS Fargate with CloudWatch dashboards and budget alerts.
- Add human-reviewed adversarial testing alongside the automated cases.
- Explore the stretch features: photo input of objects and Hindi support, with the same gates applied.
Try it
The repository runs end to end on the stub model with no AWS account:
cd backenduv sync --frozen$env:IC_USE_STUB_MODEL = "true"uv run uvicorn app.main:create_app --factory --port 8000Then
POST /api/v1/demo/session to create the Demo_Mode session and read its five stages from the events endpoint. To go live, unset IC_USE_STUB_MODEL , provide AWS credentials through the standard chain, and set IC_MODEL_ID and IC_AWS_REGION for your account.
All seed content is synthetic and contains no learner data. This prototype makes no certification or learning-efficacy claims.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article