Session

Call agent.run() to create an in-memory Session. A session owns its transcript, queue, interactions, active work, and lifecycle events. Your application chooses the session identity and provides persistence through a recorder.

const session = agent.run({
  id: "session-42",
  userId: "user-42",
  context: { locale: "en" },
  recorder: { record: async (record) => store.append(record) },
});

const completion = await session.input("Find my latest order.").completed;

Interaction and deferred work

session.input() accepts text or an approval/response reply. An interaction-required tool pauses a session in waiting; send the matching reply with input() to resume it. Use interrupt() for barge-in text, continue() after deferred work is ready, and stop() to terminate a session.

Tool and model adapters may return { kind: "deferred", token? }. Persist the resulting active record in host storage if you need to resume the work across process boundaries, then use a seeded session when reconstructing the in-memory loop.

Persistence and observation

SessionRecorder.record() receives normalized transition records. Persist them in your database, event log, or queue; recorder failures are surfaced as observations rather than silently changing the model loop. session.stream() exposes session events, while session.observe() provides live lifecycle events for model requests, tools, interactions, deferred work, and final output.

See Sessions for seeds, records, events, and method signatures.