Interface: AgentSession
Defined in: packages/agentos/src/api/agent.ts:326
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:328
Stable session identifier supplied to or auto-generated by Agent.session().
Methods
clear()
clear():
void
Defined in: packages/agentos/src/api/agent.ts:389
Clears all messages from this session's history.
Returns
void
drainHistoryEvents()
drainHistoryEvents():
HistoryEvent[]
Defined in: packages/agentos/src/api/agent.ts:385
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:374
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
Defined in: packages/agentos/src/api/agent.ts:382
Atomically replaces the session history with a caller-built compact snapshot — the divergence-reset primitive (spec §1d). 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):Promise<GenerateTextResult>
Defined in: packages/agentos/src/api/agent.ts:338
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.
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:355
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 (real provider bug; not retried).
stream()
stream(
input):StreamTextResult
Defined in: packages/agentos/src/api/agent.ts:367
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.
Returns
A StreamTextResult with async iterables and awaitable aggregates.
usage()
usage():
Promise<AgentOSUsageAggregate>
Defined in: packages/agentos/src/api/agent.ts:387
Returns persisted usage totals for this session when the usage ledger is enabled.
Returns
Promise<AgentOSUsageAggregate>