---
title: Introduction
description: >-
  A composable TypeScript framework for building reliable LLM agents on a
  harness you fully control — the same code from a local 4B model to frontier
  APIs, on a typed, observable 12-phase engine.
sidebar:
  order: 1
---

import { Aside, Card, CardGrid, LinkCard } from '@astrojs/starlight/components';

Reactive Agents is a composable TypeScript framework for building reliable LLM agents on a harness you fully control. It's built on [Effect-TS](https://effect.website), so the runtime is type-safe, observable, and composable end to end.

<Aside type="tip" title="At a glance">
Every prompt, tool call, and reasoning step is a **typed event you can subscribe to** — no hidden prompts, no proprietary loop. A self-healing tool layer recovers **86.7% of tool-call errors**, so the *same code* runs on a local 4B Ollama model and on Claude, GPT, or Gemini.
</Aside>

## The Problem

Building production AI agents is hard:

- **No type safety** — Most agent frameworks are dynamically typed. Errors surface at runtime, often in production.
- **Monolithic** — You get everything or nothing; opting into memory but not guardrails is rarely supported.
- **Opaque** — Agent decisions are black boxes, which makes them hard to debug, audit, or steer.
- **Unsafe** — Prompt injection, PII leaks, and runaway costs are afterthoughts.

## The Solution

Reactive Agents solves each of these with a layered, composable architecture:

| Problem | Solution |
|---------|----------|
| No type safety | Effect-TS schemas validate every boundary |
| Monolithic | Layer system — enable only what you need |
| Opaque | 12-phase execution engine with lifecycle hooks |
| Unsafe | Built-in guardrails, verification, and cost controls |

## What makes it different

<CardGrid>
  <Card title="Transparent harness" icon="magnifier">
    Every one of the 12 phases emits typed events with `before` / `after` / `on-error` hooks. System prompts are readable templates, not buried strings. Raw provider clients ship standalone — skip the harness entirely if you want.
  </Card>
  <Card title="Reliable on local models" icon="setting">
    A 4-stage healing pipeline recovers malformed tool calls on the fly (**+80pp accuracy**, 10× cheaper than an LLM reprompt). Local Ollama models reach **91–94%** on the same suite where frontier APIs reach 100%.
  </Card>
  <Card title="Typed structured output" icon="seti:typescript">
    Attach a Zod / Valibot / ArkType / Effect schema and read a fully-typed `result.object` — streaming field-by-field if you want. No prompt engineering, no manual parsing. *(New in v0.12)*
  </Card>
  <Card title="Durable by design" icon="random">
    Opt a run into a durable store and resume it from its last checkpoint after a crash, restart, or pause — across process boundaries. *(New in v0.12)*
  </Card>
</CardGrid>

## Key Features

### Composable Layer System

Every capability is an independent Effect Layer. Compose them like building blocks:

```typescript
const agent = await ReactiveAgents.create()
  .withMemory()          // Default memory tier (see Memory guide for enhanced + embeddings)
  .withReasoning()       // ReAct reasoning loop
  .withGuardrails()      // Injection & PII detection
  .withCostTracking()    // Budget enforcement
  .build();
```

### 12-Phase Execution Engine

Every agent task flows through a deterministic lifecycle:

1. **Bootstrap** — Load memory context
2. **Guardrail** — Safety checks on input
3. **Cost Route** — Select optimal model tier
4. **Strategy Select** — Choose reasoning strategy
5. **Think** — LLM completion (one or more iterations)
6. **Act** — Tool execution
7. **Observe** — Append tool results to context
8. **Verify** — Fact-check output (entropy, decomposition, NLI)
9. **Memory Flush** — Persist session, episodic, and procedural memories
10. **Cost Track** — Record spend against budget
11. **Audit** — Emit audit events (tokens, cost, strategy, duration)
12. **Complete** — Return final result with metadata

Each phase supports `before`, `after`, and `on-error` lifecycle hooks.

### 5 Interaction Modes

Agents dynamically adjust their autonomy level:

- **Autonomous** — Full self-direction
- **Supervised** — Periodic checkpoints
- **Collaborative** — Back-and-forth with the user
- **Consultative** — Ask before acting
- **Interrogative** — Gather information first

Mode transitions happen automatically based on confidence thresholds, cost, and user activity.

## Who Is This For?

- **TypeScript developers** building AI-powered applications
- **Teams** that need observable, auditable agent behavior
- **Projects** that require fine-grained control over agent capabilities
- **Anyone** tired of agent frameworks that feel like magic boxes

## Next Steps

<CardGrid>
  <LinkCard title="Quickstart" description="Build your first agent in 5 minutes — provider key + 3 lines." href="../quickstart/" />
  <LinkCard title="Installation" description="Set up your project (Bun or Node.js 22.5+)." href="../installation/" />
  <LinkCard title="Architecture" description="Understand the composable layer system." href="../../concepts/architecture/" />
  <LinkCard title="Typed Structured Output" description="Turn any agent into a typed extractor — new in v0.12." href="../structured-output/" />
</CardGrid>
