FAQ
Skeptical-engineer questions answered straight. If you have one that isn’t here, open an issue or ask in Discord and we’ll add it.
Should I use this?
Section titled “Should I use this?”Is it production-ready?
Section titled “Is it production-ready?”The framework runs 5,294 tests across 651 files on every PR; current main has 0 failures. The frontier benchmark passes at 100% across claude-sonnet-4-6, claude-haiku-4-5, gpt-4o-mini, and gemini-2.5-pro on the ra-full 35-task suite. Local-tier gemma4:e4b and cogito:14b hit 91-94% on the same suite — tied with gemini-2.5-flash and gpt-4o-mini.
Honest caveats:
- The framework requires Bun ≥ 1.0 — we use Bun’s native SQLite, subprocess, and HTTP APIs. Node.js support is on the roadmap but not shipped.
- We’re at v0.10.x — the API has been stable since 0.9.0 (no breaking changes), but we haven’t tagged 1.0 yet.
- Some advanced features (full multi-session memory transfer) are still being hardened — see “What’s not done yet” below.
If you need an HTTP-API-as-a-service or a hosted control plane, we don’t ship that. The framework is a TypeScript SDK.
Why Bun, not Node?
Section titled “Why Bun, not Node?”The framework leans hard on Bun-native APIs:
bun:sqlitefor the 4-layer memory store, calibration observations, and gateway session historyBun.spawnfor the sandboxedcode-executeand CLI tools- Bun’s HTTP server / fetch / streaming primitives for SSE endpoints
We could add a Node compatibility layer, but it’d duplicate ~30% of the code. Bun is also genuinely faster for the workloads agents do (concurrent IO, SQLite). Install Bun is one command.
Why Effect-TS?
Section titled “Why Effect-TS?”Three reasons that matter once you’re past hello-world:
- Typed error channels —
Effect.fail()returns a tagged error type. The compiler tells you which errors a function can produce. No more “what does this throw?” guessing. - Layer composition — every capability (memory, reasoning, guardrails, etc.) is an independent
Layeryou compose withLayer.mergeandLayer.provide. No singletons, no global state, every agent is its own runtime. - Dependency injection that survives hot-reload — services are looked up via
Tag, swappable per agent without touching call sites.
Cost: Effect has a learning curve. We provide an Effect-TS primer and 90% of users never touch raw Effect — they call .withProvider("anthropic").build() and run their agent.
What’s the catch with local models?
Section titled “What’s the catch with local models?”Local Ollama models (4B+) hit 91-94% on the same harness as paid frontier models — because of the framework, not despite it. Specifically:
- The Healing Pipeline recovers 86.7% of malformed tool calls (with +80 pp accuracy lift on FC-heavy tasks)
- The TextParseDriver handles models without native function-calling via XML / JSON / pseudo-code cascade
- The calibration system learns each model’s tool-call dialect after 5 runs
Catch: Local inference is slower (1-5 s/response on 14B vs 100 ms on a fast frontier API), and you need ~9 GB RAM for qwen3:14b / cogito:14b. The 4 GB gemma4:e4b is faster and still hits 94%.
If you only ever want one paid frontier model, you’re paying for capabilities (healing, calibration, dialect detection) you don’t strictly need — but you also pay nothing extra for them, so there’s no real downside.
How does it compare?
Section titled “How does it compare?”vs LangChain.js / LlamaIndex
Section titled “vs LangChain.js / LlamaIndex”LangChain is Python-first, dynamically typed, monolithic. Reactive Agents is TypeScript-native with zero any in framework code, modular by layer, and observable by design (every phase emits spans + EventBus events).
We ship a side-by-side migration guide — the API maps cleanly: ChatOpenAI → .withProvider("openai"), AgentExecutor → ReactiveAgent, BufferMemory → .withMemory(), callbacks → .withHook().
vs Vercel AI SDK
Section titled “vs Vercel AI SDK”Great for streaming + tool calling, but stops there. Reactive Agents adds 7 reasoning strategies (ReAct, Reflexion, Plan-Execute, Tree-of-Thought, Adaptive), persistent 4-tier memory, guardrails, verification, cost routing, and a 12-phase execution engine with full observability. Same TypeScript ergonomics; you can use both side-by-side if you already have AI SDK in production.
vs AutoGen / CrewAI
Section titled “vs AutoGen / CrewAI”Multi-agent frameworks without type safety, composable architecture, or model-adaptive intelligence. Reactive Agents ships A2A protocol (JSON-RPC + SSE for cross-agent calls), dynamic sub-agent spawning, and the healing pipeline that lifts local-model accuracy by +80pp. We see them as complementary — you can wrap a CrewAI agent as a Reactive Agents tool via agent-tool-adapter.
vs Building from scratch
Section titled “vs Building from scratch”You’d reinvent: provider adapters (6 LLM providers), guardrails, verification, semantic entropy, cost routing, A2A protocol, gateway + cron + webhooks, structured logging, OTLP tracing, the 12-phase engine, the healing pipeline, and 4 layers of memory. 651 test files keep it honest. Three months of work minimum, and you’d own the maintenance forever.
What’s not done yet?
Section titled “What’s not done yet?”We try to be honest about gaps. Things on the roadmap that aren’t shipped:
- Node.js support — Bun-only today.
- Multi-session memory transfer — episodic recall works within a process. Cross-process / cross-machine transfer is being designed.
- Sub-agent delegation effectiveness metrics — the test harness exists; we haven’t measured whether delegation beats inline execution on multi-step tasks.
v1.0tag — API is stable since 0.9; we’ll tag 1.0 once the items above ship and the calibration store has 1k+ runs across community models.
Track progress in the GitHub issues or the project state spec.
How do I…
Section titled “How do I…”…get help when I’m stuck?
Section titled “…get help when I’m stuck?”In order of speed:
- Troubleshooting guide — symptom → cause → fix for the most common failures
- Discord — community support, usually a response within hours
- GitHub Issues — for repeatable bugs / feature requests
- GitHub Discussions — for “how do I X” questions and design conversations
…keep an eye on releases?
Section titled “…keep an eye on releases?”Subscribe to the /rss.xml feed — built dynamically from the What’s New page. Or watch the GitHub releases.
…feed the docs to my AI coding tool?
Section titled “…feed the docs to my AI coding tool?”Three flat-text routes are auto-generated on every build:
/llms.txt— index file pointing at the others/llms-small.txt— abridged docs (~650 KB)/llms-full.txt— complete docs (~800 KB, 20k lines)
Cursor / Claude Code / Continue / etc. can ingest these directly so the assistant has full framework context.
…contribute?
Section titled “…contribute?”Read Contributing for the coding standards. Every page in the docs has an “Edit this page on GitHub” link at the bottom — if you spot a typo or unclear section, that’s the fastest path to a PR.