---
title: "Agent run events"
description: "The events a Hercules Agent run emits: the event envelope, every event type, which events are durable, and how to stream a run live or replay it from a server."
image: "https://hercules.app/og/home"
---

# Agent run events

> The events a Hercules Agent run emits: the event envelope, every event type, which events are durable, and how to stream a run live or replay it from a server.

> **Note:** The Agents API is in beta, so things may change. See [Agents API](https://hercules.app/docs/agents/api) for credentials and
> versioning.

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](https://hercules.app/docs/agents/event-delivery).

### What does an event look like?

```json
{
  "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?

| 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](https://hercules.app/docs/agents/api-reference#the-message-object)              |
| `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`, 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](https://hercules.app/docs/agents/api-reference#the-message-object)'s tool call. `usage`, `error`, `output`, and `capped_reason` are the [Run](https://hercules.app/docs/agents/api-reference#the-run-object)'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](https://hercules.app/docs/agents/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](https://hercules.app/docs/agents/embed-chat#how-do-page-actions-work).

### How do I stream a run?

Ask for `text/event-stream`. Any credential works, including the run's own token:

```ts 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.

```ts 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](https://hercules.app/docs/agents/embed-chat).

### How do I replay a run from my server?

Ask for `application/json` with your app key or an Organization API key:

```bash 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](https://hercules.app/docs/agents/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.

Previous: [Agents API reference](https://hercules.app/docs/agents/api-reference)

Next: [Agent event delivery](https://hercules.app/docs/agents/event-delivery)

Every docs page is listed in [llms.txt](https://hercules.app/docs/llms.txt).

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://hercules.app/#organization",
      "name": "Hercules",
      "url": "https://hercules.app",
      "logo": {
        "@type": "ImageObject",
        "url": "https://hercules.app/logo-128.png"
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://hercules.app/docs#website",
      "name": "Hercules",
      "url": "https://hercules.app/docs",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      }
    },
    {
      "@type": "WebPage",
      "@id": "https://hercules.app/docs/agents/run-events#webpage",
      "url": "https://hercules.app/docs/agents/run-events",
      "name": "Agent run events",
      "description": "The events a Hercules Agent run emits: the event envelope, every event type, which events are durable, and how to stream a run live or replay it from a server.",
      "dateModified": "2026-11-16T21:16:56.000Z",
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "breadcrumb": {
        "@id": "https://hercules.app/docs/agents/run-events#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://hercules.app/docs/agents/run-events#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Hercules",
          "item": "https://hercules.app/docs"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Agent run events",
          "item": "https://hercules.app/docs/agents/run-events"
        }
      ]
    },
    {
      "@type": [
        "Article",
        "TechArticle"
      ],
      "@id": "https://hercules.app/docs/agents/run-events#article",
      "headline": "Agent run events",
      "name": "Agent run events",
      "description": "The events a Hercules Agent run emits: the event envelope, every event type, which events are durable, and how to stream a run live or replay it from a server.",
      "url": "https://hercules.app/docs/agents/run-events",
      "mainEntityOfPage": {
        "@id": "https://hercules.app/docs/agents/run-events#webpage"
      },
      "image": "https://hercules.app/og/home",
      "dateModified": "2026-11-16T21:16:56.000Z",
      "keywords": "run events, agent events, server-sent events, Last-Event-ID, message.delta, run.completed, event replay",
      "publisher": {
        "@id": "https://hercules.app/#organization"
      },
      "isPartOf": {
        "@id": "https://hercules.app/docs#website"
      },
      "inLanguage": "en-US"
    }
  ]
}
```
