Agents

Sessions

A session is a conversation with private context. Continue it with another run, rename it, or delete it.

What a session holds

Every run belongs to a session. A run without session_id starts a new one; a run with it continues the conversation with the agent's private context replayed, so a follow-up can say "now do the same for the second page".

A session fixes:

the model connection (connection, model, protocol, endpoint) — its credential may be replaced before a later run, the identity may not;
the Workspace the runs read and write;
the network route (direct, managed or custom) — a continuation without network inherits it, and an existing browser must match it;
the credentials and navigation policy the first run named — a different set is conflict;
the output schema, when the first run had one;
the integrations selected, with their revisions — omit integration_ids to inherit.

Raw traces are private: the API returns the session's metadata and runs, never the transcript.

Routes

Method and path	Result
`GET /v1/agent-sessions`	The project's sessions, newest first
`GET /v1/agent-sessions/{id}`	Metadata and runs
`PATCH /v1/agent-sessions/{id}`	`{ "title": "…" }` (1–200 characters); `execute` role
`DELETE /v1/agent-sessions/{id}`	Soft delete: the session leaves the lists and answers `not_found` afterwards; its runs stay readable and counted in Usage, and its Workspace is untouched. A run in flight is cancelled first; deleting twice answers the same
`POST /v1/agent-sessions/{id}/purge`	Zero-data-retention projects only (`403 zero_data_retention_required` otherwise): destroys the session's content — run events, trace, the Workspace files its runs wrote, downloads and recordings — and redacts the task, output and title; ids, times and usage stay. `202` while its work is still live (finished automatically)

Continuing in code

first = client.run("Open https://example.com and list the headings.")follow = client.run("Now open the first link and do the same.", session_id=first["session_id"])

first = client.run("Open https://example.com and list the headings.")
follow = client.run("Now open the first link and do the same.", session_id=first["session_id"])

const first = await client.run('Open https://example.com and list the headings.');const follow = await client.run('Now open the first link and do the same.', { session_id: first.session_id });

const first = await client.run('Open https://example.com and list the headings.');
const follow = await client.run('Now open the first link and do the same.', { session_id: first.session_id });

A session whose model connection was deleted, or one recorded before endpoint identities were kept, remains readable but cannot be continued (conflict); start a new session.

Context compaction

When the session's model connection declares a context_window (project connections: context_window on the model; the platform model: the operator's STEALTH_AGENT_CONTEXT_WINDOW), the agent compacts the transcript once a request reaches about 60% of the window: one summarising model request, counted in usage, replaces the transcript with a summary carried as [context_summary]. The run's events show agent.compaction (phase begin/end, reason, mode, status), and a continued session resumes from the summary. Without a declared window there is no compaction; a session's private trace is bounded at 4000 messages / 2 MB.