Apex Coding AcademyExplore the curriculum
TIER 2 · PRODUCTION CAPSTONE

Evidence-Grounded Agent Swarm

Build a resumable coordinator with specialist agents, typed tools, hybrid retrieval, citations, permission budgets, deterministic model doubles, and regression evals.

Download starter bundle (.zip)Back to course

System architecture

  1. A coordinator owns a durable state machine and delegates bounded tasks to specialists.
  2. Tool adapters enforce schemas, deadlines, idempotency, and per-run permission budgets.
  3. Postgres plus pgvector stores versioned chunks; lexical and vector results are reranked.
  4. Every claim retains source, chunk, retrieval version, and confidence provenance.
  5. A deterministic evaluation runner gates prompts, retrieval, and model releases.

Acceptance requirements

  • Represent all transitions as validated events with optimistic concurrency control.
  • Prevent agents from expanding their own tool permissions or delegation depth.
  • Return abstention when evidence coverage or citation support falls below policy.
  • Checkpoint after every tool effect and resume without repeating completed effects.
  • Evaluate answer support, citation precision, task success, latency, and cost.
  • Quarantine poisoned or malformed documents without corrupting the active index.

Required failure drills

  • Crash the coordinator between a tool response and checkpoint persistence.
  • Inject a prompt-injection string inside a retrieved document; tool authority must not change.
  • Remove the strongest evidence chunk; the system must abstain or lower confidence.
  • Race two workers on one state version; exactly one transition may commit.

Submission deliverables

  • Coordinator, two specialists, typed tool gateway, retrieval service, and eval runner
  • Versioned corpus fixtures with expected citations and adversarial documents
  • Postgres/pgvector and Redis Compose stack with repeatable migrations
  • State-transition, permission-budget, recovery, retrieval, and evaluation tests
  • Release scorecard and rollback decision with trace evidence

Automated verification

$ npm ci$ npm test$ docker compose up --build --wait$ npm run migrate$ npm run eval

100-point professional rubric

State and delegation correctnessTransition and concurrency suites pass.25 pts
Grounding and citationsSupport and citation thresholds pass the golden set.25 pts
Tool safetyPermission and injection adversarial cases fail closed.20 pts
Recovery and isolationCrash and poison drills preserve exact state.15 pts
Evaluation operationsVersioned scorecard gates a reproducible release.15 pts

Starter repository contents

OPERATIONS.mddb/001.sqldocker-compose.ymlpackage.jsonsrc/coordinator.mjssrc/eval.mjssrc/permission-budget.mjssrc/retrieval.mjssrc/state-machine.mjstest/safety.test.mjs