API Cheatsheet

The 80% of the API you’ll use, all on one page. For full signatures and option types, see the generated Builder API reference and Configuration reference (both emitted from the schema — the single source of truth).

Two syntaxes, one API

createAgent(config) (declarative) and ReactiveAgents.create().withX() (fluent) are the same API: same names, same nesting — createAgent({ tools: { allowedTools } }) ≡ .withTools({ allowedTools }). Use the config object for static definitions (the 90% case); reach for the builder when construction is conditional/imperative or needs a code-only escape hatch (hooks, layers, compose).

Reading guide

Method tables below use these markers:  essential in any working agent.  recommended for any production agent.  opt-in niche capability — enable when you need it.  advanced requires understanding the lifecycle.

Minimum viable agent

The front door — a declarative config object:

import { createAgent } from "reactive-agents";

const agent = await createAgent({
  name: "assistant",
  provider: "anthropic",
});

const result = await agent.run("What's 2 + 2?");
console.log(result.output);

That’s it. Provider key from .env, model auto-picked, direct LLM loop. The same agent via the fluent builder:

import { ReactiveAgents } from "reactive-agents";

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

---

Builder Methods (most-used)

Identity & provider

Method	Status	What it does
.withName(name)	recommended	Identifier for logs, telemetry, A2A
.withProvider(p)	essential	"anthropic" · "openai" · "gemini" · "groq" · "xai" · "ollama" · "litellm" · "test"
.withModel(id)	recommended	e.g. "claude-sonnet-4-6", "gpt-4o", "qwen3:14b"
.withSystemPrompt(s)	opt-in	Persona / instructions for the agent

Cognition

Method	Status	What it does
.withReasoning()	essential	ReAct loop (default). Pass { defaultStrategy: "tree-of-thought" } to switch.
.withTools()	recommended	Built-in tools + meta-tools (recall, find, brief, pulse)
.withTools({ tools: [myTool] })	opt-in	Add custom tools to the registry
.withMemory()	recommended	4-layer memory, tier "standard" (FTS5 keyword search)
.withMemory({ tier: "enhanced" })	opt-in	+ vector embeddings (needs EMBEDDING_PROVIDER)
.withSkills({ paths: ["./skills/"] })	opt-in	Living Skills System — agentskills.io compatible

Production safety

Method	Status	What it does
.withGuardrails()	recommended	Pre-LLM injection / PII / toxicity blocking
.withVerification()	opt-in	Post-LLM fact-check (semantic entropy, NLI)
.withCostTracking()	recommended	Complexity routing + budget enforcement
.withIdentity()	advanced	Ed25519 certificates + RBAC + delegation
.withKillSwitch()	recommended	Per-agent + global emergency halt
.withRequiredTools({ tools: ["web-search"] })	opt-in	Force critical tool calls before answering
.withApprovalPolicy({ tools, mode: "detach" })	opt-in	Gate tool calls behind durable human approval (HITL)

Observability

Method	What it does
.withObservability({ verbosity: "normal", live: true })	Metrics dashboard + live phase logs + tracing
.withLogging({ level, format, filePath })	Structured logs (rotates at maxFileSizeMb)
.withCortex()	Stream telemetry to Cortex Studio over WebSocket
.withHealthCheck()	Adds agent.health() probe

Reliability

Method	What it does
.withTimeout(ms)	Hard execution timeout
.withRetryPolicy({ maxRetries, backoffMs })	Retry on transient LLM failures
.withFallbacks({ providers, errorThreshold })	Provider/model fallback chain
.withErrorHandler(fn)	Global error callback
.withMinIterations(n)	Force at least N reasoning steps
.withVerificationStep({ mode: "reflect" })	LLM self-review before answering
.withOutputValidator(fn)	Retry until output passes a predicate
.withCustomTermination(fn)	User-defined “done” check
.withDurableRuns({ dir, checkpointEvery })	Checkpoint every iteration to SQLite; crash-resume via resumeRun (Durable Execution)

Multi-agent & gateway

Method	What it does
.withDynamicSubAgents({ maxIterations })	Model-spawned sub-agents at runtime
.withAgentTool(name, config)	Named purpose-built sub-agent
.withOrchestration()	Sequential / parallel / pipeline / map-reduce
.withA2A()	Agent Cards + JSON-RPC + SSE for cross-agent calls
.withGateway({ heartbeat, crons, webhooks, policies })	Persistent autonomous harness

Hooks

Method	What it does
.withHook({ phase, timing, handler })	Intercept any of the 12 phases

.withHook({
  phase: "act",
  timing: "after",
  handler: (ctx) => Effect.succeed(ctx),
})

Phases: bootstrap · guardrail · cost-route · strategy-select · think · act · observe · verify · memory-flush · cost-track · audit · complete

---

Runtime methods (after .build())

Method	Returns
agent.run(task)	Promise<AgentResult> — full execution (status: "awaiting-approval" if gated)
agent.run(task, { onApproval })	Same-process HITL — callback drives pause → decide → resume
agent.runStream(task, { signal })	AsyncGenerator<AgentEvent> — token streaming
agent.chat(question)	Promise<string> — single-turn Q&A with adaptive routing
agent.session()	Multi-turn session with memory
agent.subscribe(tag, fn)	Listen to EventBus events
agent.registerTool(def, handler)	Add a tool at runtime
agent.unregisterTool(name)	Remove a tool at runtime
agent.listRuns({ status? })	Persisted durable runs, newest first (needs .withDurableRuns())
agent.resumeRun(runId)	Reconstruct + finish a crashed run from its last checkpoint
agent.listPendingApprovals()	Runs paused at an approval gate, awaiting a decision
agent.approveRun(runId) / agent.denyRun(runId, reason)	Resume a paused run — execute or skip the gated call
agent.health()	{ status, checks[] } — readiness probe
agent.dispose()	Cleanup MCP + open resources

