Everything a run does is an event: it starts, text streams in, a tool is called, the run ends. Stream a run's events live in the browser, replay them as JSON from your server, or receive the durable ones in your app through event delivery.
What does an event look like?
{
"id": "01JDX4M2...:42",
"seq": 42,
"run_id": "01JDX4M2...",
"thread_id": "01JDX4M1...",
"type": "run.progress",
"created_at": "2026-11-15T10:00:08.000Z",
"data": { "label": "Checking the order" }
}idis<run_id>:<seq>seqis the event's place in its run. It starts at 1 and goes up, but it skips numbers, on the stream as well as in a replay. Use it to order events and to resume, never to count them- Never drop a run's final event or a
message.completedfor itsseq. When Hercules has to end a run itself, the number it gives the ending can trail the stream by a few events, so it can be at or below a live-only event you already got. The stream always sends a finished run's final event datadepends ontype
Which events are there?
| Type | Durable | data |
|---|---|---|
run.queued | Yes | {}. Every run's first event |
run.started | Yes | {} |
message.delta | No, live only | { message_id, text }: the next piece of the reply |
message.appended | Best effort | { message_id, text }: the text written since the last checkpoint |
message.completed | Yes | { message }: the whole Message |
tool_call.started | No, live only | { tool_call_id, name, kind } |
tool_call.completed | Yes | { tool_call_id, name, kind, status, summary }, and result for an app tool that worked |
page_action | Yes | { tool_call_id, name, arguments } |
run.progress | Yes | { label }: what the Agent is doing, when no tool call says it |
run.completed | Yes | { output, usage } |
run.failed | Yes | { error, usage } |
run.cancelled | Yes | { usage } |
run.capped | Yes | { capped_reason, output, usage } |
- Every run ends with exactly one of
run.completed,run.failed,run.cancelled, orrun.capped. A run whose execution is lost is ended withrun.failedand the coderun_failedwithin a few minutes message.completedis sent only when the run stored a reply. A run that fails or is canceled before it writes one ends without it, so do not wait for it after amessage.deltaormessage.appended. When it comes, it replaces whatever those builtkind,status, andsummarymean what they do on a Message's tool call.usage,error,output, andcapped_reasonare the Run's- New event types can be added within a version, so skip the ones you don't know
Which events are durable?
- Durable events are kept with the run and delivered to your app at least once. Apply each
(run_id, seq)once - Live-only events (
message.delta,tool_call.started) are on the stream only, until 1 hour after the run ends message.appendedis best effort. It carries the text written since the last checkpoint, and is skipped when a delivery retry outlives the live stream. A replay as JSON leaves it out
What does a tool call carry?
tool_call.completed has the tool's name, its kind, how it went, and a summary:
summaryis one generic line made from the tool's name: "Ran save lead", "Couldn't run save lead", or "Sent open cart to the page". It never describes the arguments or the resultresultis what one of your app tools returned. It is left out for a failed call, and forherculestools and page actions- A
resultover 32,000 characters of JSON becomes{ "truncated": true, "preview": "..." }, with the first 32,000 characters as the preview - The arguments and results of
herculestools never leave Hercules
What does a run token see of tools?
A run token is made for the browser, so by default its stream hides what the Agent's tools did in detail:
- A
herculestool is namedtool, ontool_call.started,tool_call.completed, and the tool calls insidemessage.completed. Its summary reads "Used a tool", or "Couldn't use a tool" when it failed - No
tool_call.completedcarries aresult - Your app tools and page actions keep their names and summaries. Your app chose them
Start the run with expose_tool_details: true to leave its stream as it is: the names and summaries of hercules tools, and the result of your app tools. The results then travel to the browser, where the user can read them. Nothing else about an event changes either way, so a hidden stream lines up with the stored events by seq.
Events delivered to your app's backend, and events read with an app key or an Organization API key, always carry the full details.
What is a page action event?
A page action is one-way. When the Agent calls one, a durable page_action event carries the arguments, the call completes at once with the status sent, and the run carries on. Your page runs the action. Nothing goes back to the run.
Hercules checks the arguments against the page action's declared JSON Schema first. A call that does not match is not sent: there is no page_action event, its tool_call.completed has the status failed, and the Agent reads what was wrong and can call again. Arguments that pass arrive exactly as the Agent wrote them.
Run a page action only within 120 seconds of the event's created_at. An older one is stale: the user has moved on, so drop it. @usehercules/agents does this for you: your backend's clock decides when a tab claims the action, one tab runs each, and a late one is listed as expired for the page to tell the user. See Embed the chat.
How do I stream a run?
Ask for text/event-stream. Any credential works, including the run's own token:
async function openRunStream(live: { url: string; token: string }, lastSeq = 0) {
for (let attempt = 0; attempt < 10; attempt++) {
const response = await fetch(live.url, {
headers: {
Authorization: `Bearer ${live.token}`,
"Hercules-Version": "2025-12-09",
Accept: "text/event-stream",
// On a reconnect: the id of the last event you got.
...(lastSeq > 0 && { "Last-Event-ID": String(lastSeq) }),
},
});
if (response.ok && response.body !== null) return response.body;
// 429: the run already has 10 streams open. 5xx: Hercules could not answer.
// Anything else is a refusal that trying again will not change.
if (response.status !== 429 && response.status < 500) {
throw new Error(`The run's stream was refused with ${response.status}`);
}
const retryAfter = Number(response.headers.get("Retry-After"));
const waitSeconds = retryAfter > 0 ? retryAfter : 2 ** Math.min(attempt, 5);
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
throw new Error("The run's stream could not be opened");
}- Check the status before you read the body. A refusal is a problem details JSON body, not a stream
- A run takes 10 streams at once. One more is a 429
rate_limitedwithRetry-After: 5: wait that long and try again, or do without the live view and read the reply from your backend - You get every event after
after, or after theLast-Event-IDheader when you reconnect. Either one that is not a whole number from 0 to 2147483647 is a 400invalid_request - A finished run always answers with its ending. When no event is left after your cursor, because it is at or past the run's last
seq, the stream sends the run'smessage.completedagain, if the run stored a reply, and then its final event. For a run whose last two events aremessage.completedat 20 and the final event at 21, a cursor of 21 or more gets both, and a cursor of 20 gets the final event alone. So a late reader always gets the reply, and you may get these two events twice: apply each(run_id, seq)once - Each server-sent event's
idis the event'sseq, and itsdatais the event as JSON - A
: keep-alivecomment line arrives every 15 seconds, to keep the connection open. It is not an event - The stream closes after the run's final event. It also closes after 10 minutes without one, so reconnect with
Last-Event-IDuntil you get a final event - Use
fetch.EventSourcecannot send theAuthorizationandHercules-Versionheaders the route needs - A run token works only for
text/event-stream. WithAccept: application/jsonit is a 401invalid_run_token, and on every other route a 401credential_required - Until 1 hour after the run ends, the stream includes live-only events. After that, it replays durable events only, and the run's token no longer works
- When the run's thread is deleted, the stream ends, and the token is refused from then on
followRun from @usehercules/agents does all of this: it reads the stream with fetch, waits as Retry-After says, reconnects with Last-Event-ID, and ends after the run's final event.
import { followRun } from "@usehercules/agents";
export async function readReply(live: { url: string; token: string }) {
let text = "";
for await (const event of followRun({ url: live.url, token: live.token })) {
if (event.type === "message.delta") text += event.data.text;
if (event.type === "message.completed") {
// The whole reply: it replaces the text the deltas built.
text = event.data.message.parts
.map((part) => (part.type === "text" ? part.text : ""))
.join("");
}
}
return text;
}It throws a RunStreamError when Hercules refuses the stream, and after 10 failed connections in a row. Its status and code are the last answer's, such as 429 and rate_limited when the run's 10 streams stayed taken. The error is about the live view, not the run: the run carries on, and its reply still reaches your backend.
In a Convex app, herculesConnection and useAgentThread use followRun for you. See Embed the chat.
How do I replay a run from my server?
Ask for application/json with your app key or an Organization API key:
curl "https://api.hercules.app/v1/agents/runs/$RUN_ID/events?after=0&limit=100" \
-H "Authorization: Bearer $HERCULES_API_KEY" \
-H "Hercules-Version: 2025-12-09" \
-H "Accept: application/json"It answers { "data": [...], "has_more": false } with the durable events after after, oldest first. For the next page, pass the last event's seq as after. A page after the run's last event is empty: only the stream repeats a finished run's ending.
Additional FAQ
Can I see what a tool was called with?
For a page action, page_action carries the arguments. For your own app
tools, tool_call.completed carries the result, and your tool's handler saw
the arguments when it ran. Tools that run inside Hercules (kind hercules) show a name and a
summary only.
Why does seq skip numbers?
seq orders a run's events. It is not a count. A replay holds the durable events only, so it
skips the numbers of live-only events such as message.delta, and the run's last events can skip
numbers on the stream too. Resume from the last seq you got, whatever the next one is, and
always take a final event or a message.completed, whatever its seq.
Does every run reach a final event?
Yes. A run that stops without one, because its execution was lost, is ended as failed with the
code run_failed within a few minutes.