Execute Agent (Streaming)

Execute a research agent using Server-Sent Events (SSE) to receive responses in real time. As the agent generates text, delta events are streamed to the client.

Ideal for long-running research tasks and UI applications that display responses in real time. For simple fire-and-forget use cases, see Execute Agent (Non-Streaming).

New Execution

POST /api/v1/agent/run/stream

Headers

Header	Required	Description
`Authorization`	Yes	API key in `Bearer snorbe_...` format
`Content-Type`	Yes	`application/json`
`Accept`	Yes	`text/event-stream`

Request Body

{
  "modelName": "gpt-5-mini-2025-08-07",
  "inputText": "Research the latest AI agent papers",
  "promptKey": "chat-routing",
  "locale": "en",
  "fileUrls": [],
  "mentions": [],
  "maxBrowsingSteps": 5,
  "extendedContextEnabled": false
}

Parameters

Parameter	Type	Required	Description
`modelName`	`string`	Yes	Model name
`inputText`	`string`	Yes	Input text for the agent
`promptKey`	`string`	Yes	Prompt key (typically `"chat-routing"`)
`locale`	`string`	Yes	`"ja"` or `"en"`
`fileUrls`	`string[]`	No	Attached file URLs (max 10). Default: `[]`
`agentId`	`string`	No	Agent ID. Defaults to the default agent
`mentions`	`Mention[]`	No	@mention references (entities, agent runs, sources, other Agents). Default: `[]`. Including `type: "agent"` lets the target Agent delegate via `mentionAgent` mid-run (see /agent/run for details)
`maxBrowsingSteps`	`number`	No	Max browsing steps (1-100)
`maxChainSteps`	`number`	No	Maximum depth of Agent-to-Agent mention chains (1-50, default 10)
`maxRetries`	`number`	No	Retry count (0-5)
`retryDelayMs`	`number`	No	Retry delay in ms (0-10000)
`includeOthersEntities`	`boolean`	No	Include other users’ entities in RAG search. Default: `true`
`extendedContextEnabled`	`boolean`	No	Extended context (uses 80% of model max tokens). Default: `false`
`matrixEditContext`	`object`	No	Matrix edit context (`sourceRunId` + `selection`)
`matrixContinueContext`	`object`	No	Matrix continue context (`sourceRunId`)
`matrixSelectionContent`	`string`	No	Matrix selection XML (`<matrix_selection>` format)

Mention Object

{
  "id": "entity_abc123",
  "type": "entity",
  "label": "GPT-5"
}

Field	Type	Description
`id`	`string`	ID of the referenced item (entity, agent run, or source)
`type`	`string`	`"entity"` / `"agent-run"` / `"public-source"` / `"private-source"`
`label`	`string`	Display name

Resume (Restart Existing Run)

Resume execution after a HITL (Human-in-the-Loop) pause, such as plan or report confirmation.

POST /api/v1/agent/run/stream/{runId}

Request Body

{
  "modelName": "gpt-5-mini-2025-08-07",
  "extendedContextEnabled": false
}

Parameters

Parameter	Type	Required	Description
`modelName`	`string`	Yes	Model name
`extendedContextEnabled`	`boolean`	No	Enable extended context. Default: `false`

SSE Event Format

Each event is sent as data: {JSON}\n\n.

config event

Sent once at the start of the stream.

data: {"type":"config","payload":{"runId":"clxyz...","modelName":"gpt-5-mini-2025-08-07","locale":"en","inputText":"..."}}

delta event

Sent each time the agent generates text.

data: {"type":"delta","payload":{"runId":"clxyz...","deltaText":"Generated text","responseText":"Full text so far","stepIndex":0,"modelId":"gpt-5-mini-2025-08-07","provider":"openai"}}

step event

Sent when an execution step completes.

data: {"type":"step","payload":{"runId":"clxyz...","stepIndex":0,"status":"complete","finishReason":"stop","usage":{"inputTokens":1234,"outputTokens":567}}}

