AWS Builder Center

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_at  epoch 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  version  attribute for optimistic concurrency. This keeps the session state machine consistent under retries and double-clicks.
  • Data minimization: only  SessionRecord  fields 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_answer  or the full rubric before answering.
Reliability and cost
  • A  RequestBudget  that 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_template  or  demo_fallback ), and the UI shows  Demo fallback — no live agent execution  when 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

  1. 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.
  1. 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.
  1. 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.
  1. 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.
  1. 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 1  to  Stone 5 , and a test fails if the frontend preset drifts from the seed file.
  1. 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.
  1. 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  LIVE  label.
  • 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 backend
uv sync --frozen
$env:IC_USE_STUB_MODEL = "true"
uv run uvicorn app.main:create_app --factory --port 8000
Then  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.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article