Session API

Created via myAgent.session(id). Returns a session handle with methods for sending messages, streaming responses, and managing the session.

import { myAgent } from "@/agent";

const session = myAgent.session(chatId);

session() is synchronous — it returns a handle immediately. No network call until you call a method.

Properties

Property	Type	Description
`id`	`string`	The session ID.
`sandbox`	`SandboxHandle`	Lazy sandbox handle bound to this session. See session.sandbox.

Methods

session.send(input, opts?)

Send a message or approval to the session. Triggers the LLM loop.

Parameter	Type	Required	Description
`input`	`SendInput \| SendInput[]`	Yes	See SendInput.
`opts`	`SendOptions`	No	See SendOptions.

Returns: Promise<SendResult>

const result = await session.send("What files are in the project?");

const result = await session.send("Hello", {
  interruptIfStreaming: true,
  context: { authToken: "..." },
});

session.stream(runOrOpts?)

Get a stream of the assistant response.

Parameter	Type	Description
`runOrOpts`	`WorkflowRunLike \| StreamOptions`	Optional. Pass a workflow result for workflow streaming, or options for reconnection.

Returns: Promise<ReadableStream<UIMessageChunk>>

const stream = await session.stream();
return createUIMessageStreamResponse({ stream });

const result = await start(agentWorkflow, [...]);
const stream = await session.stream(result);

Throws if no active stream exists and no workflow result is provided.

session.history()

Get conversation history from storage.

Returns: Messages and parts for the session.

const history = await session.history();

session.interrupt(opts?)

Interrupt the current streaming response.

Parameter	Type	Description
`opts.lastPart`	`{ index: number; part: unknown }`	Optional. Precise interruption point.

Returns: Promise<void>

await session.interrupt();
await session.interrupt({ lastPart: { index: 3, part: lastPartData } });

session.usage()

Get token usage for the session.

Returns: Promise<UsageSummary>

const usage = await session.usage();

session.update(opts)

Update session configuration. Since runtime config (model, system, tools, etc.) is resolved from agent options each step, update() is scoped to persistent session fields:

Parameter	Type	Description
`sandboxId`	`string`	Override sandbox ID for this session.
`lastMessageId`	`string`	Last message ID (typically managed internally).

Returns: Promise<void>

await session.update({
  sandboxId: "custom-sandbox-123",
});

To change model, system prompt, or active tools dynamically, use resolvable agent options with context instead.

A lazy sandbox handle that resolves the sandbox ID from the session's storage record. Exposes all sandbox methods (setup, exec, readFile, writeFiles, getDomain, kill, updateNetworkPolicy, start, stop, snapshot, getStatus) without needing to know the sandbox ID upfront.

const session = myAgent.session(chatId);

// Set up the sandbox for this session
await session.sandbox.setup({ version: "v1" });

// Execute commands
const result = await session.sandbox.exec({ command: "ls", args: ["-la"] });

The sandbox ID is resolved dynamically — it reads sandboxId from the session's storage record, falling back to the session ID.

SendInput

type SendInput =
  | string
  | UIMessage
  | { role?: UIMessage["role"]; parts: UIMessage["parts"]; metadata?: Record<string, unknown>; id?: string }
  | { type: "message"; message: MessageData }
  | { type: "approval"; approval: ApprovalData };

String — Treated as a user message with a single text part.
UIMessage / parts object — Full message shape. role defaults to "user". Optional metadata is persisted with the message.
{ type: "message" } — Explicit message wrapper.
{ type: "approval" } — Resolve a pending tool approval.

SendOptions

type SendOptions = {
  interruptIfStreaming?: boolean | { lastPart: { index: number; part: unknown } };
  context?: TContext;
  abortSignal?: AbortSignal;
  sandboxId?: string;
};

Option	Type	Description
`interruptIfStreaming`	`boolean \| { lastPart: { index, part } }`	Interrupt the current response before sending.
`context`	`TContext`	Transient context (validated by `contextSchema`). Not persisted. Passed to resolvable options.
`abortSignal`	`AbortSignal`	Signal to abort the request.
`sandboxId`	`string`	Override sandbox ID for this session. Persisted if different from current.

SendResult

type SendResult = {
  assistantMessageId: string;
  done: true | Promise<true>;
};

assistantMessageId — ID of the assistant response message.
done — Resolves when the LLM loop completes. true if already finished, Promise<true> if still running.

StreamOptions

type StreamOptions = {
  messageId?: string;
  startIndex?: number;
};

WorkflowRunLike

type WorkflowRunLike = {
  getReadable(options?: { startIndex?: number }): ReadableStream;
};

Pass a workflow run result to session.stream() to stream from a durable workflow.

AgentStatus

Transient status indicators emitted over the stream during long-running phases. Delivered as data-status chunks — not persisted.

type AgentStatus =
  | { type: "sandbox-setup" }
  | { type: "sandbox-setup-cold" }
  | { type: "loading-skills" }
  | { type: "processing-approvals" }
  | { type: "needs-approval" }
  | { type: "thinking" }
  | { type: "custom"; status: string };