Skip to main content

Web/AI Contract Handbook

Understanding the AG-UI Protocol and SSE Event Streams

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.

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

Request Payload (ChatRequest)​

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

Standard Event Lifecycle​

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

Event TypePurposeKey Fields
RUN_STARTEDSignal start of execution.runId, threadId
TEXT_MESSAGE_STARTStart a new assistant response.messageId, role
TEXT_MESSAGE_CONTENTIncremental tokens/deltas.delta
TEXT_MESSAGE_ENDEnd of current message unit.messageId
RUN_FINISHEDMark end of full execution.result (metadata)
RUN_ERRORHandle backend failures.error (code, message)

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.

Custom KAP Events​

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

DATASET_LIST​

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

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

Used to trigger the high-performance image viewer.

  • Payload: {"images": [{"id": "...", "url": "...", "thumbnail_url": "..."}], "metadata": {"total_count": 42}}

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.

IMAGE_ANOMALIES​

Structured detection results primarily used by Orion for anomaly visualization.

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

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.

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