SSE Events

AEGIS uses Server-Sent Events (SSE) to stream real-time updates from agent executions, workspace assessments, and conversation interactions.

Connection Setup

SSE endpoints return a stream of text/event-stream content. Connect using the standard EventSource API or any SSE client.


const token = 'your-jwt-token';
const eventSource = new EventSource(
  'http://localhost:8000/conversations/{conversation_id}/stream',
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);
 
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.event_type, data);
};
 
eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
  eventSource.close();
};


# Using curl
curl -N -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/conversations/{conversation_id}/stream

SSE Endpoints

Endpoint	Purpose
`GET /conversations/{id}/stream`	Stream conversation events (agent responses, tool calls)
`GET /workspaces/{checklist_id}/stream`	Stream workspace assessment events

Event Format

Each SSE event is a JSON object with an event_type field:


data: {"event_type": "agent_status", "status": "thinking", "node": "initial_llm_call"}

data: {"event_type": "checklist_item_update", "item_index": 2, "status": "complete"}

Conversation Events

Events emitted during agent conversation streaming:

Event Type	Description	Key Fields
`agent_status`	Agent processing state change	`status` (thinking, calling_tool, synthesizing), `node`
`token`	Streaming text token	`content` (partial text)
`tool_call`	Agent invoked a tool	`tool_name`, `arguments`
`tool_result`	Tool execution completed	`tool_name`, `result`
`error`	Processing error	`message`, `code`
`done`	Stream complete	`final_response`

Example: Conversation Stream


data: {"event_type": "agent_status", "status": "thinking", "node": "system_prompt_node"}
data: {"event_type": "agent_status", "status": "thinking", "node": "memory_node"}
data: {"event_type": "agent_status", "status": "thinking", "node": "initial_llm_call"}
data: {"event_type": "token", "content": "Based on "}
data: {"event_type": "token", "content": "the spacing "}
data: {"event_type": "token", "content": "analysis..."}
data: {"event_type": "tool_call", "tool_name": "spacing_calculation", "arguments": {"well_api": "42-123-45678"}}
data: {"event_type": "tool_result", "tool_name": "spacing_calculation", "result": {"min_distance_ft": 340}}
data: {"event_type": "agent_status", "status": "synthesizing", "node": "synthesis_llm_call"}
data: {"event_type": "token", "content": "The proposed well is 340 feet..."}
data: {"event_type": "done", "final_response": "...complete response text..."}

Workspace Events

Events emitted during entity compliance workspace assessments:

Event Type	Description	Key Fields
`checklist_item_update`	Checklist item status changed	`item_index`, `status`, `label`
`artifact_generated`	Document/artifact produced	`item_index`, `artifact_type`, `artifact_id`
`data_table_update`	Data table populated/updated	`item_index`, `rows`, `columns`
`form_field_update`	Form field value set	`item_index`, `field_name`, `value`
`validation_result`	Compliance check completed	`rule`, `passed`, `message`
`spatial_update`	Map/spatial data updated	`coordinates`, `features`
`agent_status`	Agent processing status	`status`, `phase`
`assessment_complete`	Full assessment finished	`summary`, `risk_level`

Example: Workspace Assessment Stream


data: {"event_type": "agent_status", "status": "assessing", "phase": "data_collection"}
data: {"event_type": "checklist_item_update", "item_index": 0, "status": "in_progress", "label": "Well Data Review"}
data: {"event_type": "data_table_update", "item_index": 0, "rows": [...], "columns": ["API", "Operator", "Distance"]}
data: {"event_type": "checklist_item_update", "item_index": 0, "status": "complete"}
data: {"event_type": "checklist_item_update", "item_index": 1, "status": "in_progress", "label": "Spacing Analysis"}
data: {"event_type": "validation_result", "rule": "Rule 37 Spacing", "passed": false, "message": "340ft < 467ft minimum"}
data: {"event_type": "artifact_generated", "item_index": 1, "artifact_type": "spacing_report", "artifact_id": "art-123"}
data: {"event_type": "checklist_item_update", "item_index": 1, "status": "complete"}
data: {"event_type": "assessment_complete", "summary": "2 of 5 checks passed", "risk_level": "high"}

Reconnection

The browser’s built-in EventSource automatically reconnects on connection drops. If using a custom SSE client, implement reconnection with exponential backoff.

If the connection drops:

Wait 1 second, then reconnect
Double the wait on each subsequent failure (max 30 seconds)
The server does not replay missed events — reconnection starts from the current state

Error Events

If an error occurs during streaming, the server emits an error event before closing:


data: {"event_type": "error", "message": "Budget exceeded: 150000 token limit reached", "code": "BUDGET_EXCEEDED"}

Common error codes:

Code	Description
`BUDGET_EXCEEDED`	Agent token or cost budget exhausted
`TOOL_FAILURE`	A tool call failed during execution
`APPROVAL_TIMEOUT`	HITL approval request timed out
`INTERNAL_ERROR`	Unexpected server-side error