SSE Streaming Guide

Details on SSE streaming responses from AgenticStar Chat API. This guide covers connection lifecycle, response objects, agent-specific extension fields, and error handling.

Overview

AgenticStar Chat API delivers responses via SSE (Server-Sent Events) streaming. Each chunk is in OpenAI-compatible ChatCompletionChunk format and includes agent-specific extension fields (task information, interaction requests, etc.).

Key Points

Content-Type is text/event-stream; charset=utf-8
Each event is a JSON line with data: prefix
Stream end is notified with data: [DONE]
For long-running agent tasks, reconnection and cancellation endpoints are available

Back to Chat API Reference

Connection Lifecycle

After a request to POST /v1/chat/completions, an SSE connection is established and events are delivered in the following order.

SSE Event Flow

: connected                          ← SSE connection established comment

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant","messageInfo":{...}}}]}
                                     ↑ Role chunk (1 time)

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"sales"}}]}
data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"data"}}]}
data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"is..."}}]}
                                     ↑ Content chunks (multiple times)

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"...","tasks":[{"messageId":"...","conversationId":"...","actionType":"execute","title":"data analysis","status":"running","timestamp":1234567890}]}}]}
                                     ↑ Chunk containing task execution info (multiple times)

data: {"createdAt":"...","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"..."},"finishReason":"stop"}]}
                                     ↑ Final chunk (with finishReason)

data: [DONE]                         ← Stream end signal

Detail of Each Phase

Phase	Description
: `connected`	SSE comment line. Indicates connection is established.
Role chunk	First data event. delta contains `role: "assistant"` and `messageInfo` (conversationId, messageId).
Content chunks	Diff of text content. delta.content contains appended text. May also contain agent task execution info (delta.tasks). Delivered multiple times.
Final chunk	Chunk with finishReason set. May contain status (execution state) and deliverables (artifacts).
data: `[DONE]`	Stream end signal. SSE connection closes after this.

Response Headers

Header	Description
`Content-Type`	text/event-stream; charset=utf-8
`X-Conversation-Id`	Conversation ID. For new conversations, server-generated ID is returned.
`X-Message-Id`	Assistant response message ID.

ChatCompletionChunk Object

The top-level object contained in each SSE event's data: line.

Parameter	Type	Description
`createdAt`	`string`	Chunk generation date/time (ISO 8601 format)
`model`	`string`	Model name. `"AGENTIC STAR"`
`choices`	`array`	Array of Choice objects (always contains 1 element)

JSON
data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{ ... }]
}

Choice Object

Each element in the choices array. AgenticStar always contains only 1 element.

Parameter	Type	Description
`index`	`number`	Always `0`
`delta`	`object`	Diff data. See Delta object below.
`finishReason`	`string \| null`	`"stop"` (successful completion), `"error"` (error), or `null` (streaming)
`status`	`object`	`{ processing: boolean, unfinished: boolean }` — agent execution state
`deliverables`	`array`	Array of deliverable files generated by agent

Delta Object

Diff data for each chunk. The fields included vary depending on chunk type.

Parameter	Type	Appearance	Description
`role`	`string`	First only	Sent only in first chunk. Fixed as `"assistant"`.
`messageInfo`	`object`	First only	`{ conversationId, messageId }` — Message identification info
`content`	`string`	Multiple times	Diff of text content
`tasks`	`array`	Multiple times	Agent task execution info (sent each time task status updates)
`interaction`	`object`	Conditional	User interaction request (option presentation, etc.)

Delta Extension Fields

AgenticStar adds agent-specific extension fields to the OpenAI-compatible format. Each field is delivered at its own specific timing during or at the end of streaming.

delta.tasks

Agent task execution information. Delivered as delta.tasks array in SSE chunks when actions like tool execution, file creation, or search occur. For complete Task data model definition, see Connection Guide.

SSE Delivery Context

delta.tasks is included in SSE chunks each time task status updates. Task count per chunk is typically 1. delta.content and delta.tasks coexist in the same chunk.

