Skip to main content

Interface: AgentSession

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

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:246

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

Methods​

clear()​

clear(): void

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

Clears all messages from this session's history.

Returns​

void

messages()​

messages(): Message[]

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

Returns a snapshot of the current conversation history for this session.

Returns​

Message[]

send()​

Call Signature​

send(input): Promise<GenerateTextResult>

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

Sends a user message and returns the complete assistant reply. Appends both turns to the session history when memory is enabled. 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:272

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:284

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​

StreamTextResult

A StreamTextResult with async iterables and awaitable aggregates.

usage()​

usage(): Promise<AgentOSUsageAggregate>

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

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

Returns​

Promise<AgentOSUsageAggregate>