Installation

Bun recommended — Node.js 22.5+ also supported

Bun ≥1.0.0 gives optimal performance (native SQLite, subprocess, HTTP). Node.js 22.5+ is fully supported via @reactive-agents/runtime-shim — use npm install reactive-agents or npx tsx if you prefer the Node.js ecosystem. Install Bun: curl -fsSL https://bun.sh/install | bash.

From zero to running agent

1. Install the meta-package.

   # Bun (recommended)
   bun add reactive-agents
   
   # Node.js 22.5+
   npm install reactive-agents

2. Set at least one provider key in .env (or skip if you’re going local).

   echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
   # or OPENAI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, XAI_API_KEY, LITELLM_API_KEY
   
   # No key? Run fully local with Ollama instead:
   ollama pull qwen3:4b

   Going local, swap the provider in step 3: .withProvider("ollama").withModel("qwen3:4b") — no key required. See the Local Models guide.

3. Build your first agent — three lines is enough.

   import { ReactiveAgents } from "reactive-agents";
   const agent = await ReactiveAgents.create().withProvider("anthropic").build();
   console.log((await agent.run("Hello")).output);

4. Run it.

   # Bun
   bun run src/agent.ts
   
   # Node.js (requires tsx)
   npx tsx src/agent.ts

Simple Install

The easiest way to get started is with the reactive-agents meta-package, which bundles everything:

bun

bun add reactive-agents

npm

npm install reactive-agents

pnpm

pnpm add reactive-agents

yarn

yarn add reactive-agents

Effect dependency

effect ships as a dependency of reactive-agents and is installed automatically. When you write hooks, tools, or tests, import helpers explicitly — e.g. import { Effect } from "effect" — then use Effect.succeed, Effect.fail, Effect.gen, Effect.runPromise, etc. See the Effect-TS primer for a cheat sheet. Add effect to your app’s package.json only if you import from it outside reactive-agents’ bundled usage.

Then import from a single entry point:

import { ReactiveAgents } from "reactive-agents";

Modular Install

The framework is modular — install only the packages you need:

Foundation (required)

Package	Description
@reactive-agents/core	EventBus, AgentService, TaskService, canonical types
@reactive-agents/runtime	12-phase ExecutionEngine, ReactiveAgentBuilder, createRuntime()
@reactive-agents/llm-provider	LLM adapters: Anthropic, OpenAI, Gemini, Groq, xAI, Ollama, LiteLLM (40+), Test

Cognition (recommended)

Package	Description
@reactive-agents/reasoning	7 strategies (ReAct, Blueprint, Plan-Execute, Reflexion, ToT, Adaptive, Code-Action) + composable kernel
@reactive-agents/memory	4-layer memory (working, semantic, episodic, procedural) on bun:sqlite
@reactive-agents/tools	Tool registry, sandbox, MCP client, healing pipeline
@reactive-agents/prompts	Template engine, version-controlled prompt library
@reactive-agents/reactive-intelligence	Entropy sensor, reactive controller, learning engine, telemetry

Production safety

Package	Description
@reactive-agents/guardrails	Injection, PII, toxicity detection, kill switch
@reactive-agents/verification	Semantic entropy, fact decomposition, NLI hallucination detection
@reactive-agents/cost	Multi-factor complexity routing, budget enforcement, semantic cache
@reactive-agents/identity	Ed25519 agent certificates, RBAC, delegation, audit
@reactive-agents/diagnose	Output-leak detection (system-prompt, api-key, credential, internal)
@reactive-agents/health	Health checks and readiness probes

Observability

Package	Description
@reactive-agents/observability	OTLP tracing, MetricsCollector, structured logging
@reactive-agents/trace	Trace event types and OTLP exporters

New in v0.11

Package	Description
@reactive-agents/runtime-shim	Cross-runtime primitives (Bun + Node.js 22.5+) — Database, spawn, serve
@reactive-agents/compose	Harness composition + 6 killswitches (maxIterations, budgetLimit, etc.)
@reactive-agents/replay	Deterministic trace replay: record runs, replay without LLM calls
@reactive-agents/observe	Zero-config OpenTelemetry/OpenInference tracing to any OTLP backend

Composition & multi-agent

Package	Description
@reactive-agents/a2a	Agent-to-Agent protocol: Agent Cards, JSON-RPC 2.0, SSE streaming
@reactive-agents/gateway	Persistent autonomous harness: heartbeats, crons, webhooks, policy engine
@reactive-agents/channels	Per-sender access control + chat-mode session storage for the gateway
@reactive-agents/interaction	5 autonomy modes, checkpoints, preference learning

Evaluation & testing

Package	Description
@reactive-agents/eval	Evaluation suites, LLM-as-judge scoring, EvalStore (SQLite)
@reactive-agents/testing	Mock LLMService / ToolService / EventBus, assertion helpers (dev)

Frontend integration

Package	Description
@reactive-agents/react	React 18+ hooks: useAgentStream, useAgent
@reactive-agents/vue	Vue 3 composables: useAgentStream, useAgent with reactive refs
@reactive-agents/svelte	Svelte 4/5 stores: createAgentStream, createAgent

Developer tooling

Package	Description
@reactive-agents/cortex	Cortex Studio (Beacon, Thalamus, Lab, living skills) — bunx @reactive-agents/cortex

bun

bun add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider

npm

npm install @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider

pnpm

pnpm add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider

yarn

yarn add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider

Environment Variables

Create a .env file:

# LLM Provider — set at least one
ANTHROPIC_API_KEY=sk-ant-...        # Anthropic Claude
OPENAI_API_KEY=sk-...               # OpenAI GPT-4o
GOOGLE_API_KEY=...                  # Google Gemini
GROQ_API_KEY=gsk_...                # Groq
XAI_API_KEY=xai-...                 # xAI Grok
LITELLM_API_KEY=...                 # Optional — LiteLLM proxy auth when required

# Tools (optional)
TAVILY_API_KEY=tvly-...             # Enables built-in web search tool

# Embeddings (for enhanced / `"2"` memory tier — vector semantic search)
EMBEDDING_PROVIDER=openai           # "openai" | "ollama"
EMBEDDING_MODEL=text-embedding-3-small

# Tuning (optional)
LLM_DEFAULT_MODEL=claude-sonnet-4-6
LLM_DEFAULT_TEMPERATURE=0.7
LLM_MAX_RETRIES=3
LLM_TIMEOUT_MS=30000

TypeScript Configuration

Reactive Agents requires TypeScript 5.5+ with strict mode. This is the minimum config:

tsconfig.json (required)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}

Two stricter flags are recommended for new projects — but they tighten checks across your whole codebase, so enabling them in an existing project may require code changes beyond Reactive Agents:

tsconfig.json (recommended additions)

{
  "compilerOptions": {
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  }
}

Where to next

Quickstart — first agent in 5 minutes Provider key + 3 lines of code. The shortest path to a working agent.

Your First Agent (full walkthrough) Step-by-step: memory, reasoning, guardrails, hooks. Build out the minimum into a real one.

Choosing a Stack Pick provider · model tier · memory · reasoning strategy with a decision tree.

API Cheatsheet One-page reference of every important builder method, runtime call, and event.