Position of delta.tasks within SSE chunk:

JSON
{
  "createdAt": "2026-03-14T15:00:53.059Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "finishReason": null,
    "delta": {
      "content": "Processing local_assistant",
      "tasks": [{
        "messageId": "5b47837a-...",
        "conversationId": "09071b95-...",
        "callId": "0cf24f34-...",
        "actionType": "tool_start",
        "title": "local assistant",
        "status": "in_progress",
        "metadata": { "tool_name": "local_assistant", "call_id": "0cf24f34-...", "status": "starting" },
        "timestamp": 1773499412706,
        "createdAt": "2026-03-14T14:43:32.708Z",
        "updatedAt": "2026-03-14T14:43:32.708Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}

Task Object Fields

Parameter	Type	Required	Description
`messageId`	`string`	✓	ID of the message the task belongs to
`conversationId`	`string`	✓	ID of the conversation the task belongs to
`actionType`	`string`	✓	`"tool_start"` \| `"tool_result"` \| `"search_result"` \| `"command_execution"` \| `"mcp_tool"` \| `"file_operation"`, etc.
`status`	`string`	✓	`"pending"` \| `"in_progress"` \| `"completed"` \| `"failed"` \| `"success"` \| `"error"`
`timestamp`	`number`	✓	Task timestamp (Unix milliseconds)
`createdAt`	`string`	✓	Task creation date/time (ISO 8601)
`updatedAt`	`string`	✓	Task update date/time (ISO 8601)
`title`	`string`		Task title (for display)
`description`	`string`		Detailed description of task
`callId`	`string \| null`		Tool call ID. Links `tool_start` with corresponding `tool_result`. Null for many actionType ([details](connection-guide.md#task-data-model))
`content`	`string`		Task output content
`metadata`	`object`		Task metadata. Contains different fields by actionType ([details](connection-guide.md#task-data-model))
`files`	`TaskFile[]`		Array of files associated with task

TaskFile Fields

Parameter	Type	Description
`filename`	`string`	File name
`fileType`	`string`	`"pdf"`, `"image"`, `"text"`, `"pptx"`, `"video"`, `"other"`
`size`	`number`	File size (bytes)
`filepath`	`string`	File path

TaskFile Example

JSON
"files": [
  {
    "filename": "qr_code_decode_report.pdf",
    "fileType": "pdf",
    "size": 4201846,
    "filepath": "/plans/{conversationId}/files/qr_code_decode_report.pdf"
  }
]

Representative actionType

actionType	Description
`tool_start`	Start notification for specific tool (local_assistant / generate_video / Sandbox)
`tool_result`	Result of general tool execution. Identify tool type via `metadata.sub_event_type`
`search_result`	Web search completion result
`command_execution`	Shell command execution completion result
`mcp_tool`	MCP tool execution result (no metadata)
`file_operation`	File creation completion notification

SSE Stream Example: Tool Execution Pair

Chunk 1: Tool start (local_assistant)

JSON
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "actionType": "tool_start",
  "title": "local assistant",
  "description": "Processing local_assistant",
  "status": "in_progress",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "status": "starting"
  },
  "files": [],
  "timestamp": 1773499412706,
  "createdAt": "2026-03-14T14:43:32.708Z",
  "updatedAt": "2026-03-14T14:43:32.708Z"
}]

Chunk 2: Tool completion (linked with same callId / metadata.call_id)

JSON
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "call_T3GIhcQQft13amxdhcJ4cBDz",
  "actionType": "tool_result",
  "title": "success",
  "description": "{'result': 'ok'}",
  "status": "in_progress",
  "metadata": {
    "tool_name": "bash",
    "call_id": "call_T3GIhcQQft13amxdhcJ4cBDz",
    "sub_event_type": "bash_executed",
    "command": "python3 script.py",
    "exit_code": 0,
    "stdout": "{'result': 'ok'}\n",
    "status": "success",
    "duration_ms": 24
  },
  "files": [],
  "timestamp": 1773499362744,
  "createdAt": "2026-03-14T14:42:42.747Z",
  "updatedAt": "2026-03-14T14:42:42.747Z"
}]

delta.interaction

Sent when an agent requests interaction with a user. There are two types: presenting options (choice) and confirmation dialog (confirmation).

InteractionExtension Fields

Parameter	Type	Required	Description
`interactionType`	`string`	✓	`"choice"` \| `"confirmation"`
`content`	`string`		Body of interaction message (sent for choice / confirmation)
`options`	`string[]`		Only for interactionType: "choice". Array of options.

interactionType List

Type	Description	Included Fields
`choice`	Present options and ask user to select one	`content`, `options`
`confirmation`	Ask user for confirmation (approve/deny)	`content`

Choice Example

JSON
"interaction": {
  "interactionType": "choice",
  "content": "どの形式で出力しますか？",
  "options": ["PDF形式", "Markdown形式", "HTML形式"]
}

Confirmation Example

JSON
"interaction": {
  "interactionType": "confirmation",
  "content": "このファイルを削除してもよろしいですか？"
}

choice.status

A field included at the Choice level in the final chunk. Indicates agent execution state.

Parameter	Type	Description
`processing`	`boolean`	Whether agent is continuing background processing. If `true`, subsequent events can be received via reconnection.
`unfinished`	`boolean`	Whether task is incomplete. Becomes true while waiting for user interaction or during long processing.

JSON
"status": { "processing": false, "unfinished": false }

choice.deliverables

A field included at the Choice level in the final chunk. List of deliverable files generated by agent.

DeliverableFile Fields

Parameter	Type	Description
`filename`	`string`	File name
`filepath`	`string`	File path (relative path for download)
`fileType`	`string`	`"pdf"`, `"image"`, `"text"`, `"pptx"`, `"video"`, `"other"`
`source`	`string`	`"agent"` (agent-generated) or `"user"` (user-uploaded).
`isPrimary`	`boolean`	Whether it is a primary deliverable
`createdAt`	`string`	Creation date/time (ISO 8601 format)

JSON
"deliverables": [{
  "filename": "report.pdf",
  "filepath": "/files/output/report.pdf",
  "fileType": "pdf",
  "source": "agent",
  "isPrimary": true,
  "createdAt": "2026-03-14T10:30:05.000Z"
}]

Reconnection

Reconnect to an in-progress conversation's SSE stream. Used to recover from network disconnection.

GET /v1/chat/completions/{conversationId}

Path Parameters

Parameter	Type	Description
`conversationId`	`string`	ID of conversation to reconnect to

Usage Example

curl
# Reconnect to in-progress conversation
curl -N https://api.agenticstar.jp/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Reconnection Timing

Scenario	Description
Network Disconnection	Reconnect using X-Conversation-Id after client-side network failure

info

Reconnection is only possible for in-progress conversations. For completed conversations, 404 Not Found is returned. Results of completed conversations can be retrieved via resource API (GET /v1/conversations/{conversationId}/messages).

Cancellation

Cancel an in-progress conversation and interrupt agent execution.

POST /v1/chat/completions/{conversationId}/cancel

Usage Example

curl
curl -X POST https://api.agenticstar.jp/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Response

JSON
{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "cancelled": true
}

Error Handling

Errors are returned in 2 formats depending on when they occur.

Errors Before Stream Start (HTTP Errors)

Errors that occur before SSE connection is established. Returned as JSON in normal HTTP response.

Status	Description
`400`	Invalid request parameters (model, messages, stream, etc.)
`401`	Authentication token is invalid or not specified
`403`	Missing chat:exec scope
`409`	Specified conversation is currently processing

HTTP 400 Error Response:

JSON
{
  "error": {
    "code": 400,
    "message": "Parameter 'model' is required"
  }
}

Errors During Streaming (SSE Error Chunk)

Errors that occur in the backend during SSE streaming. Delivered as ChatCompletionChunk with finishReason set to "error".

data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "An error occurred..." },
    "finishReason": "error"
  }]
}

