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

// 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

10

---

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

boolean | void | SessionSnapshot | Promise<boolean | void | SessionSnapshot>

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

boolean | void | SessionSnapshot | Promise<boolean | void | SessionSnapshot>

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

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

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.