Interface AgentSession

send

• send(input, opts?): Promise<GenerateTextResult>

• Sends a user message and returns the complete assistant reply. Appends the send's lossless transcript delta to the session history (disable with history: false on the agent config). Accepts plain text or multimodal content (text + image parts).

  Parameters

  • input: MessageContent

    User message as text string or MessageContent array.
  • Optional opts: SessionSendOptions<undefined>

    Per-send options without a responseSchema: the generation overrides, abortSignal and budget.

  Returns Promise<GenerateTextResult>

  The full generation result including text, usage, and tool calls.
• send<S>(input, opts): Promise<SessionSendStructuredResult<output<S>>>

• Sends a user message with a Zod schema enforced server-side via the provider's native structured-output API. The reply is parsed and validated; the typed object is returned on result.object alongside the JSON string in result.text. Session history is appended just as in the text-only path, so subsequent send calls see the structured response in their conversation context.

  Type Parameters

  • S extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

  Parameters

  • input: MessageContent

    User message as text string or MessageContent array.
  • opts: SessionSendOptions<S> & {
        responseSchema: S;
    }

    Must include responseSchema.

  Returns Promise<SessionSendStructuredResult<output<S>>>

  Result with a typed object: z.infer<S> field.

  Throws

  If the provider returns schema-enforced JSON that nonetheless fails Zod validation after maxValidationRetries extra attempts (default 0).

stream

• stream(input, opts?): StreamTextResult

• Streams a user message and returns streaming iterables. The assistant reply is appended to session history once the text promise resolves. Accepts plain text or multimodal content (text + image parts).

  Parameters

  • input: MessageContent

    User message as text string or MessageContent array.
  • Optional opts: {
        abortSignal?: AbortSignal;
        budget?: SpendBudget | SpendBudgetOptions;
    }

    abortSignal ends this stream when it aborts, as SessionSendOptions.abortSignal ends a send: the provider's stream stops and the stream ends with an error part. The session stays open. budget takes the agent's place for this stream, as SessionSendOptions.budget takes it for a send.

    • Optional abortSignal?: AbortSignal

    • Optional budget?: SpendBudget | SpendBudgetOptions

  Returns StreamTextResult

  A StreamTextResult with async iterables and awaitable aggregates.

messages

• messages(): SessionTranscriptMessage[]

• Returns a snapshot of the current conversation transcript for this session in provider-replayable shape (assistant tool_calls, tool results with ids, thinking blocks). Suitable as checkpoint material for AgentSession.reseed.

  Returns SessionTranscriptMessage[]

reseed

• reseed(snapshot): void

• Atomically replaces the session history with a caller-built compact snapshot — the divergence-reset primitive. Bumps the history epoch: an in-flight send that began under an older epoch still returns to its caller, but its history append is discarded. Throws when the snapshot violates tool_use/tool_result pairing.

  Parameters

  • snapshot: SessionTranscriptMessage[]

  Returns void

drainHistoryEvents

• drainHistoryEvents(): HistoryEvent[]

• Returns accumulated history telemetry events (evictions, reseeds, stale-append discards) and clears the queue.

  Returns HistoryEvent[]

usage

• usage(): Promise<AgentOSUsageAggregate>

• Returns persisted usage totals for this session when the usage ledger is enabled.

  Returns Promise<AgentOSUsageAggregate>

recordExternalCost

• recordExternalCost(costUSD, meta?): void

• Charges a cost made outside AgentOS (speech-to-text minutes, a tool's own API) to the agent's budget; does nothing without one. With a budget, a cost of zero or below records nothing, and a cost that is not a number throws a RangeError.

  Parameters

  • costUSD: number
  • Optional meta: {
        kind?: string;
    }

    • Optional kind?: string

  Returns void

clear

• clear(): void

• Clears all messages from this session's history.

  Returns void

close

• close(): Promise<void>

• Ends this session and releases its history. A send still running is returned to its caller but added to no history, and the next agent.session(id) with this id starts empty. The id's usage totals stay readable through agent.usage(id). With runtime: 'gmi', a send or stream still running is stopped instead: its model call is aborted, its caller gets the abort error, and the steps it had finished stay in this session's messages(), marked partial; then the session's GMI is shut down.

  Returns Promise<void>

Readonly id