data: [DONE]

Recovery Strategy

Error Type	Recommended Action
HTTP Error (400/401/403)	Check request parameters or authentication info and resend
HTTP 409 Conflict	Wait for conversation processing to complete or cancel and resend
SSE Error Chunk	Resume conversation with new message or start separate conversation
Connection Loss	Attempt reconnection via GET /v1/chat/completions/{conversationId}

Complete Response Example

Typical streaming sequence: role chunk → content chunks → final chunk.

JSON
// 1. Role chunk (first time only)
data: {
  "createdAt": "2026-03-14T10:30:00.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "role": "assistant",
      "messageInfo": {
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "messageId": "660f9511-f3ac-52e5-b827-557766551111"
      }
    }
  }]
}

// 2. Content chunks (multiple times)
data: {
  "createdAt": "2026-03-14T10:30:00.123Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "Here are the analysis results of sales data."
    }
  }]
}

// 2a. Content chunk containing task execution info
data: {
  "createdAt": "2026-03-14T10:30:01.500Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "Analyzing data...",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "actionType": "tool_start",
        "status": "in_progress",
        "title": "local assistant",
        "metadata": { "tool_name": "local_assistant", "status": "starting" },
        "timestamp": 1710410001500,
        "createdAt": "2026-03-14T10:30:01.500Z",
        "updatedAt": "2026-03-14T10:30:01.500Z"
      }]
    },
    "status": { "processing": true, "unfinished": true }
  }]
}

