SSE Streaming Guide

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

Overview

AGENTIC STAR 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 prefixed with data:
Stream end is signaled by data: [DONE]
For long-running agent tasks, reconnection and cancellation endpoints are available

Back to User API Reference (Chat)

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 (once)

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":"tool_result","callId":"0cf24f34-bbd9-4833-88c4-d7f520ce3aae","title":"success","status":"completed","timestamp":1773499412706}]}}]}
                                     ↑ Chunk containing task execution info (multiple times)

: heartbeat                          ← Connection keep-alive comment (approx. 30s interval, inserted only during idle periods)

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 the connection has been 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.
: `heartbeat`	SSE comment line. Keeps the connection alive during long idle periods (to avoid proxy idle timeouts). Inserted at roughly 30-second intervals. Since it does not start with `data:`, typical clients ignore it automatically.
Final chunk	Chunk with finishReason set. May contain status (execution state) and deliverables (artifact files).
data: `[DONE]`	Stream end signal. The SSE connection is closed after this.

Response Headers

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

Response Objects

Each SSE data: line is composed of the following object hierarchy.

ChatCompletionChunk
  └─ choices[]
       └─ Choice
            ├─ delta          … Delta object (diff data)
            ├─ finishReason   … Completion reason
            ├─ status         … Agent execution state
            └─ deliverables   … Artifact files

ChatCompletionChunk

The top-level object of each SSE event.

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 1 element)

Choice

Each element of the choices array. AGENTIC STAR always contains only 1 element.

Parameter	Type	Description
`index`	`number`	Always `0`
`delta`	`object`	Diff data (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 artifact files generated by the agent

Delta

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

Parameter	Type	Appearance	Description
`role`	`string`	First only	Sent only in the 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 (array of Task objects)
`interaction`	`object`	Conditional	User interaction request (option presentation, etc.)

Agent Extension Fields

AGENTIC STAR adds agent-specific extension fields to the OpenAI-compatible format.

Field	Level	Description
`delta.tasks`	Delta	Agent task execution info
`delta.interaction`	Delta	User interaction request
`choice.status`	Choice	Agent execution state
`choice.deliverables`	Choice	List of artifact files

delta.tasks

Agent task execution info. Delivered as a delta.tasks array in SSE chunks when actions such as tool execution, file creation, or search occur. Sent each time a task status updates; the typical number of Tasks per chunk is 1. delta.tasks coexists with delta.content in the same chunk.

For details of the Task object, see Task Data Model.

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",
        "description": "Processing 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 }
  }]
}

delta.interaction

Sent when the agent requests interaction with the user. There are two types: option presentation (choice) and confirmation dialog (confirmation).

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

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

Example of choice:

JSON
"interaction": {
  "interactionType": "choice",
  "content": "Which format would you like to output?",
  "options": ["PDF", "Markdown", "HTML"]
}

Example of confirmation:

JSON
"interaction": {
  "interactionType": "confirmation",
  "content": "Are you sure you want to delete this file?"
}

choice.status

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

Parameter	Type	Description
`processing`	`boolean`	Whether the agent is continuing background processing. Typically transitions together with `unfinished`. If `true`, subsequent events can be received via reconnection.
`unfinished`	`boolean`	Whether the task is incomplete. Typically transitions together with `processing`. Both `false` means normal completion; both `true` means processing is still ongoing.

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

choice.deliverables

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

Parameter	Type	Description
`filename`	`string`	File name
`filepath`	`string`	File path (relative path for download)
`source`	`string`	`"agent"` (agent-generated) or `"user"` (user-uploaded).
`isPrimary`	`boolean`	Whether it is a primary artifact
`createdAt`	`string`	Creation date/time (ISO 8601 format)
`mimeType`	`string?`	MIME type (e.g., `"application/pdf"`, `"image/png"`, `"text/markdown"`). Omitted when it cannot be determined from filename
`size`	`number?`	File size (bytes). Omitted when 0 or below

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

Task Data Model

The delta.tasks array contains Task objects that represent actions the agent has executed. Each Task consists of "fields common to all Tasks" and "a variable part whose structure is switched by actionType".

When developing your own agent on the Marketplace edition

The specifications in this document up to and including "SSE Connection Lifecycle", "ChatCompletionChunk", "Choice", "status", and "deliverables" are guaranteed by the platform.

The actionType values and metadata internals of delta.tasks[] are documented based on the SaaS edition agent implementation. When developing your own agent on the Marketplace edition, these depend on your implementation, so use them as reference information only.

Overview

Task = [ Common fields ] + [ Variable part driven by actionType ]

