Agent SSE Event Reference

The MarkDocket agent streams its responses as a sequence of Server-Sent Events (SSE) over an HTTP POST connection. Each event carries a type field that identifies its role in the turn, plus a data payload. This page documents every event type your client may receive, the fields each carries, and how to handle them.

Event envelope

Every event in the stream follows the SSE wire format:

event: <type>
data: <JSON-encoded payload>

The data field is always a JSON object. The shape of that object depends on type, as described below.

Event types

text

A streaming prose chunk from the model. Multiple text events are emitted in sequence; concatenate their content fields in order to reconstruct the full assistant message.

Usage: Append each content fragment to your display buffer as it arrives for a typewriter effect. The stream of text events ends when the model has finished producing prose for the current reasoning step — further events of other types may still follow.

tool_call

Emitted when the model decides to invoke a tool. The agent has not yet executed the tool at this point — the event signals intent.

Usage: Use tool_call events to show the user which tools the agent is using and with what parameters. The toolName always matches a name from the published tool catalog. toolCallId is the correlation key — hold it until the matching tool_result arrives.

tool_result

Emitted after a tool call completes, carrying the result the agent received back. Every tool_call event will be followed by exactly one tool_result with the same toolCallId, unless the turn is cancelled or fails before the tool returns.

Usage: Match toolCallId to the earlier tool_call event to update your UI (for example, mark a tool-call card as completed or errored). When isError is true, the model will typically observe the error and decide whether to retry, use a different tool, or explain the failure in a subsequent text event.

vault_file

Emitted when the agent has saved a file to the user's Vault as part of the turn. This can occur after tools that produce downloadable artifacts (reports, draft documents, figures, and similar outputs).

Usage: Render a file attachment card in your UI when a vault_file event arrives. The user can then open or download the file using vaultFileId with the Vault file endpoint. More than one vault_file event may arrive in a single turn if the agent produces multiple artifacts.

billing_required

Emitted when the agent turn cannot proceed because a billing action is required — for example, the account has no remaining credits, or a plan upgrade is needed to use a particular capability. The turn stops after this event is emitted.

This event carries a BillingBlockEnvelope as its payload.

Usage: The billing_required event is the streaming equivalent of an HTTP 402 response — the same BillingBlockEnvelope shape is used at every layer of the platform (HTTP error bodies, automation signals, CLI output, and MCP structured errors), so you can handle it uniformly. Inspect requiredAction to determine which UI flow to present: a credits top-up, a plan upgrade, or a payment method update.

Turn lifecycle and event ordering

A normal agent turn produces events roughly in this order, though the exact sequence depends on how many tool calls the model makes:

1. One or more text events — the model's initial reasoning or response prose.
2. A tool_call event — the model requests a tool.
3. A tool_result event — the tool returns its output.
4. Steps 1–3 may repeat as the model reasons across multiple tool calls.
5. Zero or more vault_file events — if the turn produced saved artifacts.
6. A final text event — the model's concluding response.

If billing is blocked at any point, the sequence ends with a single billing_required event instead of completing normally.

Correlating events

All events include a turnId field that matches the turn identifier returned when the turn was submitted. Use turnId to associate streamed events with the correct conversation thread when multiple turns are in flight, and use toolCallId to pair each tool_call with its eventual tool_result.

Error handling summary

For billing errors specifically, the reason and requiredAction fields follow the platform's canonical billing contract — each reason maps to exactly one requiredAction, so you can drive UI flows deterministically from the event payload without additional API calls.