@reactive-agents/interaction

Interaction modes and human-in-the-loop primitives for the Reactive Agents framework. v0.10.3

Five autonomy modes, configurable checkpoints, approval gates, escalation rules, and a preference learner that adapts mode selection over time. Designed for agents that occasionally need human judgment — without forcing every run to be supervised.

Installation

bun add @reactive-agents/interaction

Or via the umbrella:

bun add reactive-agents

The 5 Modes

| Mode | Autonomy | When it activates | | --------------- | ------------------------------ | ---------------------------------- | | autonomous | Full — no interruptions | High confidence, routine tasks | | supervised | Periodic checkpoints | Moderate confidence | | collaborative | Human decides key steps | Complex or ambiguous tasks | | consultative | Human approves before acting | High-cost or risky operations | | interrogative | Human provides all direction | Information gathering only |

Modes transition automatically based on ModeTransitionRules and EscalationConditions — an autonomous agent can escalate to consultative when entropy spikes or estimated cost crosses a threshold, then de-escalate when confidence recovers.

Quick Example

import { ReactiveAgents } from "reactive-agents";

const agent = await ReactiveAgents.create()
  .withName("assistant")
  .withProvider("anthropic", { model: "claude-sonnet-4-20250514" })
  .withInteraction({
    defaultMode: "supervised",
    onCheckpoint: async (ctx) => {
      console.log("Agent wants to:", ctx.proposedAction);
      const ok = await askHuman(ctx);
      return { approved: ok };
    },
    escalation: [
      { type: "cost-threshold", thresholdUsd: 0.50, toMode: "consultative" },
      { type: "low-confidence", threshold: 0.4, toMode: "collaborative" },
    ],
  })
  .build();

Direct Service Usage

import { Effect } from "effect";
import {
  InteractionManager,
  InteractionManagerLive,
  CheckpointService,
  ModeSwitcher,
} from "@reactive-agents/interaction";

const program = Effect.gen(function* () {
  const interaction = yield* InteractionManager;
  const switcher = yield* ModeSwitcher;

  yield* switcher.switchTo("collaborative", { reason: "user-requested" });
  const decision = yield* interaction.requestApproval({
    action: "delete-file",
    path: "/tmp/x",
  });
  return decision;
});

Preference Learning

The PreferenceLearner records approval/rejection patterns and surfaces them as UserPreference records that can bias future mode selection — e.g. learning that the user always approves web-search calls but always wants to confirm filesystem writes.

import { PreferenceLearner } from "@reactive-agents/interaction";

const prefs = yield* PreferenceLearner;
yield* prefs.record({
  action: "web-search",
  decision: "approve",
  context: { agentId, taskId },
});
const tolerance = yield* prefs.getTolerance(); // InterruptionTolerance

Key Exports

| Export | Purpose | | ------------------------------------------------- | ------------------------------------------------ | | InteractionManager, InteractionManagerLive | Top-level orchestrator for modes + checkpoints | | ModeSwitcher, ModeSwitcherLive | Programmatic mode transitions | | CheckpointService, CheckpointServiceLive | Approval-point persistence | | NotificationService, NotificationServiceLive | Multi-channel notifications | | CollaborationService, CollaborationServiceLive | Bidirectional agent ↔ human messaging | | PreferenceLearner, PreferenceLearnerLive | Approval-pattern learner | | createInteractionLayer | Factory for the runtime layer | | InteractionModeType, Checkpoint, Notification, InterruptRule, CollaborationSession, UserPreference | Schemas + types | | InteractionError, ModeError, CheckpointError, NotificationError, InputTimeoutError | Tagged errors |

Documentation

• Full docs: docs.reactiveagents.dev/guides/interaction-modes/

License

MIT