Documentation / @agentick/core / AppOptions

Interface: AppOptions

Defined in: core/src/app/types.ts:458

Configuration options for creating an App instance.

AppOptions configure the execution runner - things that apply across all sessions created from this app.

Extends

LifecycleCallbacks

Properties

devTools?

optional devTools: boolean

Defined in: core/src/app/types.ts:506

Enable DevTools event emission for all sessions created by this app.

When true, lifecycle events (execution_start, tick_start, tick_end, execution_end, fiber_snapshot) are emitted to the DevTools emitter.

Default

false

inbox?

optional inbox: InboxStorage

Defined in: core/src/app/types.ts:538

Override default in-memory inbox with a durable backend.

The inbox enables external message delivery to sessions. A MemoryInboxStorage is created automatically if not provided.

inheritDefaults?

optional inheritDefaults: boolean

Defined in: core/src/app/types.ts:661

Whether to inherit middleware and telemetry from the global Agentick instance.

When true (default), the app inherits:

Middleware registered via Agentick.use('*', mw), Agentick.use('tool:*', mw), etc.
Telemetry provider from Agentick.telemetryProvider

Set to false for isolated apps (useful in testing).

Default

true

Example

typescript

// App inherits Agentick defaults (default behavior)
const app = createApp(MyAgent, { model });

// Isolated app - no Agentick middleware
const testApp = createApp(TestAgent, { model, inheritDefaults: false });

maxTicks?

optional maxTicks: number

Defined in: core/src/app/types.ts:480

Maximum number of ticks before stopping execution.

Default

maxTimelineEntries?

optional maxTimelineEntries: number

Defined in: core/src/app/types.ts:628

Maximum timeline entries to keep in memory per session. When exceeded, oldest entries are trimmed after each tick. Default: unbounded.

mcpServers?

optional mcpServers: Record<string, MCPConfig>

Defined in: core/src/app/types.ts:474

MCP server configurations.

model?

optional model: EngineModel<ModelInput, ModelOutput>

Defined in: core/src/app/types.ts:463

Override model from JSX (for testing/mocking). If not provided, uses the model from <Model> component in JSX tree.

onAfterPersist()?

optional onAfterPersist: (sessionId, snapshot) => void | Promise<void>

Defined in: core/src/app/types.ts:579

Called after a session snapshot has been persisted.

Parameters

sessionId

string

The ID of the persisted session

snapshot

SessionSnapshot

The snapshot that was saved

Returns

void | Promise<void>

onAfterRestore()?

optional onAfterRestore: (session, snapshot) => void | Promise<void>

Defined in: core/src/app/types.ts:603

Called after a session has been restored.

Parameters

session

Session

The restored session

snapshot

SessionSnapshot

The snapshot that was used

Returns

void | Promise<void>

onAfterSend()?

optional onAfterSend: (session, result) => void

Defined in: core/src/app/types.ts:614

Called after send completes successfully.

Parameters

session

Session

result

SendResult

Returns

void

onBeforePersist()?

optional onBeforePersist: (session, snapshot) => boolean | void | SessionSnapshot | Promise<boolean | void | SessionSnapshot>

Defined in: core/src/app/types.ts:568

Called before a session snapshot is persisted to store.

Use this to:

Cancel persistence (return false)
Modify the snapshot before saving (return modified snapshot)

Parameters

session

Session

The session being persisted

snapshot

SessionSnapshot

The snapshot that will be saved

Returns

false to cancel, modified snapshot, or void to proceed

onBeforeRestore()?

optional onBeforeRestore: (sessionId, snapshot) => boolean | void | SessionSnapshot | Promise<boolean | void | SessionSnapshot>

Defined in: core/src/app/types.ts:592

Called before a session is restored from storage.

Use this to:

Cancel restoration (return false)
Migrate/transform old snapshot formats (return modified snapshot)

Parameters

sessionId

string

The ID of the session being restored

snapshot

SessionSnapshot

The snapshot loaded from storage

Returns

false to cancel, modified snapshot, or void to proceed

onBeforeSend()?

optional onBeforeSend: <P>(session, input) => void | SendInput<P>

