Session

A first-class conversation session.

Created by agent.session(). Holds conversation history and state that persist across multiple turns. Turns execute sequentially.

Example

const session = agent.session()
const r1 = await session.run("Hello").result
const r2 = await session.run("Follow up").result
await session.close()

readonly history: Message[]

Flat chronological conversation history, auto-accumulates across turns.

readonly id: string

Unique session identifier.

readonly state: Record<string, unknown>

Session state — read-only for client code. Middleware writes via ctx.state.

[asyncDispose](): Promise<void>

Alias for close() — enables await using session = agent.session().

Promise<void>

close(): Promise<void>

Close the session, triggering session-level middleware cleanup. Idempotent — safe to call multiple times.

Promise<void>

run(input, opts?): AgentRun

Execute a single conversational turn.

Returns an AgentRun with dual interface: async iterable for streaming, .result Promise for the final RunResult.

string

User message text

Optional run options (e.g., output schema)

If the session has been closed

If a turn is already in progress