Configuration reference

setupAgentCore(options)

const runtime = await setupAgentCore({
  storage,          // required — your database
  queue,            // required — durable dispatch
  bus,              // required — live fan-out
  kv,               // required — hot state
  streams,          // run streams; left out, kept in memory (one process only)
  resolveModel,     // required — registry key → { instance, contextWindow, modelId }
  admin,            // optional — defaults to SQLite, or Postgres via env
  pricer,           // optional — prices every model call (§4)
  tools,            // optional — { search, fetcher } for the built-in web tools
  log,              // optional — defaults to console
  config,           // optional — everything below
});

await matters: the operational store is opened here, and a store that cannot be opened should be a startup error.

config — every setting

Human in the loop

Setting	Default	Meaning
hitlTtlMs	900000 (15 min)	How long a parked approval stays answerable. On expiry it resolves as a timeout denial and the run continues.
reclaimGraceMs	60000	Grace beyond the TTL before orphan reclamation may claim a thread.

Deadlines and overload

The same four settings in both runtimes (Go names in brackets, as durations):

Setting	Default	Meaning
stepTimeoutMs (StepTimeout)	0 (off)	Bounds one model round trip; a step past it fails and the run takes the retry policy.
segmentTimeoutMs (SegmentTimeout)	0 (off)	Bounds one worker segment; a segment past it settles the run FAILED with stopReason timeout.
maxQueueWaitMs (MaxQueueWait)	0 (off)	A job picked up later than this fails with the reason instead of running.
maxQueueDepth (MaxQueueDepth)	0 (off)	A new run is refused (reason queue_full) before anything is written once this many jobs are ready and waiting. Needs a queue that can count.

In Go, a config built by hand keeps the default of every field left at zero where zero could never work (a step cap, a poll, a lease). The two booleans, RecordPayloads and PromptCaching, cannot tell "false" from "left out": start from DefaultConfig() to keep them on.

Run limits

Setting	Default	Meaning
maxSteps	25	Model round trips per run. The safety cap against runaway loops.
tokenBudget	undefined	Default per-run token budget. Unbounded apart from maxSteps.
costBudgetMicros	undefined	Default per-run money cap, in millionths of the pricer's currency. Needs a pricer. See Cost and pricing.
runMaxAttempts	3	Queue redrive attempts before a run finalizes FAILED.
stopPollMs	500	How often a running worker re-reads the stop signal. Also the window in which it notices a newer run replaced it.
runRetryBackoffMs / runRetryBackoffMaxMs	5000 / 120000	A failed run waits this long before its first retry, twice as long each time after, with jitter. The thread shows QUEUED while it waits.
runRedriveDelaySeconds	2	First delay before re-dispatching a job that found the run lock held. It doubles on each try, up to the lease.
runLockLeaseSeconds	120 (2 min)	Lease on the per-thread run lock. The worker renews it every sixth of the lease while it holds it, so an expired lock means a dead worker. A job blocked by a held lock gives up only after waiting at least one lease. Parked approvals hold no lock.

Subagents

Setting	Default	Meaning
subagentMaxDepth	2	Nesting cap.
subagentMaxConcurrent	3	Children running at once per run, at each depth.
subagentMaxSteps	10	Model round trips per child.
subagentResultCapChars	8000	Characters of a child's result handed to the parent.

Built-in tools

Setting	Default	Meaning
builtinToolResultCapChars	20000	The most characters a built-in tool hands the model in one result: a page's text, a reader's answer. Past it the text is cut and the result says truncated: true. See Web tools.
sandboxIdleTtlMs	1800000 (30 min)	A thread's sandbox ends after it has sat unused this long; the next call makes a fresh one. Go: SandboxIdleTTL. See Sandboxes.
sandboxMaxLifetimeMs	86400000 (24 h)	A thread's sandbox ends this long after it was made, however much it is used. Go: SandboxMaxLifetime.
sandboxScope	'thread'	'thread' keeps one sandbox per thread; 'run' gives each run its own, ended with the run. Go: SandboxScope. See Sandboxes.
sandboxKeepOnPark	false	With sandboxScope: 'run', keep the sandbox while the run waits for an approval or an answer. Go: SandboxKeepOnPark.
sandboxDefaults	{}	Merged into every sandbox made: network, envs, template, image, resources, extra. Go: SandboxDefaults.
sandboxStateDir	'.agentenkit'	Where the sandbox tools keep their own files. An absolute path keeps them out of the work folder. Go: SandboxStateDir.

Context and caching

Setting	Default	Meaning
contextCeilingTokens	265000	Universal ceiling.
contextOutputReserveTokens	16000	Held back for the completion.
compactionTrigger	0.8	Compact past this share of budget.
contextTailShare	0.25	Share of budget kept verbatim.
compactionModel	'gpt-4o-mini'	Registry key of the cheap model that writes the summary. Resolved through your own resolveModel, so a registry without that key must name its own.
promptCaching	true	Stamp cache breakpoints on the stable prefix.
nativeWindows	—	Per-model windows below the ceiling. A contextWindow from resolveModel wins.

Run streams

Each run segment writes a short-lived run stream. Go names in brackets, as durations.

Setting	Default	Meaning
streamGraceMs (StreamGrace)	600000 (10 min)	How long a stream is kept after its segment ends. A tab that reconnects within it picks up inside the stream; one that comes later gets a snapshot, which has the final text in the messages.
streamTtlMs (StreamTTL)	86400000 (24 h)	How long a stream lives if nothing ever closes it. The last guard when the worker and the sweep both failed.
streamFlushMs (StreamFlush)	50	How long stream events wait to be appended together. A step end, a tool result, a park and a close go out at once. 0 sends every event as it comes.
streamFlushEvents (StreamFlushEvents)	32	Append at once when this many stream events are waiting.

Keep the grace short on Redis, where streams live in memory. On Postgres or SQLite it can be higher, since rows on disk cost little.

Operational history

Setting	Default	Meaning
recordPayloads	true	Record prompts, step text and tool arguments/results. Turn off when payloads carry sensitive data.
payloadCapChars	2000	Characters kept per recorded value.

Provider options

Setting	Default	Meaning
providerOptions	—	Provider-specific settings applied to every run, keyed by provider namespace. An agent spec overrides it, and a run input overrides both. See Provider options.

Billing

Setting	Default	Meaning
billingPreCheck	—	({ threadId, runId?, state, stage, budget?, publishEvent }) => { ok, error? }. Runs at stage: 'dispatch', before anything is written (a refusal means the run never exists), and again at 'pickup', when a worker takes the job (a refusal fails the run; lowering budget.costBudgetMicros or budget.maxSteps caps this segment). The check can publish on the thread, and the platform publishes RUN_REFUSED.

Pricing is not a config setting — pricer sits on setupAgentCore beside the ports, because it decides what goes into the store rather than how the loop behaves. See Cost and pricing.

Environment variables

Variable	Read by	Meaning
AGENTIC_KIT_ADMIN_DATABASE_URL	core	Postgres for the operational store. Unset means SQLite.
AGENTIC_KIT_ADMIN_DB	core	Path to the SQLite operational store.
TEST_ADMIN_PG	test suite	Postgres URL for the admin store tests.
SKIP_PG_TESTS	test suite	Set to 1 to opt out of them deliberately.

Everything else — provider keys, your database URL, queue credentials — is read by your code, not the library's.

useAgentThread(options)

See React for the full table. In brief: routes, baseUrl, fetch, headers, openStream, defaultModel, persistence, labels, format, onEvent, onCustom, threadsRefreshMs, loadThreadsOnMount, initialThreadId.