AgentResult shape:

{
  output: string,
  success: boolean,
  debrief?: { summary, keyFindings, metrics },
  terminatedBy: "final_answer_tool" | "final_answer" | "max_iterations" | "end_turn" | "llm_error" | "abstained",
  abstention?: { reason, missing },  // present iff terminatedBy === "abstained"
  metadata: { duration, cost, tokensUsed, stepsCount, strategyUsed },
}

---

Event tags (subscribe via agent.on())

Tag	Fires when
AgentStarted / AgentCompleted	Task begins / ends
ReasoningStepCompleted	Each thought / action / observation
ToolCallCompleted	Each tool call ({ toolName, durationMs, success })
IterationProgress	Every reasoning loop iteration (streaming)
StrategySwitched	Auto-strategy-switch triggered
GuardrailViolationDetected	Input blocked
LLMRequestStarted / LLMRequestCompleted	Each LLM API call
MemoryBootstrapped / MemoryFlushed	Memory loaded / written
FinalAnswerProduced	Final answer extracted from loop
ContextSynthesized	Context curation step ran
TextDelta	Token-level streaming chunk (runStream only)
StreamCompleted / StreamCancelled	Stream end states

---

Streaming pattern

const controller = new AbortController();

for await (const event of agent.runStream("Analyze this", { signal: controller.signal })) {
  if (event._tag === "TextDelta") process.stdout.write(event.text);
  if (event._tag === "IterationProgress") console.log(`Step ${event.iteration}/${event.maxIterations}`);
  if (event._tag === "StreamCompleted") {
    console.log(event.toolSummary);  // Array<{ toolName, calls, successRate }>
  }
}

// Cancel from anywhere
controller.abort();

One-line SSE endpoint:

import { AgentStream } from "reactive-agents";
Bun.serve({ fetch: (req) => AgentStream.toSSE(agent.runStream("Hello")) });

---

Functional composition

import { agentFn, pipe, parallel, race } from "reactive-agents";

// Lazy agent functions
const researcher = agentFn({ name: "researcher", provider: "anthropic" }, (b) =>
  b.withReasoning().withTools()
);

// Sequential pipeline
const pipeline = pipe(researcher, summarizer);
const result = await pipeline("Find latest AI news");

// Parallel fan-out — output contains labeled results from all 3
const multi = parallel(sentimentAgent, keywordAgent, summaryAgent);

// Fastest wins
const fastest = race(claudeAgent, gpt4Agent);

// Cleanup
await pipeline.dispose();

---

Agent as data

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

const builder = ReactiveAgents.create()
  .withName("researcher")
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "plan-execute-reflect" })
  .withTools({ adaptive: true })
  .withMemory({ tier: "enhanced" });

const json = agentConfigToJSON(builder.toConfig());
// Save to DB / send over wire / commit to repo

const restored = await ReactiveAgents.fromJSON(json);
const agent = await restored.build();

---

Environment variables

# Pick one provider key (or run local Ollama)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
GROQ_API_KEY=gsk_...
XAI_API_KEY=xai-...

# Optional — enables built-in tools
TAVILY_API_KEY=tvly-...      # Web search
SERPER_API_KEY=...           # Web search (alt)

# Optional — vector memory ("enhanced" tier)
EMBEDDING_PROVIDER=openai    # or "ollama"
EMBEDDING_MODEL=text-embedding-3-small

# Tuning
LLM_DEFAULT_MODEL=claude-sonnet-4-6
LLM_DEFAULT_TEMPERATURE=0.7
LLM_MAX_RETRIES=3
LLM_TIMEOUT_MS=30000

---

CLI (rax)

bunx rax init my-app --template standard      # Scaffold a project
rax create agent researcher --recipe researcher  # Generate from recipe
rax run "Explain X" --provider anthropic         # Run an agent
rax serve --port 4111                            # Expose as A2A HTTP server
rax cortex                                       # Launch Cortex Studio
rax playground                                   # Interactive REPL
rax eval run --suite ./eval-suite.yaml           # Run an evaluation
rax inspect <agent-id>                           # Debug a session
rax health                                       # Check provider readiness

Full reference: CLI Commands.

---

Mental model

A ReactiveAgent is a runtime built from composable Layers. Each .with*() adds a Layer. build() composes them into the ExecutionEngine’s 12-phase lifecycle. agent.run() flows a task through all 12 phases. Hooks intercept any phase. Events fire from every phase. No singletons, no global state — each agent is its own isolated runtime.

.withProvider() · .withReasoning() · .withTools() · .withMemory()
                          ↓
                  build() composes Layers
                          ↓
                   12-phase ExecutionEngine
                          ↓
                bootstrap → guardrail → cost-route → strategy-select
                          ↓
                       ⟲ think → act → observe ⟲
                          ↓
                  verify → memory-flush → cost-track → audit → complete
                          ↓
                      AgentResult

For the deep dive, see Architecture and Layer System.