actionType (6 types) ─┬─ Tool lifecycle    tool_start, tool_result *
                      ├─ Special results   search_result, command_execution, mcp_tool
                      └─ File notifications file_operation

  * tool_result has a second-level branch via metadata.sub_event_type (9 types)

As a representative example, a Task for a Bash command completion (tool_result / sub_event_type: bash_executed) looks like this:

JSON
{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "actionType": "tool_result",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "status": "completed",
  "title": "success",
  "description": "{'result': 'ok'}",
  "metadata": {
    "tool_name": "bash",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "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"
}

The rest of this section is organized as "Common fields → actionType branch map → Per-group details → Stream example".

About the sandbox preparation notification

At the start of a conversation, a pair of actionType: "tool_start" → "tool_result" is delivered with tool_name: "agent_executor" and title: "Sandbox". This is not a tool invoked by the AI agent; it is an infrastructure notification that the execution environment (sandbox) preparation has started / completed. The metadata contains only tool_name and call_id.

If you want to display it, use title / description as-is. If no special handling is needed, you may filter it out with tool_name === "agent_executor".

Common fields

Fields that appear in every Task.

Field	Type	Description
`messageId`	`string`	ID of the message the task belongs to
`conversationId`	`string`	ID of the conversation the task belongs to
`actionType`	`string`	Discriminator that determines the variant structure (§ actionType branch map)
`status`	`string`	Task state. One of `in_progress` / `completed` / `failed` / `error` / `pending` (the overall task lifecycle; `error` appears mainly when `command_execution` fails; `pending` may be observed in infrastructure notifications such as the sandbox preparation notice, or as a residual initial state when reading via the history API). Tool-specific detailed statuses are stored in `metadata.status` and are a separate value from this field
`callId`	`string \| null`	Only `tool_start` and `tool_result` carry a value; null for other actionTypes. Start and result are paired by the same value
`title`	`string`	Short heading of the task type or target (for display)
`description`	`string`	Progress message or supplementary explanation (for display)
`content`	`string`	Task output body (for display, can be long)
`metadata`	`object`	Structure varies by `actionType` (see Per-group details)
`files`	`TaskFile[]`	Related files. Mainly used with `file_operation` (TaskFile structure — see below)
`timestamp`	`number`	Task timestamp (Unix milliseconds)
`createdAt`	`string`	Creation date/time (ISO 8601)
`updatedAt`	`string`	Update date/time (ISO 8601)

Do not use display text for program branching

title / description / content are human-readable text fields. Do not use them as branching conditions in your program. For branching, use actionType / status / metadata.sub_event_type.

Field	Typical use
`title`	Short heading of the task type or target (e.g. tool name, MCP name)
`description`	Progress message or supplementary explanation
`content`	Body of the tool output

actionType branch map

actionType is the discriminator that determines how the variant part of a Task changes. The 6 values fall into 3 groups:

Tool lifecycle: Notifies the start / completion of a tool used by the agent
Special results: Web search, shell command, MCP tool — each with their own metadata structure
File notifications: Notifies files generated by the agent

actionType	Group	callId	Description
`tool_start`	Tool lifecycle	✓	Tool execution start notification
`tool_result`	Tool lifecycle	✓	Tool execution completion result
`search_result`	Special result	—	Web search completion result
`command_execution`	Special result	—	Shell command execution completion result
`mcp_tool`	Special result	—	MCP tool execution result
`file_operation`	File notification	—	File creation completion notification

Pairing by callId: tool_start and tool_result are linked by the same callId / metadata.call_id. For other actionTypes, callId is null. See § SSE Stream Example for a concrete pairing example.

The next sections describe the metadata structure and behavior for each group.

Group ① Tool lifecycle

tool_start / tool_result notify the start (tool_start) and completion (tool_result) of tools used by the agent.

tool_start

Tool execution start notification. Use callId and metadata.call_id to link with the corresponding tool_result.

Emission Conditions

tool_start is currently emitted only when tool_name is generate_video or local_assistant. For all other tools, only the completion tool_result is delivered.

Use tool_result as the primary signal for detecting tool completion
Treat tool_start as a supplementary notification limited to the tools above
Supported tools may be added in the future, so we recommend implementing code that safely ignores unknown tool_name values

Common fields:

Field	Type	Description
`tool_name`	`string`	`"generate_video"` or `"local_assistant"`
`call_id`	`string`	Tool call ID (same value as callId). Links with the corresponding `tool_result`
`status`	`string`	Fixed as `"starting"`

tool_result

Tool execution completion result. metadata.sub_event_type subdivides the tool type.

metadata common fields

Field	Type	Description
`tool_name`	`string`	Tool name
`call_id`	`string`	Tool call ID
`sub_event_type`	`string`	Tool type (see the 9 types below)
`status`	`string`	Tool-specific execution result status. This is a different field from Task.status (the overall task lifecycle) — it is a tool-specific value inside `metadata` (e.g., `"success"`, `"created"`, `"read"`, `"edited"`, `"searched"`, `"fetched"`, `"completed"` — varies by tool)

Ignore unknown sub_event_type / extra fields

The sub_event_type values observable through the external SSE stream are currently 9. New types may be added in the future, so we strongly recommend implementing code that safely ignores unknown sub_event_type values and references only the fields you need.

Depending on the execution context, the metadata of each sub_event_type may contain extra fields (e.g., agent when a sub-agent executes the tool, slide_event during slide generation, sdd_event during SDD-driven development). The tool_name value also varies by execution path for the same sub_event_type (e.g., "read" vs "file_read" for file_read). Safely ignore any fields your client does not recognize.

Some tool_result Tasks have no sub_event_type. For generic batch operations (e.g., tool_name: "batch") or very short intermediate notifications immediately after a tool call, metadata.sub_event_type itself may be omitted. When sub_event_type is missing or unknown, use tool_name / title / description only for display, and skip the Task for programmatic branching.

sub_event_type list

The following 9 types are sent to the external SSE stream, identically for SaaS and Marketplace editions. (When Desktop App integration is used, macos_automation may additionally appear; we recommend implementing clients that safely ignore it as an unknown value.)

sub_event_type	Description	Main metadata fields
`local_assistant`	Local assistant execution completion	`message`, `result`, `files_created`, `files_modified`, `execution_time`, `turns_used`
`bash_executed`	Bash command execution	`command`, `exit_code`, `stdout`, `stderr`, `duration_ms`, `working_dir`
`file_edited`	File editing (write / edit / multiedit / apply_patch / notebook_edit / render_diagram)	`file_path`, `lines_written`, `replacements_made`, `diff`, `total_edits`
`file_read`	File reading	`file_path`, `lines_read`, `total_lines`, `is_binary`, `truncated`
`file_searched`	File search (grep / glob / ls)	`pattern`, `path`, `matches`, `files`, `file_count`, `tree`
`web_fetched`	Web content fetch / file transfer	`url`, `content_type`, `status_code`, `from_cache`, `duration_ms`
`task_launched`	Subtask launch	`agent_type`, `task_description`, `success`, `duration_ms`
`video_generated`	Video generation completion	`job_id`, `preview_urls`, `final_url`, `used_prompt`, `model`
`image_generated`	Image generation completion	`image_url`, `original_prompt`, `revised_prompt`, `model`

Search / command / MCP / file creation use their own actionType

Web search / shell command / MCP tools are delivered as independent actionType values (search_result / command_execution / mcp_tool), not as tool_result
File creation notifications are delivered as actionType: "file_operation"
The above four do not appear in metadata.sub_event_type

Details per sub_event_type

The 9 types are listed below using the same template (metadata fields + JSON example). Each is wrapped in a <details> block — click to expand the ones you need.

bash_executed — Bash command execution

Field	Type	Description
`tool_name`	`string`	`"bash"`
`command`	`string`	Executed command
`exit_code`	`number`	Exit code
`stdout`	`string`	Standard output
`stderr`	`string`	Standard error output
`status`	`string`	`"success"` (exit_code=0) or `"error"`
`duration_ms`	`number`	Execution time (milliseconds)
`working_dir`	`string`	Execution directory
`title`	`string`	Short tool-level label (`"Execute: "` + first 30 chars of the command). Different from the Task-level `title`

JSON
"metadata": {
  "tool_name": "bash",
  "call_id": "call_0jqMfLE5lIuoJHglhuItZ4cZ",
  "command": "mkdir -p /home/ubuntu/scratchpad",
  "exit_code": 0,
  "stdout": "",
  "stderr": "",
  "status": "success",
  "duration_ms": 2,
  "working_dir": "/opt/.autonomous_agent/.sandbox-runtime",
  "title": "Execute: mkdir -p /home/ubuntu/scratchp...",
  "sub_event_type": "bash_executed"
}

local_assistant — Local assistant execution completion

Field	Type	Description
`tool_name`	`string`	`"local_assistant"`
`message`	`string`	Executed task description
`success`	`boolean`	Success flag
`result`	`string`	Execution result text
`files_created`	`string[]`	Array of created file paths
`files_modified`	`string[]`	Array of modified file paths
`error`	`string \| null`	Error content (only on failure)
`execution_time`	`number`	Execution time (seconds)
`turns_used`	`number`	Internal turn count
`status`	`string`	`"completed"` or `"failed"`

JSON
"metadata": {
  "tool_name": "local_assistant",
  "call_id": "call_01HXYZ",
  "sub_event_type": "local_assistant",
  "message": "Create and test a Python script",
  "success": true,
  "result": "Created the requested Python script and added unit tests. All tests pass.",
  "files_created": [
    "/workspace/exec-12345/src/data_processor.py",
    "/workspace/exec-12345/tests/test_data_processor.py"
  ],
  "files_modified": [
    "/workspace/exec-12345/requirements.txt"
  ],
  "error": null,
  "execution_time": 23.5,
  "turns_used": 8,
  "status": "completed"
}

Minimal progress notification form

For tool calls routed through claude-code-mcp, a minimal progress notification may be delivered in addition to the completion result. In that case, metadata contains only tool_name and call_id — the message / result / status and other fields above are not included. We recommend handling it as a progress notification or skipping it when status is absent.

file_edited — File editing (write / edit / multiedit / apply_patch / notebook_edit / render_diagram)

file_edited is emitted via multiple tools. Branch on tool_name.

Common fields

Field	Type	Description
`tool_name`	`string`	Edit tool name. Varies by execution path (e.g., `"write"`, `"edit"`, `"multiedit"`, `"file_edit"`, `"apply_patch"`, `"notebook_edit"`, `"render_diagram"`)
`file_path`	`string`	Target file path (representative file for multi-file edits)
`status`	`string`	`"created"` \| `"updated"` \| `"edited"` \| `"multi_edited"` \| `"error"`

write-specific (tool_name: "write")

Field	Type	Description
`lines_written`	`number`	Lines written
`file_size`	`number`	File size in bytes
`line_start`	`number \| null`	Start line of the write range
`line_end`	`number \| null`	End line of the write range
`content_truncated`	`boolean`	Set to `true` only when content is too large to include in `message` (otherwise omitted / effectively `false`)

JSON
"metadata": {
  "tool_name": "write",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/new_module.py",
  "lines_written": 45,
  "file_size": 1234,
  "line_start": 1,
  "line_end": 45,
  "status": "created"
}

edit-specific (tool_name: "edit")

Field	Type	Description
`replacements_made`	`number`	Replacement count
`strategy_used`	`string`	Replacement strategy applied (e.g., `"exact"`, `"whitespace_normalized"`)
`diff`	`string`	Diff text
`lines_count`	`number`	Total lines of the file after edit
`content_truncated`	`boolean`	Set to `true` only when content is too large to include in `message`

JSON
"metadata": {
  "tool_name": "edit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/main.py",
  "replacements_made": 3,
  "strategy_used": "exact_match",
  "diff": "- old_function()\n+ new_function()",
  "lines_count": 150,
  "status": "edited"
}

multiedit-specific (tool_name: "multiedit")

Field	Type	Description
`total_edits`	`number`	Total edit count
`successful_edits`	`number`	Successful edit count
`failed_edits`	`number`	Failed edit count
`diff`	`string`	Diff text
`lines_count`	`number`	Total lines of the file after edit
`content_truncated`	`boolean`	Set to `true` only when content is too large to include in `message`

JSON
"metadata": {
  "tool_name": "multiedit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/config.py",
  "total_edits": 5,
  "successful_edits": 4,
  "failed_edits": 1,
  "diff": "- DEBUG = False\n+ DEBUG = True",
  "lines_count": 120,
  "status": "multi_edited"
}

apply_patch-specific (tool_name: "apply_patch")

Field	Type	Description
`added_files`	`string[]`	Array of added file paths
`modified_files`	`string[]`	Array of modified file paths
`deleted_files`	`string[]`	Array of deleted file paths
`moved_files`	`object[]`	Array of moved files (`{from, to}` objects)
`total_files`	`number`	Total number of affected files
`success`	`boolean`	Whether the patch was applied successfully
`errors`	`string[]`	Array of error messages (on failure)

JSON
"metadata": {
  "tool_name": "apply_patch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/src/main.py",
  "added_files": ["/workspace/exec-12345/src/new_feature.py"],
  "modified_files": ["/workspace/exec-12345/src/main.py"],
  "deleted_files": [],
  "moved_files": [],
  "total_files": 2,
  "success": true,
  "errors": [],
  "status": "edited"
}

notebook_edit-specific (tool_name: "notebook_edit")

Field	Type	Description
`operation`	`string`	Notebook operation type (e.g., `"insert"`, `"replace"`, `"delete"`)
`total_cells`	`number`	Total cell count after edit

JSON
"metadata": {
  "tool_name": "notebook_edit",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/analysis.ipynb",
  "operation": "insert",
  "total_cells": 12,
  "status": "edited"
}

render_diagram-specific (tool_name: "render_diagram")

Field	Type	Description
`diagram_type`	`string`	Diagram type (e.g., `"mermaid"`, `"plantuml"`)
`format_used`	`string`	Output format (e.g., `"png"`, `"svg"`)
`error`	`string \| null`	Error content (only on failure)

JSON
"metadata": {
  "tool_name": "render_diagram",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_edited",
  "file_path": "/workspace/exec-12345/diagrams/architecture.png",
  "diagram_type": "mermaid",
  "format_used": "png",
  "error": null,
  "status": "created"
}

file_read — File reading

Field	Type	Description
`tool_name`	`string`	Read tool name. Varies by execution path (e.g., `"read"`, `"file_read"`)
`file_path`	`string`	Target file path
`raw_content`	`string`	File content read (raw). Not previewable for binary files
`lines_read`	`number`	Lines read
`total_lines`	`number`	Total lines in the file
`is_binary`	`boolean`	Whether the file is binary
`truncated`	`boolean`	Whether the content was truncated
`status`	`string`	Fixed as `"read"`
`line_start`	`number \| null`	Start line of the read range
`line_end`	`number \| null`	End line of the read range

JSON
"metadata": {
  "tool_name": "read",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_read",
  "file_path": "/workspace/exec-12345/src/main.py",
  "raw_content": "# Main Application\nimport os\nimport sys\n\ndef main():\n    print('Hello, World!')\n",
  "lines_read": 6,
  "total_lines": 6,
  "is_binary": false,
  "truncated": false,
  "line_start": 1,
  "line_end": 6,
  "status": "read"
}

file_searched — File search (grep / glob / ls)

Field	Type	Description
`tool_name`	`string`	Search tool name. Varies by execution path (e.g., `"grep"`, `"glob"`, `"ls"`, `"file_search"`)
`status`	`string`	`"searched"` (grep) / `"globbed"` (glob) / `"listed"` (ls)
`pattern`	`string`	Search pattern (for grep / glob)
`path`	`string`	Search path (for grep)
`cmd`	`string`	Executed command (for grep)
`matches`	`string[]`	Raw match lines from ripgrep (for grep). Format depends on `output_mode`: `files_with_matches` returns file paths, `content` returns `"path:line:content"` strings, `count` returns `"path:count"` strings
`files_searched`	`number`	Number of files searched (for grep)
`directory`	`string`	Target directory (for glob / ls)
`files`	`string[]`	Matched files (for glob)
`file_count`	`number`	File count (for glob / ls)
`truncated`	`boolean`	Whether results were truncated (for glob)
`tree`	`string`	Directory tree as text (for ls)
`dir_count`	`number`	Directory count (for ls)
`total_size`	`number`	Total file size in bytes (for ls)

Via grep (tool_name: "grep")

JSON
"metadata": {
  "tool_name": "grep",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "pattern": "def main",
  "path": "/workspace/exec-12345/src",
  "cmd": "rg \"def main\" --hidden --max-columns 500 -l /workspace/exec-12345/src",
  "matches": ["src/main.py", "src/utils.py"],
  "files_searched": 2,
  "status": "searched"
}

Via glob (tool_name: "glob")

JSON
"metadata": {
  "tool_name": "glob",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "pattern": "**/*.py",
  "directory": "/workspace/exec-12345/src",
  "files": ["main.py", "utils.py", "config.py"],
  "file_count": 3,
  "truncated": false,
  "status": "globbed"
}

Via ls (tool_name: "ls")

JSON
"metadata": {
  "tool_name": "ls",
  "call_id": "call_01HXYZ",
  "sub_event_type": "file_searched",
  "directory": "/workspace/exec-12345",
  "tree": ".\n├── src/\n│   ├── main.py\n│   └── utils.py\n├── tests/\n└── README.md",
  "file_count": 3,
  "dir_count": 2,
  "total_size": 45678,
  "status": "listed"
}

web_fetched — Web content fetch / file transfer

web_fetched is emitted via two paths: web page fetch and file transfer (download / upload). Branch on tool_name.

Via webfetch (tool_name: "webfetch")

Field	Type	Description
`url`	`string`	Target URL
`content_type`	`string`	Response Content-Type
`status_code`	`number`	HTTP status code
`truncated`	`boolean`	Whether content was truncated
`from_cache`	`boolean`	Whether served from cache
`status`	`string`	Fixed as `"fetched"`
`duration_ms`	`number`	Fetch time (milliseconds)
`response_headers`	`object`	Response headers
`title`	`string`	Short tool-level label (`"Fetch: "` + first 50 chars of the URL). Different from the Task-level `title`

JSON
"metadata": {
  "tool_name": "webfetch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "web_fetched",
  "url": "https://example.com",
  "content_type": "text/html",
  "status_code": 200,
  "truncated": false,
  "from_cache": false,
  "duration_ms": 523,
  "response_headers": {
    "content-type": "text/html; charset=UTF-8",
    "content-length": "1256"
  },
  "title": "Fetch: https://example.com",
  "status": "fetched"
}

File transfer family (tool_name: "download" / "upload" / "download_file" / "download_multiple_files" / "download_with_resume" / "get_file_info_from_url" / "check_url_accessibility" / "upload_to_ftp" / "react_upload_file" etc.)

Field	Type	Description
`url`	`string`	Target URL (`upload_url` for uploads)
`file_path`	`string`	Local file path
`status`	`string`	`"completed"` or `"error"`
`success`	`boolean`	Success flag
`file_size`	`number \| null`	File size in bytes
`content_type`	`string`	File Content-Type

JSON
"metadata": {
  "tool_name": "download_file",
  "call_id": "call_01HXYZ",
  "sub_event_type": "web_fetched",
  "url": "https://example.com/data.csv",
  "file_path": "/workspace/exec-12345/downloads/data.csv",
  "success": true,
  "file_size": 204800,
  "content_type": "text/csv",
  "status": "completed"
}

task_launched — Subtask launch

Field	Type	Description
`tool_name`	`string`	`"task"`
`agent_type`	`string`	Launched sub-agent type
`task_description`	`string`	Subtask description
`success`	`boolean`	Success flag
`status`	`string`	`"completed"` or `"failed"`
`title`	`string`	Short tool-level label (`"{agent_type}: {task_description}"`. If longer than 30 chars, the first 27 chars + `"..."`). Different from the Task-level `title`
`duration_ms`	`number`	Execution time (milliseconds)
`error_details`	`string \| null`	Error details (only on failure)

JSON
"metadata": {
  "tool_name": "task",
  "call_id": "call_01HXYZ",
  "sub_event_type": "task_launched",
  "agent_type": "data_analysis",
  "task_description": "Analyze sales data",
  "success": true,
  "title": "data_analysis: Analyze sale...",
  "duration_ms": 45678,
  "error_details": null,
  "status": "completed"
}

video_generated — Video generation completion

video_generated is emitted via two paths: single generation and batch generation. Branch on tool_name.

Single generation (tool_name: "generate_video")

Field	Type	Description
`success`	`boolean`	Success flag
`job_id`	`string`	Video generation job ID
`status`	`string`	Job status
`preview_urls`	`string[]`	Preview URL array
`final_url`	`string \| null`	Final video URL
`used_prompt`	`string`	Prompt actually used
`error`	`string \| null`	Error content (on failure)
`error_type`	`string \| null`	Error type
`model`	`string`	Model used
`created_at`	`string`	Creation timestamp (ISO 8601)
`completed_at`	`string`	Completion timestamp (ISO 8601)

JSON
"metadata": {
  "tool_name": "generate_video",
  "call_id": "call_01HXYZ",
  "sub_event_type": "video_generated",
  "success": true,
  "job_id": "job-azure-sora-12345",
  "preview_urls": [
    "https://storage.example.com/previews/frame001.jpg",
    "https://storage.example.com/previews/frame002.jpg"
  ],
  "final_url": "https://blob.example.com/exec-12345/generated_video.mp4",
  "used_prompt": "A beautiful sunset over the ocean with waves gently crashing on the shore",
  "error": null,
  "error_type": null,
  "model": "azure/sora-2",
  "created_at": "2026-04-18T15:00:00Z",
  "completed_at": "2026-04-18T15:02:30Z",
  "status": "succeeded"
}

Batch generation (tool_name: "generate_videos_batch")

Fields from single generation (job_id / preview_urls / final_url / used_prompt / model etc.) are not included. Only aggregate values are provided.

Field	Type	Description
`success`	`boolean`	Overall batch success flag
`total`	`number`	Total number of videos processed
`succeeded`	`number`	Number of successful videos
`failed`	`number`	Number of failed videos

JSON
"metadata": {
  "tool_name": "generate_videos_batch",
  "call_id": "call_01HXYZ",
  "sub_event_type": "video_generated",
  "success": false,
  "total": 4,
  "succeeded": 3,
  "failed": 1
}

image_generated — Image generation completion

Field	Type	Description
`tool_name`	`string`	`"generation_image"`
`success`	`boolean`	Success flag
`image_url`	`string \| null`	Generated image URL
`local_path`	`string \| null`	Local save path
`original_prompt`	`string`	Original prompt
`revised_prompt`	`string \| null`	Revised prompt (for gpt-image-1)
`error`	`string \| null`	Error content (on failure)
`error_type`	`string \| null`	Error type
`model`	`string`	Model used (e.g., `"gpt-image-1"`)
`created_at`	`string`	Creation timestamp (ISO 8601)

JSON
"metadata": {
  "tool_name": "generation_image",
  "call_id": "call_01HXYZ",
  "sub_event_type": "image_generated",
  "success": true,
  "image_url": null,
  "local_path": "/workspace/exec-12345/generated_image.png",
  "original_prompt": "Create a landscape painting with mountains and a lake",
  "revised_prompt": "A serene landscape with mountains in the background, a calm lake in the foreground, and a clear blue sky",
  "error": null,
  "error_type": null,
  "model": "gpt-image-1",
  "created_at": "2026-04-18T15:00:00Z"
}

Group ② Special results

Web search / shell command / MCP tool are delivered as independent actionType values. metadata.sub_event_type is not attached.

search_result

Web search completion result.

Field	Type	Description
`query`	`string`	Search query
`searchType`	`string`	Search type (`"web"` / `"news"` / `"video"` / `"image"` / `"location"`)
`searchEngine`	`string`	Search engine used (e.g., `"brave"`, `"bing"`, `"duckduckgo"`)
`resultCount`	`number`	Number of search results
`results`	`array`	Array of search results (`SearchResult` objects — see below)

Each element of results[] (SearchResult)

Field	Type	Description
`position`	`number`	Position in search results (1-indexed)
`url`	`string`	URL of the search result
`title`	`string`	Title
`description`	`string`	Snippet / summary
`source`	`string`	Search engine that provided this result (e.g., `"brave"`)
`raw_content`	`string \\| null`	Page body preview (`null` if unavailable)
`published_date`	`string \\| null`	Published date in ISO 8601 (`null` if unavailable)
`age`	`string \\| null`	Age expression (e.g., `"December 11, 2025"`, `"2 hours ago"`)
`author`	`string \\| null`	Author (`null` if unavailable)
`site_name`	`string \\| null`	Site domain (e.g., `"softbank.jp"`)

JSON
"metadata": {
  "query": "SoftBank AGENTIC STAR service",
  "searchType": "web",
  "searchEngine": "brave",
  "resultCount": 2,
  "results": [
    {
      "position": 1,
      "url": "https://www.softbank.jp/corp/news/press/sbkk/2025/20251211_01/",
      "title": "SoftBank launches AGENTIC STAR, an enterprise AI agent platform",
      "description": "SoftBank Corp. announced the launch of AGENTIC STAR, an enterprise-focused AI agent platform service...",
      "source": "brave",
      "raw_content": null,
      "published_date": "2025-12-11T00:00:00",
      "age": "December 11, 2025",
      "author": null,
      "site_name": "softbank.jp"
    },
    {
      "position": 2,
      "url": "https://businessnetwork.jp/article/31937/",
      "title": "SoftBank unveils AGENTIC STAR",
      "description": "SoftBank held a press briefing on December 11, 2025 and announced the launch of its enterprise AI agent platform AGENTIC STAR.",
      "source": "brave",
      "raw_content": null,
      "published_date": "2025-12-11T06:33:17",
      "age": "December 11, 2025",
      "author": null,
      "site_name": "businessnetwork.jp"
    }
  ]
}

command_execution

Shell command execution completion result.

Field	Type	Description
`command`	`string`	Executed command
`exitCode`	`number`	Exit code
`output`	`string`	Standard output
`errorOutput`	`string`	Standard error output
`workingDirectory`	`string`	Execution directory

JSON
"metadata": {
  "command": "ls -la /workspace/exec-12345/output",
  "exitCode": 0,
  "output": "total 32\n-rw-r--r-- 1 user user 4201846 Mar 14 10:30 report.pdf\n",
  "errorOutput": "",
  "workingDirectory": "/workspace/exec-12345"
}

mcp_tool

Notification of MCP (Model Context Protocol) tool execution.

metadata currently omitted

Tasks with actionType: "mcp_tool" currently omit the metadata field. Refer to title (MCP name) and description (execution message) for tool name and execution status. Fields may be added to metadata in future versions.

Also note that Task.status currently remains "in_progress" throughout. Do not use it for completion detection — refer to description (execution message) instead.

Group ③ File notifications

Notifies that the agent has created an output file in the working directory.

file_operation

The files array contains the details of the created file (TaskFile structure), and metadata.filePaths holds the corresponding paths inside the working directory (order matches the files array).

metadata fields

Field	Type	Description
`operationType`	`string`	Operation type (currently only `"create"`)
`filePaths`	`string[]`	Array of file paths inside the working directory (order matches the `files` array)

TaskFile structure

Structure of each element in files: TaskFile[].

Field	Type	Description
`filename`	`string`	File name
`size`	`number`	File size (bytes)
`filepath`	`string`	Download URL or file path inside the working directory
`mimeType`	`string?`	MIME type (e.g., <code>"application/pdf"</code>, <code>"image/png"</code>, <code>"text/markdown"</code>). Omitted when it cannot be determined from filename

JSON example

JSON
{
  "actionType": "file_operation",
  "title": "File created",
  "description": "Created report.pdf",
  "status": "completed",
  "metadata": {
    "operationType": "create",
    "filePaths": ["/workspace/exec-12345/output/report.pdf"]
  },
  "files": [
    {
      "filename": "report.pdf",
      "size": 4201846,
      "filepath": "https://blob.example.com/abc123/report.pdf",
      "mimeType": "application/pdf"
    }
  ]
}

SSE Stream Example: Tool Execution Pair

Example of a tool_start → tool_result pairing. The same callId / metadata.call_id links the start and completion.

Chunk 1: Tool start

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

JSON
"tasks": [{
  "messageId": "5b47837a-...",
  "conversationId": "09071b95-...",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "actionType": "tool_result",
  "title": "success",
  "description": "Created the requested Python script.",
  "status": "completed",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "sub_event_type": "local_assistant",
    "message": "Create a Python script",
    "success": true,
    "result": "Created the requested Python script.",
    "status": "success",
    "execution_time": 12.4,
    "turns_used": 3
  },
  "files": [],
  "timestamp": 1773499362744,
  "createdAt": "2026-03-14T14:42:42.747Z",
  "updatedAt": "2026-03-14T14:42:42.747Z"
}]

