Run Agent (Streaming)

POST /api/v1/agents/:agentId/run-stream — execute an agent and stream the response as Server-Sent Events.

Runs an agent the same way as /run, but streams the response as it's generated instead of waiting for the full reply.

POST /api/v1/agents/{agentId}/run-stream

Path parameters

Parameter	Type	Description
`agentId`	string (UUID)	The agent to run.

Request body

Identical to /run: message (required), session_id, user_id, tag, tool_context.

200 OK, Content-Type: text/event-stream. Each event is a data: <json>\n\n line. Every event carries a common base — event, runId, agentId, agentName, sessionId, userId, createdAt (unix seconds) — plus event-specific fields.

Event sequence

RunStarted → ModelRequestStarted → RunContent (×N) → ModelRequestCompleted → RunContentCompleted → RunCompleted

Event	Extra fields	Description
`RunStarted`	—	The run has been accepted and started.
`ModelRequestStarted`	—	The underlying LLM call has begun.
`RunContent`	`content`	One chunk of generated text. Emitted once per token/delta — expect many of these per run.
`ModelRequestCompleted`	—	The LLM call finished.
`RunContentCompleted`	—	All content chunks have been emitted.
`RunCompleted`	`content` (full text), `metrics`	Terminal event. `content` is the complete reconstructed response; `metrics` has the same shape as `/run`'s response (`inputTokens`, `outputTokens`, `latencyMs`, `model`, `failoverUsed`).

data: {"event":"RunContent","runId":"b7e1...","agentId":"3f9c...","agentName":"Support Bot","sessionId":"a1c4...","userId":"d92e...","createdAt":1732550123,"content":"Hello"}

data: {"event":"RunCompleted","runId":"b7e1...","agentId":"3f9c...","agentName":"Support Bot","sessionId":"a1c4...","userId":"d92e...","createdAt":1732550124,"content":"Hello! How can I help you today?","metrics":{"inputTokens":12,"outputTokens":9,"latencyMs":842,"model":null,"failoverUsed":false}}

Error event

If the run fails at any point, an error event replaces the rest of the sequence — it's always terminal, and no further events follow it:

data: {"event":"error","runId":"b7e1...","agentId":"3f9c...","agentName":"Support Bot","sessionId":"a1c4...","userId":"d92e...","createdAt":1732550124,"reason":"Agent runtime closed the connection before completing the run"}

Disconnect and cancellation

If you close the connection (abort the fetch, close the response stream) before RunCompleted or error arrives, Elizon detects the disconnect and cancels the in-flight run upstream — there's no need to call the cancel endpoint separately in that case.

TypeScript example

const response = await fetch(`https://api.elizon.com/api/v1/agents/${agentId}/run-stream`, {
  method: 'POST',
  headers: {
    'X-API-Key': 'elz_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ message: 'Hello!' }),
})

const reader = response.body!.getReader()
const decoder = new TextDecoder()
let fullContent = ''

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  const chunk = decoder.decode(value, { stream: true })
  for (const line of chunk.split('\n')) {
    if (!line.startsWith('data: ')) continue
    const event = JSON.parse(line.slice(6))
    if (event.event === 'RunContent') fullContent += event.content
    if (event.event === 'RunCompleted') {
      console.log('Complete response:', fullContent)
      console.log('Metrics:', event.metrics)
    }
    if (event.event === 'error') {
      console.error('Run failed:', event.reason)
    }
  }
}

Errors

Before the stream opens, the same validation and scope errors as /run apply (400, 403, 404, 502). Once the stream has started, failures are reported as an error event instead of an HTTP error status — check the status code of the initial response, then watch for an error event for anything that goes wrong mid-stream.