Documentation / @agentick/core / App

Interface: App<P>

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

A reusable app instance created by createApp().

All sessions are persistent sessions internally. Ephemeral execution (run/stream) creates a session, sends once, then closes immediately.

Example

const MyAgent = ({ query, context }) => (
  <>
    <System>You are helpful. {context}</System>
    <Timeline />
    <User>{query}</User>
  </>
);

const app = createApp(MyAgent, { model });

// Ephemeral: create → send → close
const result = await app.run({ query: "Hello!", context: "Be concise" });

// Streaming ephemeral
for await (const event of app.stream({ query: "Hello!" })) {
  console.log(event);
}

// Persistent session (new with generated ID)
const session = app.session();
await session.render({ query: "Hello!" });
await session.render({ query: "Follow up" });
await session.close();

// Named session (get-or-create by ID)
const conv = app.session('conv-123');
await conv.render({ query: "Hello!" });

// Session with options
const withOpts = app.session({ sessionId: 'conv-456', maxTicks: 5 });

Type Parameters

P

P = { }

Properties

run

run: Procedure<(input) => SessionExecutionHandle, true>

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

Run the app with input.

Returns SessionExecutionHandle (AsyncIterable, not PromiseLike):

• await handle.result → SendResult
• for await (const event of handle) → StreamEvent

Creates an ephemeral session internally (create → run → close).

Examples

const result = await app.run({
  props: { system: "You are helpful" },
  messages: [{ role: "user", content: [{ type: "text", text: "Hello!" }] }],
}).result;
console.log(result.response);

const result = await app.run({
  props: { system: "You are helpful" },
  messages: [{ role: "user", content: [{ type: "text", text: "Follow up" }] }],
  history: previousConversation.entries,
  maxTicks: 5,
  devTools: true,
}).result;

const handle = await app.run({ messages });
handle.queueMessage({ role: "user", content: [...] });
const result = await handle.result;

---

sessions

readonly sessions: readonly string[]

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

List active session IDs.

Methods

close()

close(sessionId): Promise<void>

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

Close and cleanup a session.

Parameters

sessionId

string

Returns

Promise<void>

---

getSession()

getSession(sessionId): Session<P> | undefined

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

Get a live session by ID. Returns undefined if not in memory.

Unlike session(id) which creates-or-gets, this is read-only inspection. Does not hydrate from store or create a new session.

Parameters

sessionId

string

Returns

Session<P> | undefined

---

has()

has(sessionId): boolean

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

Check if a session exists (in memory).

Parameters

sessionId

string

Returns

boolean

---

onSessionClose()

onSessionClose(handler): () => void

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

Register onSessionClose handler.

Parameters

handler

(sessionId) => void

Returns

(): void

Returns

void

---

onSessionCreate()

onSessionCreate(handler): () => void

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

Register onSessionCreate handler.

Parameters

handler

(session) => void

Returns

(): void

Returns

void

---

processInbox()

processInbox(): Promise<void>

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

Process all pending inbox messages across all sessions.

Hydrates sessions as needed (from store) and drains their inboxes. Call this at startup to sweep durable backends after restart.

Returns

Promise<void>

---

receive()

Call Signature

receive(message): Promise<void>

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

Deliver a message to the inbox with routing.

Routes via sessionResolver if configured, otherwise creates a new session. The message is written to the inbox storage; if the target session is active, its subscriber fires immediately and drains.

Parameters

message

InboxMessageInput

Returns

Promise<void>

Call Signature

receive(sessionId, message): Promise<void>

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

Deliver a message directly to a specific session's inbox by ID.

Bypasses the sessionResolver entirely — writes straight to inbox storage. Use this for session-to-session communication where the target is already known.

Parameters

sessionId

string

message

InboxMessageInput

Returns

Promise<void>

---

send()

send(input, options?): Promise<SessionExecutionHandle>

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

Send to a session.

Without sessionId: creates ephemeral session, executes, destroys. With sessionId: creates or reuses managed session (may hydrate from store).

Parameters

input

SendInput<P>

options?

sessionId?

string

Returns

Promise<SessionExecutionHandle>

---

session()

Call Signature

session(id?): Promise<Session<P>>

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

Get or create a session.

This is the primary way to access sessions:

• session() - Creates new session with generated ID
• session('id') - Gets existing or creates new session with that ID
• session({ sessionId, ...opts }) - Gets or creates with options

Use app.has(id) to check if a session exists without creating it.

Parameters

id?

string

Returns

Promise<Session<P>>

Example

// New session with generated ID
const session = app.session();

// Get or create by ID
const conv = app.session('conv-123');

// With options
const withOpts = await app.session({ sessionId: 'conv-456', maxTicks: 5 });
const newWithOpts = await app.session({ maxTicks: 5 }); // Generated ID

Call Signature

session(options): Promise<Session<P>>

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

Parameters

options

SessionOptions

Returns

Promise<Session<P>>