Reconnection

Reconnect to the SSE stream of an in-progress conversation. Used to recover from network disconnection.

GET /v1/chat/completions/{conversationId}

Usage Example

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

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 the 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.fd.agenticstar.tm.softbank.jp/api/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 the SSE connection is established. Returned as JSON in a 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`	The specified conversation is currently being processed

HTTP 400 error response:

JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "Parameter 'model' is required",
    "code": "missing_parameter",
    "param": "model",
    "suggested_action": "Please provide the required parameter"
  }
}

Errors During Streaming (SSE Error Chunk)

Errors that occur in the backend during SSE streaming. Delivered as a 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 a new message or start a separate conversation
Connection loss	Attempt reconnection via GET /v1/chat/completions/{conversationId}

Complete Response Example

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

// 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 the 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",
        "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "actionType": "tool_start",
        "status": "in_progress",
        "title": "local assistant",
        "metadata": { "tool_name": "local_assistant", "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "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": "These are the analysis results.",
      "tasks": [{
        "messageId": "660f9511-f3ac-52e5-b827-557766551111",
        "conversationId": "550e8400-e29b-41d4-a716-446655440000",
        "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "actionType": "tool_result",
        "status": "completed",
        "title": "success",
        "description": "Sales data analysis is complete.",
        "metadata": {
          "tool_name": "local_assistant",
          "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "sub_event_type": "local_assistant",
          "message": "Analyze sales data",
          "success": true,
          "result": "Sales data analysis is complete.",
          "status": "success",
          "execution_time": 45.6,
          "turns_used": 3,
          "files_created": ["/files/output/report.pdf"]
        },
        "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",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z",
      "mimeType": "application/pdf",
      "size": 4201846
    }]
  }]
}

// 4. Stream end
data: [DONE]

Overview​

Connection Lifecycle​

SSE Event Flow​

Detail of Each Phase​

Response Headers​

Response Objects​

ChatCompletionChunk​

Choice​

Delta​

Agent Extension Fields​

delta.tasks​

delta.interaction​

choice.status​

choice.deliverables​

Task Data Model​

Overview​

Common fields​

actionType branch map​

Group ① Tool lifecycle​

tool_start​

tool_result​

sub_event_type list​

Details per sub_event_type​

Group ② Special results​

search_result​

command_execution​

mcp_tool​

Group ③ File notifications​

file_operation​

TaskFile structure​

SSE Stream Example: Tool Execution Pair​

Reconnection​

Usage Example​

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

Response Objects

ChatCompletionChunk

Choice

Delta

Agent Extension Fields

delta.tasks

delta.interaction

choice.status

choice.deliverables

Task Data Model

Overview

Common fields

actionType branch map

Group ① Tool lifecycle

tool_start

tool_result

sub_event_type list

Details per sub_event_type

Group ② Special results

search_result

command_execution

mcp_tool

Group ③ File notifications

file_operation

TaskFile structure

SSE Stream Example: Tool Execution Pair

Reconnection

Usage Example

Cancellation

Usage Example

Response

Error Handling

Errors Before Stream Start (HTTP Errors)

Errors During Streaming (SSE Error Chunk)

Recovery Strategy

Complete Response Example