A reference implementation of a multi-agent AI system built on agentic-loop engineering principles:
Perceive → Plan → Act → Observe → Reflect → Adapt. The loop is an explicit, inspectable state machine — not a hidden prompt chain — with bounded autonomy, self-verification, durable checkpointing, and full trace replay.
Watch an objective flow through the full agentic loop in real time — no install, no API keys, no sign-up.
Live demo status: 100% client-side TypeScript port with a deterministic mock provider — always online on Vercel. The Python
core/engine runs offline with the same loop semantics (24 tests, 99% coverage).
Built by Devayan Mandal — AI / ML Engineer.
| Live agentic loop | Multi-agent orchestration |
|---|---|
 |  |
| System architecture + engineering rigor |
|---|
 |
| Path | What it is |
|---|---|
core/ | The Python reference engine — the agentic loop, agents, tool registry, memory, model router, observability. 24 tests, 99% coverage. Runs offline, no API keys. |
web-demo/ | A Next.js live demo (aarop.vercel.app) that animates the full agentic loop in the browser. |
docs/AAROP_Case_Study.pdf | A polished 4-page case study (problem → architecture → results → ADRs). |
core/docs/ARCHITECTURE.md | C4 diagrams, production reference stack, and 5 ADRs. |
core/docs/PROJECT_SPEC.md | The full chief-architect-level system specification. |
PERCEIVE → PLAN → ACT → OBSERVE → REFLECT ──accept──► DONE
▲ │
└──────────── ADAPT ◄──────reject──┘ (budget exhausted → ESCALATE)
| Phase | Responsibility |
|---|---|
| Perceive | Normalize input + retrieve relevant context / memory (RAG) |
| Plan | Build a cost-aware hierarchical task graph |
| Act | Invoke schema-validated, sandboxed tools / sub-agents |
| Observe | Capture structured results + detect anomalies |
| Reflect | Critic verifies output against acceptance criteria |
| Adapt | Replan / retry with backoff / escalate to a human |
Every phase transition emits a structured trace event, so any run is fully reconstructable and replayable. Every run respects step / cost / time budgets and escalates instead of looping forever.
aarop/
├── core/ # Python reference engine (runs offline, 99% tested)
│ ├── src/aarop/
│ │ ├── core/loop.py # agentic loop state machine + Budget guardrails
│ │ ├── agents/agents.py # Planner · Actor · Verifier (critic)
│ │ ├── tools/registry.py # schema-validated tools, scopes, circuit breaker
│ │ ├── memory/store.py # working / episodic / semantic memory + RAG
│ │ ├── routing/ # cost-aware model router
│ │ └── observability/ # structured tracing + replay
│ ├── examples/run_demo.py
│ ├── tests/test_loop.py
│ └── docs/ # ARCHITECTURE.md, PROJECT_SPEC.md
├── web-demo/ # Next.js 14 live demo (Vercel)
│ ├── app/
│ ├── lib/aarop.ts # TS port + node:test helpers
│ ├── e2e/ # Playwright Chromium smokes
│ └── public/favicon.svg
├── docs/
│ ├── AAROP_Case_Study.pdf
│ └── screenshots/
├── SECURITY.md
├── LICENSE
└── README.md
Core engine (Python):
cd core
pip install -e ".[dev]"
python examples/run_demo.py --objective "calculate 21*2 + 8" --verbose
pytest --cov=aarop # 24 passed · 99% coverageLive demo (Next.js):
cd web-demo
npm ci
npm test# node:test helpers (calculator, planner, loop)
npm run typecheck
npm run dev # http://localhost:3000- Explicit loop state machine — observable, replayable, crash-recoverable
- Bounded autonomy — step / cost / time budgets with human escalation
- Self-verification — a critic agent gates every result before commit
- Resilient tooling — schema-validated, permission-scoped, retries + circuit breaker + audit log
- Cost-aware model routing — cloud + self-hosted, pluggable
- Observability — structured trace per run (OpenTelemetry-shaped)
- 99% test coverage on core orchestration; CI across Python 3.10–3.12, plus web unit tests,
tsc --noEmit, and Playwright smokes
See core/docs/ARCHITECTURE.md for C4 diagrams, the production reference stack (Temporal, FastAPI, pgvector, vLLM, Kubernetes, OpenTelemetry), and 5 Architecture Decision Records.
The web-demo/ ports the exact loop logic to TypeScript and runs 100% client-side with a deterministic mock provider — instant, free, and always online. Deployed on Vercel: aarop.vercel.app. See web-demo/README.md for deploy steps.
Threat model for both surfaces: SECURITY.md.
- Pluggable real LLM provider (OpenAI / Anthropic / self-hosted vLLM)
- Persistent memory backend (pgvector / Qdrant) + cross-encoder reranker
- Durable workflow execution via Temporal
- OpenTelemetry exporter + Grafana dashboards
- "Bring your own API key" toggle in the live demo
See CONTRIBUTING.md. Issues and PRs welcome.
MIT © 2026 Devayan Mandal — see LICENSE.