browse events

When the browse tool is selected, browser automation progress is streamed as events.

data: {"type":"browse-start","payload":{"runId":"clxyz...","websocketInfo":{"session_id":"browser-session-id","user_id":"user-id","ws_url":"wss://...","token":"..."}}}
data: {"type":"browse-step","payload":{"runId":"clxyz...","stepIndex":1,"action":"click","screenshot":"..."}}
data: {"type":"browse-ask-human","payload":{"runId":"clxyz...","status":"pending","question":"Which menu should I open?"}}
data: {"type":"browse-final","payload":{"runId":"clxyz...","result":"Collected information..."}}
data: {"type":"browse-end","payload":{"runId":"clxyz..."}}

When you receive browse-ask-human, answer through /browser/answer-question using browse-start.payload.websocketInfo.session_id as sessionId. Unlike plan/report/matrix reviews, you do not call /agent/run/stream/{runId} after answering a browser question.

complete event

Sent when the agent finishes. This is the final event in the stream.

data: {"type":"complete","payload":{"runId":"clxyz...","text":"Final response text","finishReason":"stop","status":"completed","model":{"id":"gpt-5-mini-2025-08-07","provider":"openai"}}}

error event

Sent when an error occurs.

data: {"type":"error","payload":{"message":"Error message"}}

Additional internal events

The SSE stream emits every internal event as the agent progresses. In addition to the basic events above (config / delta / step / browse-* / complete / error), the following are also streamed:

Category	Event types
Plan (HITL)	`plan`, `plan-draft-delta`, `plan-draft-complete`, `plan-confirmed`, `plan-rejected`
Report structure (HITL)	`report-structure-draft-delta`, `report-structure-draft-complete`, `report_structure_confirmed`, `report_structure_rejected`
Matrix (HITL)	`matrix-structure-draft-delta`, `matrix-structure-draft-complete`, `matrix-data-preview`, `matrix-data-updated`, `matrix_structure_confirmed`, `matrix_structure_rejected`
Source summarization	`source-summary-start`, `source-summary-delta`, `source-summary-item`, `source-summary-complete`
Graph extraction	`graph-start`, `graph`, `graph-extraction-entity-delta`

Recovering a dropped stream: every event sent over SSE is also persisted as agentRun.process in the database. If your SSE connection drops, call GET /turn/list — turns[].agentRun.process returns the same event timeline, and referenced sources are available in turns[].agentRun.publicSourceAgentRuns / privateSourceAgentRuns.

Examples

curl -N -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run/stream" \
  -H "Authorization: Bearer snorbe_your_api_key_here" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "gpt-5-mini-2025-08-07",
    "inputText": "Research the latest AI agent papers",
    "promptKey": "chat-routing",
    "locale": "en"
  }'

Resume Example

# Resume after HITL confirmation
curl -N -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run/stream/clxxx123" \
  -H "Authorization: Bearer snorbe_your_api_key_here" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"modelName":"gpt-5-mini-2025-08-07"}'

Error Responses

If an error occurs before the stream starts, a regular JSON response is returned instead of SSE.

HTTP Status	Description
401	Invalid API key
400	Validation error
404	Agent run not found for the given `runId` (resume only)

​Execute Agent (Streaming)

​New Execution

​Headers

​Request Body

​Parameters

​Mention Object

​Resume (Restart Existing Run)

​Request Body

​Parameters

​SSE Event Format

​config event

​delta event

​step event

​browse events

​complete event

​error event

​Additional internal events

​Examples

​Resume Example

​Error Responses

Execute Agent (Streaming)

New Execution

Headers

Request Body

Parameters

Mention Object

Resume (Restart Existing Run)

Request Body

Parameters

SSE Event Format

config event

delta event

step event

browse events

complete event

error event

Additional internal events

Examples

Resume Example

Error Responses