Hercules

DevelopersRun events

Developers

Agent run events

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" }
}
  • id is <run_id>:<seq>
  • seq is 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.completed for its seq. 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
  • data depends on type

Which events are there?

TypeDurabledata
run.queuedYes{}. Every run's first event
run.startedYes{}
message.deltaNo, live only{ message_id, text }: the next piece of the reply
message.appendedBest effort{ message_id, text }: the text written since the last checkpoint
message.completedYes{ message }: the whole Message
tool_call.startedNo, live only{ tool_call_id, name, kind }
tool_call.completedYes{ tool_call_id, name, kind, status, summary }, and result for an app tool that worked
page_actionYes{ tool_call_id, name, arguments }
run.progressYes{ label }: what the Agent is doing, when no tool call says it
run.completedYes{ output, usage }
run.failedYes{ error, usage }
run.cancelledYes{ usage }
run.cappedYes{ capped_reason, output, usage }
  • Every run ends with exactly one of run.completed, run.failed, run.cancelled, or run.capped. A run whose execution is lost is ended with run.failed and the code run_failed within a few minutes
  • message.completed is 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 a message.delta or message.appended. When it comes, it replaces whatever those built
  • kind, status, and summary mean what they do on a Message's tool call. usage, error, output, and capped_reason are 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.appended is 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:

  • summary is 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 result
  • result is what one of your app tools returned. It is left out for a failed call, and for hercules tools and page actions
  • A result over 32,000 characters of JSON becomes { "truncated": true, "preview": "..." }, with the first 32,000 characters as the preview
  • The arguments and results of hercules tools 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 hercules tool is named tool, on tool_call.started, tool_call.completed, and the tool calls inside message.completed. Its summary reads "Used a tool", or "Couldn't use a tool" when it failed
  • No tool_call.completed carries a result
  • 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:

Stream a run in the browser
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_limited with Retry-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 the Last-Event-ID header when you reconnect. Either one that is not a whole number from 0 to 2147483647 is a 400 invalid_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's message.completed again, if the run stored a reply, and then its final event. For a run whose last two events are message.completed at 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 id is the event's seq, and its data is the event as JSON
  • A : keep-alive comment 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-ID until you get a final event
  • Use fetch. EventSource cannot send the Authorization and Hercules-Version headers the route needs
  • A run token works only for text/event-stream. With Accept: application/json it is a 401 invalid_run_token, and on every other route a 401 credential_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.

Follow a run to its end
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:

Replay a run's events
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.