---
title: Architecture
description: The layered architecture of Reactive Agents.
---

import { FileTree, Aside } from '@astrojs/starlight/components';

Reactive Agents uses a layered, composable architecture built on Effect-TS.

<Aside type="tip" title="Mental model">
Every `.with*()` call adds a Layer. `build()` composes Layers into the **12-phase ExecutionEngine**. `agent.run()` flows a task through all 12 phases. No singletons, no global state — each agent is its own isolated runtime.
</Aside>

## Kernel structure

The reasoning kernel was reorganized in v0.10 to group code by capability. If you're contributing or reading the source, this is the layout:

<FileTree>
- packages/reasoning/src/kernel/
  - **capabilities/**
    - act/ tool execution, gating, parsing, healing pipeline
    - attend/ context utils + tool formatting
    - comprehend/ task intent
    - decide/ arbitrator (single-owner termination)
    - reason/ think · think-guards · stream parser
    - reflect/ loop detector · reactive observer · strategy evaluator
    - sense/ step utils
    - verify/ evidence grounding · quality utils · verifier
  - **loop/**
    - runner.ts main 12-phase orchestrator
    - react-kernel.ts ReAct strategy kernel
    - terminate.ts single-owner termination helper
    - auto-checkpoint.ts
    - output-assembly.ts
    - output-synthesis.ts
  - **state/** kernel-state · kernel-hooks · kernel-constants
  - **utils/** diagnostics · ICS coordinator · lane controller
</FileTree>

The single-owner termination invariant (M9 mechanism, 100% path coverage) is enforced by `kernel/loop/terminate.ts` plus a CI lint guard at `scripts/check-termination-paths.sh` — no path bypasses the arbitrator.

## Layer Stack

```
                    ┌─────────────────────────┐
                    │    ReactiveAgentBuilder  │  Public API
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │      ExecutionEngine     │  12-phase lifecycle
                    └────────────┬────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
    ┌────▼────┐            ┌─────▼─────┐           ┌─────▼─────┐
    │  Memory │            │ Reasoning │           │   Tools   │
    │ (L2)    │            │ (L3)      │           │ (L8)      │
    └────┬────┘            └─────┬─────┘           └─────┬─────┘
         │                       │                       │
    ┌────▼────────────────────────▼───────────────────────▼────┐
    │                    LLM Provider (L1.5)                    │
    └────────────────────────────┬─────────────────────────────┘
                                 │
    ┌────────────────────────────▼─────────────────────────────┐
    │           Core Services (L1)                             │
    │   EventBus  ·  AgentService  ·  TaskService              │
    └──────────────────────────────────────────────────────────┘
```

## Optional Layers

These can be enabled independently:

| Layer | Package | What It Does |
|-------|---------|-------------|
| Guardrails | `@reactive-agents/guardrails` | Input/output safety |
| Verification | `@reactive-agents/verification` | Fact-checking, semantic entropy |
| Cost | `@reactive-agents/cost` | Model routing, budget enforcement |
| Identity | `@reactive-agents/identity` | Agent certificates, RBAC |
| Observability | `@reactive-agents/observability` | Tracing, metrics, logging |
| Interaction | `@reactive-agents/interaction` | 5 autonomy modes |
| Orchestration | `@reactive-agents/orchestration` | Multi-agent workflows |
| Prompts | `@reactive-agents/prompts` | Template engine |
| A2A | `@reactive-agents/a2a` | Agent-to-Agent protocol (JSON-RPC, Agent Cards, SSE) |
| Gateway | `@reactive-agents/gateway` | Persistent autonomous harness: heartbeats, crons, webhooks, policy engine |
| Reactive Intelligence | `@reactive-agents/reactive-intelligence` | Entropy sensor, reactive controller, local learning, optional telemetry; integrates with kernel + EventBus |

## Dependency Graph

```
Core ← LLM Provider ← Memory
                     ← Reasoning
                     ← Tools

Core ← Guardrails (standalone)
     ← Verification (standalone)
     ← Cost (standalone)
     ← Identity (standalone)
     ← Observability (standalone)
     ← Interaction (needs EventBus)
     ← Orchestration (standalone)
     ← Prompts (standalone)
     ← A2A (needs Core + Tools)
     ← Gateway (needs Core EventBus)
```

## How Layers Compose

Every layer is an Effect `Layer` — a recipe for building a service. Layers compose through `Layer.merge` and `Layer.provide`:

```typescript
import { createRuntime } from "@reactive-agents/runtime";

// The runtime composes all enabled layers into a single Layer
const runtime = createRuntime({
  agentId: "my-agent",
  provider: "anthropic",
  enableGuardrails: true,
  enableReasoning: true,
  enableCostTracking: true,
});

// This Layer provides ALL services needed by the ExecutionEngine
```

This means:
- **No singletons** — Each agent gets its own service instances
- **No global state** — Everything is scoped to the Layer
- **Testable** — Swap any layer with a test implementation
- **Tree-shakeable** — Disabled layers aren't loaded
