Menu
Configure a ReactiveAgentBuilder with the correct layer composition for any agent use case.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | builder-api-reference |
| description | Configure a ReactiveAgentBuilder with the correct layer composition for any agent use case. |
| compatibility | Reactive Agents TypeScript projects using @reactive-agents/* |
| metadata | {"author":"reactive-agents","version":"2.0","tier":"capability"} |
Produce a complete, correctly-ordered builder chain with the right .withX() calls for the task. Every method used must exist in this reference.
The declarative createAgent(config) front door and this fluent builder are the
same API — same key names, same nesting (createAgent({ tools: { allowedTools } })
≡ .withTools({ allowedTools })). Use createAgent for static definitions; the
builder for conditional/imperative construction or code-only escape hatches
(.withHook, .withLayers, .compose). This reference lists the fluent methods;
each maps to an AgentConfig key of the same name.
import { createAgent } from "@reactive-agents/runtime";
const agent = await createAgent({
name: "assistant",
provider: "anthropic",
reasoning: { defaultStrategy: "adaptive", maxIterations: 10 },
});
import { ReactiveAgents } from "@reactive-agents/runtime";
// Minimal — provider + reasoning is enough to run
const agent = await ReactiveAgents.create()
.withName("assistant")
.withProvider("anthropic")
.withReasoning({ defaultStrategy: "adaptive", maxIterations: 10 })
.build();
// Production — adds reliability, observability, cost controls
const agent = await ReactiveAgents.create()
.withName("assistant")
.withProvider("anthropic")
.withModel("claude-opus-4-6")
.withReasoning({ defaultStrategy: "adaptive", maxIterations: 15 })
.withTools({ allowedTools: ["web-search", "file-read", "checkpoint"] })
.withMemory({ tier: "enhanced", dbPath: "./agent.db" })
.withGuardrails({ injection: true, pii: true, toxicity: true })
.withVerification()
.withCostTracking({ perRequest: 0.50, daily: 20.0 })
.withObservability({ verbosity: "normal", live: true })
.withMaxIterations(20)
.build();
| Method | Params | Notes |
|---|---|---|
.withName(name) | string | Display name; defaults to "agent" |
.withAgentId(id) | string | Override auto-generated ID |
.withPersona(p) | { role?, background?, instructions?, tone? } | Generates system prompt from fields |
.withSystemPrompt(s) | string | Raw system prompt — overwrites .withPersona() |
.withEnvironment(ctx) | Record<string, string> | Key-value pairs injected into system prompt |
| Method | Params | Notes |
|---|---|---|
.withProvider(p) | "anthropic"|"openai"|"gemini"|"ollama"|"litellm"|"test" | Required |
.withModel(m) | string | { model, thinking?, temperature? } | Uses provider default if omitted |
.withRateLimiting(cfg) | { requestsPerMinute?, tokensPerMinute?, maxConcurrent? } | Provider-level rate limits |
.withCircuitBreaker(cfg?) | { failureThreshold?, cooldownMs?, halfOpenRequests? } | Retries with backoff on errors |
.withDynamicPricing(provider) | PricingProvider | Fetches live pricing during build |
.withModelPricing(registry) | Record<string, { input, output }> | Custom per-model USD pricing |
| Method | Params | Notes |
|---|---|---|
.withReasoning(opts?) | { defaultStrategy?, maxIterations?, enableStrategySwitching?, maxStrategySwitches?, fallbackStrategy? } | Strategies: "reactive", "plan-execute-reflect", "tree-of-thought", "reflexion", "adaptive" |
.withMaxIterations(n) | number | Hard cap; overrides .withReasoning value |
.withRequiredTools(cfg) | { tools?, adaptive?, maxRetries? } | Forces tool calls before completion |
| Method | Params | Notes |
|---|---|---|
.withTools(opts?) | { tools?, allowedTools?, adaptive?, resultCompression? } | No args = all built-ins enabled |
.withDocuments(docs) | DocumentSpec[] | RAG context injection |
.withPrompts(opts?) | prompts config | Custom prompt templates |
| Method | Params | Notes |
|---|---|---|
.withMemory(opts?) | "standard" | "enhanced" | { tier, dbPath?, capacity? } | "enhanced" requires writable SQLite path |
| Method | Params | Notes |
|---|---|---|
.withGuardrails(opts?) | { injection?, pii?, toxicity?, customBlocklist? } | All default true |
.withKillSwitch() | — | Exposes .pause(), .resume(), .stop(), .terminate() |
.withBehavioralContracts(c) | { deniedTools?, allowedTools?, maxToolCalls?, maxIterations?, maxOutputLength?, deniedTopics?, requireDisclosure? } | Rule-based constraints |
.withVerification(opts?) | { semanticEntropy?, factDecomposition?, nli?, hallucinationDetection?, passThreshold?, useLLMTier? } | Runtime hallucination detection |
.withAudit() | — | Append-only action audit log |
| Method | Params | Notes |
|---|---|---|
.withCostTracking(opts?) | { perRequest?, perSession?, daily?, monthly? } | USD budgets; throws on breach |
| Method | Params | Notes |
|---|---|---|
.withObservability(opts?) | { verbosity?, live?, logModelIO?, file?, telemetry?, tracing? } | file is JSONL output path; telemetry: true | { mode: "contribute"|"isolated" } enables run telemetry |
.withLogging(cfg) | { level?, format?, output?, filePath?, maxFileSizeBytes?, maxFiles? } | Structured logging |
| Method | Params | Notes |
|---|---|---|
.withGateway(opts?) | GatewayOptions | Persistent agent with heartbeats/crons/webhooks |
.withA2A(opts?) | { port?, basePath? } | A2A server (JSON-RPC 2.0 + SSE) |
.withStreaming(opts?) | { density?: "tokens"|"full" } | Streaming output |
.withAgentTool(name, cfg) | name + { agent } | Local agent registered as a tool |
.withDynamicSubAgents(opts?) | { maxIterations? } | Dynamic sub-agent spawning |
.withRemoteAgent(name, url) | name + A2A URL | Remote A2A agent as callable tool |
.withCortex(url?) | optional URL | Cortex desk server integration |
.withHealthCheck() | — | Self-monitoring health endpoint |
.withErrorHandler(fn) | (err, ctx) => void | Custom error handling callback |
.withHook(hook) | LifecycleHook | Lifecycle callbacks (beforeRun, afterStep, etc.) |
.withSelfImprovement() | — | Meta-learning from past runs |
.withExperienceLearning() | — | Injects prior-run experience tips into context |
| Method | Returns | Notes |
|---|---|---|
.build() | Promise<ReactiveAgent> | Always await |
.buildEffect() | Effect<ReactiveAgent> | For Effect runtime callers |
ReactiveAgents.fromConfig(cfg) | Promise<ReactiveAgentBuilder> | From AgentConfig object |
ReactiveAgents.fromJSON(json) | Promise<ReactiveAgentBuilder> | From JSON string |
ReactiveAgents.runOnce(task, builder) | Promise<AgentResult> | Build + run + dispose |
.build() is async — always await or you get an unresolved Promise.withPersona() and .withSystemPrompt() both set the system prompt — the last call wins.withTools() no-args enables 5 standard tools: web-search, http-get, file-read, file-write, code-execute — shell-execute is opt-in only via .withTools({ terminal: true }) (see shell-execution-sandbox skill).withTools({ terminal: true }) enables shell execution sandboxed via Docker or local allowlist — use with caution in production.withMemory("enhanced") without dbPath uses a default path — set it explicitly in multi-agent environments to avoid collisions.withGateway() requires calling .start() on the built agent; .build() alone does not start the loopenableStrategySwitching: true without maxStrategySwitches defaults to 2 switches maxAgentic harness diagnostic + improvement loop. Probes the framework with real model runs, uses the rax-diagnose CLI to root-cause failures from structured trace data, ships ONE coordinated architectural fix, verifies via before/after diff, commits with empirical evidence. Use at the start of any harness improvement session — replaces ad-hoc grep + log-spelunking with a deterministic feedback loop.
Use when the architecture may have drifted from documentation, packages have grown complex, dead code or disabled systems are suspected, or before planning a major refactor — scoped to the reactive-agents-ts 22-package monorepo.
Reactive Agents framework architecture — layer stack, dependency graph, build order, and package structure. Use when planning work, understanding package relationships, or determining build dependencies.
Use when analyzing the Reactive Agents codebase for architectural improvements, abstraction opportunities, composability gaps, or Effect-TS engineering quality — before proposing refactors, during design reviews, or when codebase complexity is growing.
LLMService API contract — the correct signatures for complete(), stream(), embed(), and response types. Use when calling LLMService from any layer, writing reasoning strategies, or building LLM-dependent features.
LLM provider streaming patterns and per-provider quirks. Use when adding a new provider, implementing adapter hooks, or debugging streaming tool call behavior in packages/llm-provider.