> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and streaming

> See how SSE AG-UI transport, WebSocket notifications, and persisted run events work together.

SSE streams provide live output.

Durable events provide replay, resume, and recovery.

WebSocket notifications tell clients when related state changed.

```mermaid theme={null}
flowchart TB
  Runtime[Agent runtime] --> Chunk[Runtime chunk]
  Chunk --> Encoder[AG-UI encoder]
  Encoder --> Live[SSE response stream]
  Live --> Client[Client UI]
  Encoder --> Mirror[Durable event mirror]
  Mirror --> EventLog[(Durable event log)]
  EventLog --> Replay[Replay and follow]
  EventLog -.-> Notify[WebSocket notification]
  Notify -.-> Client
```

## Live transport

Conversation streams return `text/event-stream` for AG-UI execution.

Clients render text, tool calls, tool results, reasoning, and terminal state while the run is active.

## Durable event log

The durable mirror converts stream chunks into persisted run events.

Later reads can replay the event log or continue following a run.

Veryfront uses the [AG-UI events specification](https://docs.ag-ui.com/concepts/events) for streamed agent output.

## SSE run stream

The durable run stream returns `text/event-stream`.

It starts from the persisted event log.

It accepts `Last-Event-ID`, emits heartbeats, and closes after a terminal run event.

## AG-UI event reference

The public stream forwards these AG-UI event types.

| Event                       | Family    | Purpose                                  |
| --------------------------- | --------- | ---------------------------------------- |
| `RUN_STARTED`               | Lifecycle | Run began                                |
| `RUN_FINISHED`              | Lifecycle | Run completed successfully               |
| `RUN_ERROR`                 | Lifecycle | Run failed or was cancelled              |
| `TEXT_MESSAGE_START`        | Text      | Assistant message began                  |
| `TEXT_MESSAGE_CONTENT`      | Text      | Assistant text delta                     |
| `TEXT_MESSAGE_END`          | Text      | Assistant message ended                  |
| `TOOL_CALL_START`           | Tool      | Tool call began                          |
| `TOOL_CALL_ARGS`            | Tool      | Tool argument delta                      |
| `TOOL_CALL_CHUNK`           | Tool      | Tool-call chunk from compatible runtimes |
| `TOOL_CALL_END`             | Tool      | Tool call arguments ended                |
| `TOOL_CALL_RESULT`          | Tool      | Tool result or tool error                |
| `STATE_SNAPSHOT`            | State     | Full runtime state snapshot              |
| `STATE_DELTA`               | State     | Incremental runtime state update         |
| `MESSAGES_SNAPSHOT`         | State     | Full message snapshot                    |
| `REASONING_MESSAGE_START`   | Reasoning | Public reasoning message began           |
| `REASONING_MESSAGE_CONTENT` | Reasoning | Public reasoning message delta           |
| `REASONING_MESSAGE_END`     | Reasoning | Public reasoning message ended           |
| `CUSTOM`                    | Custom    | Named Veryfront extension event          |

## Custom event names

`CUSTOM` events use a constrained public name set.

| Name               | Purpose                                        |
| ------------------ | ---------------------------------------------- |
| `message-metadata` | Message metadata attached to streamed output   |
| `source-url`       | URL citation or source reference               |
| `source-document`  | Document citation or source reference          |
| `file`             | File reference emitted by a run                |
| `tool-call-status` | Tool execution status update                   |
| `stream-heartbeat` | Run stream heartbeat emitted during SSE follow |

## WebSocket notification events

WebSocket notifications are lightweight invalidation events. They do not carry AG-UI token deltas.

Clients use project event notifications to refresh child-run and message data.

| Event                    | Purpose                              |
| ------------------------ | ------------------------------------ |
| `message.created`        | Conversation message created         |
| `message.updated`        | Conversation message changed         |
| `message.status_changed` | Message status changed               |
| `message.deleted`        | Conversation message deleted         |
| `agent_run.created`      | Conversation-owned agent run created |
| `agent_run.updated`      | Conversation-owned agent run changed |
| `participant.joined`     | Participant joined a conversation    |
| `participant.left`       | Participant left a conversation      |
| `conversation.updated`   | Conversation metadata changed        |
| `typing.start`           | Participant started typing           |
| `typing.stop`            | Participant stopped typing           |