Introduction

Reactive Agents is a composable TypeScript framework for building reliable LLM agents on a harness you fully control. It’s built on Effect-TS, so the runtime is type-safe, observable, and composable end to end.

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 repairs malformed tool calls before they fail, so the same code runs on a local 4B Ollama model and on Claude, GPT, or Gemini.

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

Transparent harness

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.

Reliable on local models

A 4-stage healing pipeline repairs malformed tool calls on the fly — deterministic string/type fixes instead of an LLM reprompt — so local Ollama models can run the same tool-calling loop as frontier APIs.

Typed structured output

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)

Durable by design

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)

Key Features

Composable Layer System

Every capability is an independent Effect Layer. Compose them like building blocks — declaratively with createAgent(config), or fluently with the builder:

Declarative

import { createAgent } from "reactive-agents";

const agent = await createAgent({
  name: "my-agent",            // required in the declarative config
  provider: "anthropic",       // required in the declarative config
  memory: {},          // Default memory tier (see Memory guide for enhanced + embeddings)
  reasoning: {},       // ReAct reasoning loop
  guardrails: {},      // Injection & PII detection
  costTracking: {},    // Budget enforcement
});

Builder

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.

Interaction Modes (standalone package)

@reactive-agents/interaction is an opt-in, standalone package that models five autonomy levels — autonomous, supervised, collaborative, consultative, and interrogative — with mode switching, checkpoints, and notifications as composable Effect services.

It is used directly, not through createAgent or the builder: createInteractionLayer() provides the InteractionManager service as an Effect layer you compose into your own program. See the interaction modes example in the Examples Catalog for the working pattern.

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

Quickstart Build your first agent in 5 minutes — provider key + 3 lines.

Installation Set up your project (Bun or Node.js 22.5+).

Architecture Understand the composable layer system.

Typed Structured Output Turn any agent into a typed extractor — new in v0.12.