interaction-autonomy

name: interaction-autonomy description: Configure one of 5 human-agent interaction modes (autonomous through interrogative) and implement mode-switching, approval gates, and collaborative workflows. compatibility: Reactive Agents TypeScript projects using @reactive-agents/* metadata: author: reactive-agents version: "2.0" tier: "capability"

Interaction and Autonomy

Agent objective

Produce a builder with .withInteraction() enabled and the correct initial mode configured, with guidance on how to switch modes at runtime and handle approval checkpoints.

When to load this skill

• Configuring how much autonomy an agent has vs. how much human oversight is required
• Building a supervised agent that pauses for approval at key decision points
• Implementing a collaborative mode where agent and user work together in real-time
• Switching modes dynamically based on task risk or user preference

The 5 interaction modes

Implementation baseline

import { ReactiveAgents } from "@reactive-agents/runtime";

// Supervised agent — pauses at milestones for approval
const agent = await ReactiveAgents.create()
  .withName("assistant")
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 20 })
  .withTools({ allowedTools: ["web-search", "file-read", "file-write", "checkpoint"] })
  .withInteraction()   // enables interaction layer with all 5 modes
  .withSystemPrompt(`
    You are operating in supervised mode.
    Before writing any files, checkpoint your plan and wait for approval.
  `)
  .build();

Key patterns

Enabling interaction

.withInteraction()
// Enables the InteractionManager, ModeSwitcher, NotificationService,
// CheckpointService, CollaborationService, and PreferenceLearner.
// Default mode: "autonomous"

Mode usage

// "autonomous" — agent runs to completion without interruption
// Best for: background tasks, cron jobs, trusted pipelines
const agent = ReactiveAgents.create()
  .withInteraction()
  .withSystemPrompt("Complete the task without interruption.")
  .build();

// "supervised" — agent must receive approval before continuing past checkpoints
// Best for: production deployments, high-risk tool calls
const agent = ReactiveAgents.create()
  .withInteraction()
  .withGuardrails()
  .withGateway({ policies: { requireApprovalFor: ["file-write", "send-email"] } })
  .build();

// "collaborative" — agent and user exchange messages during execution
// Best for: interactive chat, pair programming workflows

// "consultative" — agent surfaces observations and suggestions
// Best for: advisory dashboards, recommendation engines

// "interrogative" — user can query agent state mid-execution
// Best for: debugging, explainability, audit

Accessing InteractionManager at runtime

import { InteractionManager } from "@reactive-agents/interaction";
import { Effect } from "effect";

// Switch mode at runtime (e.g., escalate from autonomous to supervised):
const program = Effect.gen(function* () {
  const manager = yield* InteractionManager;
  yield* manager.switchMode(agentId, "supervised");
  const currentMode = yield* manager.getMode(agentId);
  console.log("Now in mode:", currentMode);
});

Approval checkpoints in supervised mode

In "supervised" mode, the agent can pause and request human approval:

// System prompt instructs the agent to use the checkpoint tool:
.withSystemPrompt(`
  When you are about to take an irreversible action (file writes, API calls),
  use the checkpoint tool to save your plan and pause for review.
  Only proceed after receiving confirmation.
`)
.withTools({ allowedTools: ["checkpoint", "file-read", "file-write"] })
.withInteraction()

The checkpoint tool (SAVE mode) records state; the approval flow is handled by your application layer reading the checkpoint and calling agent.resume().

Combining with kill switch for mode transitions

const agent = ReactiveAgents.create()
  .withInteraction()
  .withKillSwitch()  // enables pause/resume for approval gates
  .build();

const handle = agent.run(task);

// Pause for approval:
await handle.pause();
// ... user reviews ...
await handle.resume();

Builder API reference

Pitfalls

• .withInteraction() enables the layer but does not set the initial mode — the agent defaults to "autonomous" unless the system prompt or runtime code switches it
• Mode switching is per-agent-ID — ensure the correct agentId is used when calling InteractionManager.switchMode()
• "supervised" mode without .withKillSwitch() means approval checkpoints can be described in the system prompt but cannot programmatically pause execution — pair them together
• Default approval timeout in InteractionManager is 5 minutes — if no approval arrives, the agent proceeds or times out based on policy
• "collaborative" and "interrogative" modes require a live communication channel between the agent and the user — these modes are designed for real-time UI integrations (see ui-integration skill)