Interface SeatHandle

A roster member that runs one session of its own; built by sessionSeat and by launch_agency. Its first call opens the session, and fails when the member already serves a session under the seat's id: generate() rejects and stream() throws, with the TypeError that names the id (a launch's seat, with that error's name alone).

Of the per-call options an agency passes to its members, a seat applies the call's abortSignal, budget and tool-approval gate, and on generate() the per-send generation overrides a session's send takes (maxTokens, requestTimeout, toolChoice, cacheDiagnostics, cache); its session's stream() takes none of those. Its member's own ledger records the seat's calls, so a call's usageLedger is not applied. The seat warns once about each other per-call option it is given (temperature, model, provider and the rest), which its member's own settings replace.

interface SeatHandle {
    seatId: string;
    record(): LaunchSeatRecord;
    generate(prompt, opts?): Promise<unknown>;
    stream(prompt, opts?): AgentStreamResult;
    session(id?): unknown;
    usage(sessionId?): Promise<unknown>;
    close(): Promise<void>;
    listen?(opts?): Promise<{
        port: number;
        url: string;
        close: (() => Promise<void>);
    }>;
    connect?(): Promise<void>;
    export?(metadata?, options?): unknown;
    exportJSON?(metadata?, options?): string;
    description?: string;
    dependsOn?: string[];
}

Hierarchy (view full)

Methods

record generate stream session usage close listen? connect? export? exportJSON?

Properties

seatId description? dependsOn?

Methods

record

generate

  • generate(prompt, opts?): Promise<unknown>

  • Generates a single reply (non-streaming).

    Parameters

    • prompt: string

      User prompt text.

    • Optional opts: Record<string, unknown>

      Optional per-call overrides.

    Returns Promise<unknown>

    The complete generation result including text, usage, and tool calls.

stream

  • stream(prompt, opts?): AgentStreamResult

  • Streams a reply, returning a streaming result surface.

    Single agents return a StreamTextResult with textStream, text, usage, and toolCalls. Agencies return an AgencyStreamResult with additional agentCalls, parsed, and finalTextStream fields. Both are assignable to AgentStreamResult.

    Parameters

    • prompt: string

      User prompt text.

    • Optional opts: Record<string, unknown>

      Optional per-call overrides.

    Returns AgentStreamResult

    A streaming result with at least textStream, fullStream, text, and usage.

session

  • session(id?): unknown

  • Returns (or creates) a named conversation session.

    Parameters

    • Optional id: string

      Optional session identifier; auto-generated when omitted.

    Returns unknown

    The session object for this ID.

usage

  • usage(sessionId?): Promise<unknown>

  • Returns cumulative usage totals for the agent or a specific session.

    Parameters

    • Optional sessionId: string

      Optional session filter.

    Returns Promise<unknown>

close

  • close(): Promise<void>

  • Releases all in-memory state held by this agent.

    Returns Promise<void>

Optional listen

  • listen(opts?): Promise<{
        port: number;
        url: string;
        close: (() => Promise<void>);
    }>

  • Starts a loopback WebSocket listener on 127.0.0.1 that exchanges JSON text: { "text": "..." } in, { "text": "..." } out, one request at a time per connection. It performs no speech recognition or synthesis; a binary frame receives an audio_not_supported error and close code 1003. Present on agency instances created with voice: { enabled: true }. Spoken calls use VoiceSessionFactory.

    Parameters

    • Optional opts: {
          port?: number;
      }

      Listener options; port 0, the default, picks a free port.

      • Optional port?: number

    Returns Promise<{
        port: number;
        url: string;
        close: (() => Promise<void>);
    }>

    Resolves to the bound port, URL, and a close() teardown function.

Optional connect

  • connect(): Promise<void>

  • Connects the agent to configured channel adapters (e.g. Discord, Slack). Present on agency instances only.

    Returns Promise<void>

Optional export

  • export(metadata?, options?): unknown

  • Exports the agent's full configuration as a portable object.

    The returned AgentExportConfig (imported from ./agentExport.js) can be serialized to JSON or YAML and re-imported via importAgent().

    Parameters

    • Optional metadata: Record<string, unknown>

      Optional human-readable metadata to attach.

    • Optional options: {
          redactSecrets?: boolean;
      }

      Redaction options; secrets are redacted unless redactSecrets is false.

      • Optional redactSecrets?: boolean

    Returns unknown

    A portable config object.

Optional exportJSON

  • exportJSON(metadata?, options?): string

  • Exports the agent's full configuration as a pretty-printed JSON string.

    Parameters

    • Optional metadata: Record<string, unknown>

      Optional human-readable metadata to attach.

    • Optional options: {
          redactSecrets?: boolean;
      }

      Redaction options; secrets are redacted unless redactSecrets is false.

      • Optional redactSecrets?: boolean

    Returns string

    JSON string with 2-space indentation.

Properties

Readonly seatId

seatId: string

The seat's session id on its member.

Optional description

description?: string

What a hierarchical manager reads about the seat; without it the manager sees "General purpose".

Optional dependsOn

dependsOn?: string[]

Seats this one waits for under the graph strategy. An agency that names no strategy and is not adaptive runs graph when any seat's dependsOn lists a seat; an empty list lists none. agency() throws AgencyConfigError, naming the seat, for a dependsOn that is set and is not an array of seat names.

Settings

Member Visibility

Theme

On This Page

recordgeneratestreamsessionusagecloselistenconnectexportexportJSONseatIddescriptiondependsOn