SSE Streaming Format

Agent execution and live session monitoring use Server-Sent Events (SSE) for real-time streaming.

Agent Execution Stream

When executing an agent via POST /api/v2/agents/:agent_id/stream, the response is an SSE stream with the following event types:

event: metadata
data: {"request_id":"uuid","agent_id":"uuid","session_id":null,"tenant_id":"uuid"}

event: status
data: {"phase":"STARTING","timestamp":"2026-01-13T19:00:00.000Z"}

event: phase
data: {"phase":"EXECUTE"}

event: tool
data: {"tool":"zigma_list_contracts","call_id":"uuid","success":true,"result_summary":"5 contracts found"}

event: thinking
data: {"thought":"Processing data..."}

event: response
data: {"content":"Found 5 active contracts...","sources":[]}

event: metrics
data: {"usage":{"input_tokens":150,"output_tokens":200,"total_tokens":350,"cost_usd":0.001},"iterations":2,"execution_time_ms":3500}

data: [DONE]

Event Types

Event	Description	Key Fields
metadata	Request information	request_id, agent_id, session_id, tenant_id
status	Initial status or processing phase	phase, timestamp
attachments	Attachment processing results	processed, errors
phase	Phase change	phase: STARTING, PROCESSING_ATTACHMENTS, EXECUTE, RESPOND
tool	Tool call executed	tool, call_id, success, result_summary
thinking	Agent reasoning	thought
response	Final response	content, sources
metrics	Execution metrics	usage, iterations, execution_time_ms
warning	Non-fatal warning	message
error	Execution error	code, message

---

Live Session Stream

Monitor agent executions in real-time via GET /api/v1/sessions/:executionId/live.

Events

Event	Description	Key Fields
snapshot	Current state on connect	executionId, phase, agentId, startedAt
session:start	Session started	tenantId, agentId, userId, source
session:phase	Phase change	phase: PREPROCESSING, EXECUTE, RESPOND
session:tool	Tool execution	tool, success, result
session:thinking	Agent reasoning	thought
session:linked	Persistent session ID resolved	sessionId
session:complete	Execution completed	contentPreview, usage, iterations, executionTimeMs
session:error	Execution error	error

Live to Detail Navigation

When you receive the session:linked event, you get the persistent sessionId that can be used to navigate to the session detail view. Before this event, sessionId is null.

Timeout: The SSE stream closes automatically after 5 minutes or when the session finishes.

---

Consuming SSE in Code

JavaScript (Browser):

const eventSource = new EventSource('/api/v1/sessions/exec-123/live', {
  headers: { 'Authorization': 'Bearer <jwt>' }
});

eventSource.addEventListener('session:tool', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Tool ${data.tool}: ${data.success ? 'OK' : 'FAILED'}`);
});

eventSource.addEventListener('session:complete', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Done in ${data.executionTimeMs}ms`);
  eventSource.close();
});

cURL:

curl -N "https://llm.zihin.ai/api/v2/agents/AGENT_ID/stream" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "List active contracts"}'