Skip to main content

Interface: AgentSession

Defined in: packages/agentos/src/api/agent.ts:551

A named conversation session returned by Agent.session(). Maintains its own message history independently of other sessions on the same agent.

Properties​

id​

readonly id: string

Defined in: packages/agentos/src/api/agent.ts:553

Stable session identifier supplied to or auto-generated by Agent.session().

Methods​

clear()​

clear(): void

Defined in: packages/agentos/src/api/agent.ts:626

Clears all messages from this session's history.

Returns​

void


close()​

close(): Promise<void>

Defined in: packages/agentos/src/api/agent.ts:636

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>


drainHistoryEvents()​

drainHistoryEvents(): HistoryEvent[]

Defined in: packages/agentos/src/api/agent.ts:616

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

Returns​

HistoryEvent[]


messages()​

messages(): SessionTranscriptMessage[]

Defined in: packages/agentos/src/api/agent.ts:605

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[]


recordExternalCost()​

recordExternalCost(costUSD, meta?): void

Defined in: packages/agentos/src/api/agent.ts:624

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

meta?​
kind?​

string

Returns​

void


reseed()​

reseed(snapshot): void

Defined in: packages/agentos/src/api/agent.ts:613

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


send()​

Call Signature​

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

Defined in: packages/agentos/src/api/agent.ts:564

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.

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.

Call Signature​

send<S>(input, opts): Promise<SessionSendStructuredResult<output<S>>>

Defined in: packages/agentos/src/api/agent.ts:581

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​

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

Parameters​
input​

MessageContent

User message as text string or MessageContent array.

opts​

SessionSendOptions<S> & object

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

Defined in: packages/agentos/src/api/agent.ts:598

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.

opts?​

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. guards are enforced on this stream, as on streamText(); a turn whose input a guard rewrote or replaced is not added to the history.

abortSignal?​

AbortSignal

budget?​

SpendBudget | SpendBudgetOptions

guards?​

TextGuardrailOptions

Returns​

StreamTextResult

A StreamTextResult with async iterables and awaitable aggregates.


usage()​

usage(): Promise<AgentOSUsageAggregate>

Defined in: packages/agentos/src/api/agent.ts:618

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

Returns​

Promise<AgentOSUsageAggregate>