Defined in: core/src/app/types.ts:609

Called before send is executed. Return a modified input to override what is sent.

Type Parameters

P

P

Parameters

session

Session<P>

input

SendInput<P>

Returns

void | SendInput<P>

onComplete()?

optional onComplete: (result) => void

Defined in: core/src/app/types.ts:87

Called when execution completes successfully.

Parameters

result

SendResult

The final result

Returns

void

Inherited from

LifecycleCallbacks.onComplete

onError()?

optional onError: (error) => void

Defined in: core/src/app/types.ts:93

Called when an error occurs during execution.

Parameters

error

Error

The error that occurred

Returns

void

Inherited from

LifecycleCallbacks.onError

onEvent()?

optional onEvent: (event) => void

Defined in: core/src/app/types.ts:67

Called for every stream event. Use this for fine-grained event handling.

Parameters

event

StreamEvent

Returns

void

Inherited from

LifecycleCallbacks.onEvent

onSessionClose()?

optional onSessionClose: (sessionId) => void

Defined in: core/src/app/types.ts:555

Called when a session is closed and removed from the registry.

Parameters

sessionId

string

Returns

void

onSessionCreate()?

optional onSessionCreate: (session) => void

Defined in: core/src/app/types.ts:550

Called when a session is created.

Parameters

session

Session

Returns

void

onTickEnd()?

optional onTickEnd: (tick, usage?) => void

Defined in: core/src/app/types.ts:81

Called when a tick ends.

Parameters

tick

number

The tick number

usage?

UsageStats

Token usage for this tick

Returns

void

Inherited from

LifecycleCallbacks.onTickEnd

onTickStart()?

optional onTickStart: (tick, executionId) => void

Defined in: core/src/app/types.ts:74

Called when a tick starts.

Parameters

tick

number

The tick number (1-indexed)

executionId

string

The execution ID

Returns

void

Inherited from

LifecycleCallbacks.onTickStart

onToolConfirmation()?

optional onToolConfirmation: (call, message) => Promise<boolean>

Defined in: core/src/app/types.ts:621

Callback for tool confirmation. Called when a tool with requiresConfirmation is invoked. Return true to allow, false to deny.

Parameters

call

ToolCall

message

string

Returns

Promise<boolean>

resolve?

optional resolve: ResolveConfig

Defined in: core/src/app/types.ts:639

Resolve configuration for loading data before session render.

When a session is restored from a store, resolve functions receive the snapshot as context. Results are available via useResolved(key).

When resolve is set, snapshots are NOT auto-applied on restore — the resolve function controls reconstruction (Layer 2).

runner?

optional runner: ExecutionRunner

Defined in: core/src/app/types.ts:496

Execution runner for all sessions created by this app.

Controls how compiled context reaches the model and how tool calls execute. Default: standard model→tool_use protocol (no transformation).

Example

typescript

const app = createApp(MyAgent, {
  model,
  runner: replRunner({ sandbox: true }),
});

sessionResolver()?

optional sessionResolver: (message) => string | Promise<string | null> | null

Defined in: core/src/app/types.ts:545

Route incoming messages to session IDs. Used by app.receive().

Return a session ID to route to, or null to create a new session.

Parameters

message

InboxMessageInput

Returns

string | Promise<string | null> | null

sessions?

optional sessions: SessionManagementOptions

Defined in: core/src/app/types.ts:530

Session management configuration.

Controls persistence, limits, and auto-cleanup of sessions.

Example

typescript

const app = createApp(MyAgent, {
  sessions: {
    store: new RedisSessionStore(redis),
    maxActive: 100,
    idleTimeout: 5 * 60 * 1000, // 5 minutes
  },
});

signal?

optional signal: AbortSignal

Defined in: core/src/app/types.ts:512

App-level abort signal. All sessions will respect this signal.

tools?

optional tools: ExecutableTool<(input, ctx?) => ContentBlock[] | Promise<ContentBlock[]>>[]

Defined in: core/src/app/types.ts:469

Additional tools to make available. These are merged with tools from <Tool> components in JSX.

knob

Functions