// 3. Final chunk (with deliverables and status)
data: {
  "createdAt": "2026-03-14T10:30:05.456Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": {
      "content": "Above are the analysis results.",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "actionType": "tool_result",
        "status": "in_progress",
        "title": "Data Analysis",
        "content": "Analysis is complete.",
        "timestamp": 1710410000000,
        "createdAt": "2026-03-14T10:30:05.400Z",
        "updatedAt": "2026-03-14T10:30:05.400Z"
      }]
    },
    "finishReason": "stop",
    "status": { "processing": false, "unfinished": false },
    "deliverables": [{
      "filename": "report.pdf",
      "filepath": "/files/output/report.pdf",
      "fileType": "pdf",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z"
    }]
  }]
}

// 4. Stream end
data: [DONE]

Overview​

Connection Lifecycle​

SSE Event Flow​

Detail of Each Phase​

Response Headers​

ChatCompletionChunk Object​

Choice Object​

Delta Object​

Delta Extension Fields​

delta.tasks​

SSE Delivery Context​

Task Object Fields​

TaskFile Fields​

TaskFile Example​

Representative actionType​

SSE Stream Example: Tool Execution Pair​

delta.interaction​

InteractionExtension Fields​

interactionType List​

Choice Example​

Confirmation Example​

choice.status​

choice.deliverables​

DeliverableFile Fields​

Reconnection​

Path Parameters​

Usage Example​

Reconnection Timing​

Cancellation​

Usage Example​

Response​

Error Handling​

Errors Before Stream Start (HTTP Errors)​

Errors During Streaming (SSE Error Chunk)​

Recovery Strategy​

Complete Response Example​

Overview

Connection Lifecycle

SSE Event Flow

Detail of Each Phase

Response Headers

ChatCompletionChunk Object

Choice Object

Delta Object

Delta Extension Fields

delta.tasks

SSE Delivery Context

Task Object Fields

TaskFile Fields

TaskFile Example

Representative actionType

SSE Stream Example: Tool Execution Pair

delta.interaction

InteractionExtension Fields

interactionType List

Choice Example

Confirmation Example

choice.status

choice.deliverables

DeliverableFile Fields

Reconnection

Path Parameters

Usage Example

Reconnection Timing

Cancellation

Usage Example

Response

Error Handling

Errors Before Stream Start (HTTP Errors)

Errors During Streaming (SSE Error Chunk)

Recovery Strategy

Complete Response Example