Quickstart

Prerequisites

• Bun ≥1.0.0 (curl -fsSL https://bun.sh/install | bash)
• An API key from Anthropic, Google Gemini, OpenAI, or LiteLLM — or run a local model with Ollama (no key needed)

The fastest path through this guide is the rax workflow (Rax = Reactive Agents Executable).

In a hurry?

The minimum viable agent is 3 lines. Skip to step 3 if you’ve already got Bun + an API key.

1. Create a Project

Using the CLI:

bunx rax init my-agent-app --template standard
cd my-agent-app
bun install

rax init --template standard scaffolds:

• Directorymy-agent-app/

  • Directorysrc/

    • agent.ts Your first agent — runnable with bun run src/agent.ts
    • Directorytools/ Drop custom tools here; auto-discovered when wired into builder

      • …
  • .env Provider API keys (gitignored by default)
  • package.json reactive-agents dependency + bun run agent script
  • tsconfig.json strict mode + Bun-aware module resolution
  • README.md

Or manually:

mkdir my-agent-app && cd my-agent-app
bun init -y
bun add reactive-agents

Effect dependency

effect ships as a dependency of reactive-agents and is installed automatically. For hooks and custom tools, import helpers explicitly (import { Effect } from "effect") and use Effect.succeed, Effect.fail, etc. — see the Effect-TS primer. Add effect to your app only if you rely on it outside the framework’s re-exports.

2. Set Up Environment

Set at least one provider key. Pick whichever you have access to:

# Pick at least one
echo 'ANTHROPIC_API_KEY=sk-ant-...' > .env  # Recommended for first agent
echo 'OPENAI_API_KEY=sk-...'        >> .env
echo 'GOOGLE_API_KEY=...'           >> .env

# Or run fully local — no key needed
ollama pull qwen3:4b

Optional keys for built-in tools (web search, etc.) — add them later when you call .withTools():

echo 'TAVILY_API_KEY=tvly-...' >> .env   # Web search (Tavily backend)
echo 'SERPER_API_KEY=...'      >> .env   # Web search (Serper.dev backend)

3. Build an Agent

Create src/agent.ts:

src/agent.ts

import { ReactiveAgents } from "reactive-agents";

const agent = await ReactiveAgents.create()
  .withProvider("anthropic")
  .build();

const result = await agent.run("What are the three laws of thermodynamics?");
console.log(result.output);

That’s the minimum. .withProvider() picks the default model for the provider automatically (claude-sonnet-4-6 for Anthropic). Set ANTHROPIC_API_KEY in your environment before running.

To pin a specific model or add a name:

src/agent.ts

const agent = await ReactiveAgents.create()
  .withName("my-first-agent")
  .withProvider("anthropic")
  .withModel("claude-sonnet-4-6")
  .build();

const result = await agent.run("What are the three laws of thermodynamics?");
console.log("Output:", result.output);
console.log("Duration:", result.metadata.duration, "ms");
console.log("Steps:", result.metadata.stepsCount);

Resource cleanup

Always dispose agents that use MCP servers or other subprocess-based tools — otherwise the process will hang on open pipes. Use await using for automatic cleanup, or runOnce() for one-shot scripts. See Resource Management for all three patterns.

4. Run It

bun run src/agent.ts

5. Add Capabilities

The canonical composition path is a HarnessProfile preset — lean(), balanced(), or intelligent(). Presets compose the registry’s default-on capability set so you don’t pile up redundant .withX() calls.

src/agent.ts

import { ReactiveAgents, HarnessProfile } from "reactive-agents";

const agent = await ReactiveAgents.create()
  .withName("research-agent")
  .withProvider("anthropic")
  .withModel("claude-sonnet-4-6")
  .withProfile(HarnessProfile.balanced())   // memory + RI + verifier + strategy switching
  .build();

Pick the preset that matches the workload:

• HarnessProfile.lean() — model + nothing else. Latency- and cost-sensitive paths; benchmark ablations.
• HarnessProfile.balanced() — today’s production defaults (memory + reactive intelligence + verifier + strategy switching).
• HarnessProfile.intelligent() — balanced + skill persistence for cross-session compounding learning.

Override one capability after the preset — order matters; later calls win:

const agent = await ReactiveAgents.create()
  .withName("research-agent")
  .withProvider("anthropic")
  .withModel("claude-sonnet-4-6")
  .withProfile(HarnessProfile.balanced())
  .withMemory({ tier: "enhanced" })          // upgrade memory to vector embeddings
  .compose((h) => h.before("act", logFn))    // canonical chokepoint composition
  .build();

Individual .withX() methods still work for backward compatibility, but most are now @deprecated aliases for either a HarnessProfile preset or a .compose(...) chokepoint. Check the JSDoc on a method to see which preset / compose primitive it routes to.

What’s Next?

Scaffold a New Project create-reactive-agent scaffolds a runnable agent in seconds — pick template, provider, and package manager.

OpenTelemetry Tracing Export spans from every agent run to Jaeger, Grafana Tempo, Langfuse, or any OTLP backend.

Your First Agent Deeper walkthrough — memory, reasoning, guardrails, and lifecycle hooks step by step.

Common Builder Stacks Copy-paste recipes for tools, streaming, multi-agent, gateway, and Agent-as-data.

API Cheatsheet The 80% of the API on one page — every important method, runtime call, and event tag.

Choosing a Stack Pick provider, model tier, memory, and reasoning strategy in 2 minutes.

Browse 30+ Examples Runnable across foundations, tools, multi-agent, gateway, streaming, and more.

Troubleshooting Symptom → cause → fix reference for the most common failures.