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
readonlyid: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?
Returns
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>