Session state

Long, structured conversations need somewhere to keep progress: which intake questions are answered, what stage the call is in, what the caller already confirmed. Session state is a durable key-value store attached to the session — the agent writes it through tools, the server owns it, and your client observes every change as an event.

Because the server owns the state, it survives things your process doesn't control: transport reconnects, upstream model-session rotations, even continuation into a resumed session.

Enabling it

Opt the agent into the two state tools. They have no typed kinds yet; in TypeScript they use the deprecated generic server-tool reference (see Server tools). The Python SDK no longer ships the generic reference, so writing session state is TypeScript-only until the typed kinds land:

import { COSMO_SET_STATE_TOOL, COSMO_VIEW_STATE_TOOL } from 'cosmo-ai/cosmo';

const agent = client.agent({
  instructions: '…',
  tools: [
    { kind: 'server', name: COSMO_SET_STATE_TOOL },
    { kind: 'server', name: COSMO_VIEW_STATE_TOOL },
  ],
});

cosmo.set_state writes keys; cosmo.view_state lets the agent re-read the current state. Tell the model in the instructions what to track — the tools give it the means, the instructions give it the discipline.

Observing changes

Every successful write pushes a cosmo.session-state event to the client with the full state, the updated_keys of this write, any warnings, and stage (hoisted from state["stage"] because "what phase is the call in" is the single most common thing UIs need):

session.on('session_state', ({ state, updatedKeys, stage }) => {
  setProgress(stage);              // drive a stepper, checklist, or CRM panel
  console.log('updated:', updatedKeys);
});

In Python and Swift, watch for the state event on the session's event stream (surfaced under the first-party cosmo.* event family; unrecognized first-party events arrive as unknown rather than erroring — TypeScript is the SDK with first-class typed support today).

What it's for — and not for

State is per-session. If you need the values after the call, capture the final cosmo.session-state event (or read the recorded artifacts — see Recording & privacy).