@reactive-agents/react

React hooks + components for Reactive Agents agentic UI — runs, durable interactions, inbox, generative UI, devtools.

Stability: experimental. The wire contract is versioned and additive-only, but signatures may change in a minor release. Pin a version for production use.

React bindings for AI agents, built on the headless @reactive-agents/ui-core engine — so streams are resumable, human-in-the-loop is durable (survives reloads), and generative UI is registry-safe. All hooks are thin reactivity wrappers over ui-core; the protocol, reconnect, and state logic live there.

Install

bun add @reactive-agents/react
# or: npm install @reactive-agents/react

Quick start

Server (Next.js App Router):

// app/api/agent/route.ts
import { ReactiveAgents, AgentStream } from "reactive-agents";

export async function POST(req: Request) {
  const { prompt } = await req.json();
  const agent = await ReactiveAgents.create().withProvider("anthropic").withTools().build();
  return AgentStream.toSSE(agent.runStream(prompt));
}

Client:

import { useRun } from "@reactive-agents/react";

function Chat() {
  const { state, run } = useRun({ endpoint: "/api/agent" });
  return (
    <div>
      <button onClick={() => run("Explain quantum entanglement")}>Ask</button>
      <p style={{ whiteSpace: "pre-wrap" }}>{state.text}</p>
      {state.status === "streaming" && <span>●</span>}
      {state.error && <p style={{ color: "red" }}>{state.error}</p>}
    </div>
  );
}

Hooks

| Hook | Purpose | |------|---------| | useRun({ endpoint, objectMode?, auto?, attach? }) | Core run hook — returns { state, run, cancel, reattach }. state is ui-core's RunState (status, text, output, object, cost, pendingInteraction, pendingApproval, …). | | useResumableRun({ endpoint, runId, cursor? }) | Reattach to a durable run on mount and replay from a cursor (survives reloads). | | useInteractions({ interactionEndpoint }) | respond(runId, interactionId, value) for durable request_user_input — returns { respond, pending, error }. | | useTaskInbox({ endpoint, pollMs? }) | Poll the durable-run inbox — { runs, loading, error, refresh }. | | useRunCost / useRunSteps | Live cost and tool/step trace derived from the run stream. | | useAgentStream / useAgent | Streaming and one-shot classics (now rewired onto useRun). |

Components

Headless-first (unstyled primitives with data-* attributes + render-prop/callback escape hatches); an optional styled reference layer ships from @reactive-agents/react/styles.

| Component | Purpose | |-----------|---------| | AgentPrompt, ChoiceCard, ApprovalGate | Render a durable interaction / approval and answer it. | | TaskInbox | Email-like list of async agent jobs. | | CostMeter, StepTimeline | Live cost + tool/step trace. | | AgentSurface (+ uiTreeSchema, ComponentRegistry) | Safe generative UI — renders a registry-constrained node tree; hallucinated components are unrepresentable. | | AgentDevtools | Floating dev overlay: runs, live event stream, cost burn, replay. |

Testing

Record a real run once, replay it in CI with zero tokens (via @reactive-agents/ui-core/testing):

import { mockAgentEndpoint, recordRunFixture } from "@reactive-agents/ui-core/testing";

const fixture = await recordRunFixture(agentStream);
// pass mockAgentEndpoint(fixture) as the fetchImpl to any hook

Part of Reactive Agents

Part of Reactive Agents — the TypeScript AI-agent framework on Effect-TS. See the Web Integration guide, the Agentic UI Core reference, and the full docs.