---
title: Installation
description: How to install and configure Reactive Agents.
sidebar:
  order: 4
---

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

<Aside type="tip" title="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`.
</Aside>

## From zero to running agent

<ol class="ra-steps">

<li>

**Install the meta-package.**

```bash
# Bun (recommended)
bun add reactive-agents

# Node.js 22.5+
npm install reactive-agents
```

</li>

<li>

**Set at least one provider key** in `.env` (or skip if you're going local).

```bash
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env
# or OPENAI_API_KEY, GOOGLE_API_KEY, GROQ_API_KEY, XAI_API_KEY, LITELLM_API_KEY
```

</li>

<li>

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

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

</li>

<li>

**Run it.**

```bash
# Bun
bun run src/agent.ts

# Node.js (requires tsx)
npx tsx src/agent.ts
```

</li>

</ol>

## Simple Install

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

<Tabs syncKey="pkg">
  <TabItem label="bun">
  ```bash
  bun add reactive-agents
  ```
  </TabItem>
  <TabItem label="npm">
  ```bash
  npm install reactive-agents
  ```
  </TabItem>
  <TabItem label="pnpm">
  ```bash
  pnpm add reactive-agents
  ```
  </TabItem>
  <TabItem label="yarn">
  ```bash
  yarn add reactive-agents
  ```
  </TabItem>
</Tabs>

:::note[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](/concepts/effect-ts/) 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:

```typescript
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`          | 27-signal 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/orchestration` | Sequential, parallel, pipeline, map-reduce workflows                      |
| `@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/scenarios`     | Pre-built test scenarios + scenario builder                               |
| `@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` |

<Tabs syncKey="pkg">
  <TabItem label="bun">
  ```bash
  bun add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider
  ```
  </TabItem>
  <TabItem label="npm">
  ```bash
  npm install @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider
  ```
  </TabItem>
  <TabItem label="pnpm">
  ```bash
  pnpm add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider
  ```
  </TabItem>
  <TabItem label="yarn">
  ```bash
  yarn add @reactive-agents/core @reactive-agents/runtime @reactive-agents/llm-provider
  ```
  </TabItem>
</Tabs>

## Environment Variables

Create a `.env` file:

```bash
# 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:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  }
}
```

## Where to next

<CardGrid>
  <LinkCard
    title="Quickstart — first agent in 5 minutes"
    description="Provider key + 3 lines of code. The shortest path to a working agent."
    href="../quickstart/"
  />
  <LinkCard
    title="Your First Agent (full walkthrough)"
    description="Step-by-step: memory, reasoning, guardrails, hooks. Build out the minimum into a real one."
    href="../your-first-agent/"
  />
  <LinkCard
    title="Choosing a Stack"
    description="Pick provider · model tier · memory · reasoning strategy with a decision tree."
    href="../choosing-a-stack/"
  />
  <LinkCard
    title="API Cheatsheet"
    description="One-page reference of every important builder method, runtime call, and event."
    href="/reference/cheatsheet/"
  />
</CardGrid>
