---
title: "Per-session agent event stream (SSE)"
method: GET
path: "/v1/agent/stream"
tags: ["Agent"]
---

# Per-session agent event stream (SSE)

`GET /v1/agent/stream`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/agent/stream`
- Auth: HTTP bearer

Server-Sent Events stream of one agent session's frames — token
deltas, tool-call proposals (`approvalRequired` is reserved for the
server-side approval protocol; a proposal a firewall Ask rule asks for
names that rule in `approvalRule`, one that asks because an update reset
an earlier Allow carries `updatedSinceAllowed: true`, and one that asks lists
the answers its prompt may offer in `offeredAnswers`), tool results (carrying the produced
Asset `structured` payload, the result's by-reference `resourceLinks`
`[{uri, name, mimeType}]`, and `fileMutation` pre/post snapshots for
file mutations), `tool-progress` frames (live 0…1 `fraction` of an
awaited async-verb job while the kernel holds the call open),
cost frames, and the terminal turn-ended marker.
Between turns the stream also carries `work-delivered` frames — a
conversation-scoped background job's terminal result injected by the
server with no turn open (`{workId, verb, jobId, outputAssetId,
asset, isError, text}`, mirroring `job_result`; `text` is the exact
bracketed marker appended to the durable conversation transcript).
A completion landing mid-turn queues and drains immediately after
that turn's terminal frame, so `turn-ended` remains the last frame
OF a turn while the subscription itself is worth holding open
between turns.
Each frame carries a monotonic per-session `id:`; reconnect with
`Last-Event-ID` (or `lastEventId=` query param) to replay missed
frames from the session's bounded ring buffer. Scoped: a subscriber
sees only the named session's frames.

## Query parameters

- `session` string, required
- `lastEventId` integer

## Response `200`

SSE stream of agent session frames

## Other responses

- `404`: No conversation with this id, in memory or on disk. A conversation that is only on disk (evicted, or from before a restart) rehydrates and streams.

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)