Web Handbook

Understanding the AG-UI Protocol and SSE Event Streams

Author

Kav AI

Published

April 5, 2026

1 Introduction

The KAP Frontend (Web) and AI Backend (Server) communicate using a real-time, event-driven protocol based on Server-Sent Events (SSE). This “AG-UI” protocol ensures that agent reasoning, tool execution, and rich media results are streamed to the user with zero latency.

1.1 🏗️ Communication Flow

The web client initiates a chat by sending a POST request to the streaming endpoint. The AI server then responds with an open SSE connection.

  • Endpoint: /chat/agui/stream
  • Method: POST
  • Headers:
    • Authorization: Bearer <JWT_TOKEN>
    • Content-Type: application/json

1.1.1 Request Payload (ChatRequest)

{
  "message": "List my datasets",
  "system_type": "adk",
  "threadId": "user-thread-001",
  "runId": "optional-uuid"
}

1.2 🚦 Standard Event Lifecycle

All runs follow a strict event sequence to manage UI state transitions.

Event Type Purpose Key Fields
RUN_STARTED Signal start of execution. runId, threadId
TEXT_MESSAGE_START Start a new assistant response. messageId, role
TEXT_MESSAGE_CONTENT Incremental tokens/deltas. delta
TEXT_MESSAGE_END End of current message unit. messageId
RUN_FINISHED Mark end of full execution. result (metadata)
RUN_ERROR Handle backend failures. error (code, message)

1.3 🛠️ Tool Execution Visibility

KAP exposes tool calls to the AG-UI so users can see the “inner monologue” of the agents.

  1. TOOL_CALL_START: Name of the tool (e.g., list_datasets).
  2. TOOL_CALL_ARGS: Incremental JSON arguments.
  3. TOOL_CALL_END: Signal arguments are complete.
  4. TOOL_CALL_RESULT: The stringified output from the tool.

1.4 🎨 Custom KAP Events

KAP extends the base AG-UI protocol with specialized CUSTOM events for our domain-specific viewers.

1.4.1 1. DATASET_LIST

Used to render the RLS-filtered list of available datasets (Argus/Orion).

  • Payload: {"datasets": [{"id": "uuid", "name": "...", "slug": "..."}]}

1.4.3 3. MARKDOWN_REPORT

Rich interactive reports with embedded component directives.

  • Directives: [[dataset-list:id]] or [[image-gallery:id]] are parsed by the frontend to inject live interactive components into the static markdown.

1.4.4 4. IMAGE_ANOMALIES

Structured detection results primarily used by Orion for anomaly visualization.

  • Payload: {"anomalies": [{"bbox": [x, y, w, h], "category": "Surface Stains"}]}

1.5 🧠 State Synchronization

The AI server can sync complex agent state (e.g., progress bars, current step) via:

  • STATE_SNAPSHOT: A full replacement of the client-side agent state.
  • STATE_DELTA: Incremental updates using JSON Patch (RFC 6902) format.

1.6 ⚛️ Frontend Consumer (useAguiEvents)

The React frontend uses a specialized hook to parse the SSE stream and dispatch events to the Redux store or local state.

  • Reconnection: Automatic retry on connection drop.
  • Message Buffering: Tokens are buffered and flushed to ensure smooth text animations.
  • Event Dispatching: Custom events are routed to dedicated slice handlers (e.g., gallerySlice).

Last Updated: 2026-04-05