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. 15s 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. The text format is controlled by the request `outputFormat` — plain text by default (`"markdown"` preserves Markdown). 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 15-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.)
`uiResource`	`object`	Conditional	Display-only UI resource. For where each kind arrives, see delta.uiResource

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.uiResource`	Delta	Display-only UI resource
`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.uiResource

A UI resource produced by the agent during execution. Sent when the output includes something text alone cannot express, such as a chart, a map, or a card list. No user reply is expected — UI that asks for a reply is delivered in delta.interaction.

A UI resource is either type: "html", which renders HTML, or type: "data", which carries structured data. For type: "html", delta.uiResource carries metadata only — the HTML itself is not included. Retrieve the HTML as a string from the UI resource endpoint; rendering happens in your own application. See Notes on rendering for what to watch out for.

Where it arrives depends on the producer and the kind

Producer	Kind	Arrives in	What you do
AGENTIC STAR	Display (chart, map, card list)	`delta.uiResource`	Just render it. No reply needed
AGENTIC STAR	Input (choice cards, question form)	`delta.interaction.uiResource`	See delta.interaction
External MCP server	Display or input alike	`delta.uiResource`	Never arrives in `interaction`. The HTML itself may contain input fields (see Notes on rendering)

delta.uiResource and delta.interaction.uiResource have the same structure, but the two never appear in the same chunk.

If you do not handle UI

UI resources are supplementary output. The alternative text is in altText, which is the same string as delta.content of the same chunk. A client that does not render UI can simply ignore delta.uiResource and read delta.content.

Not every UI produced during a run is delivered. When the HTML cannot be served, delta.uiResource is absent and only the alternative text arrives in delta.content.

Common fields

type tells you how to render it; origin tells you how far to trust it. altText is the text to use when you do not render the UI.

Parameter	Type	Description
`type`	`string`	`"html"` (an HTML document; the body is not included, retrieve it from the UI resource endpoint) or `"data"` (structured data, included inline in the `data` field, no retrieval needed). Ignore unknown values.
`origin`	`string`	`"first-party"` (produced by AGENTIC STAR) or `"external"` (produced by an external MCP server your administrator has approved). See the table below for how handling differs.
`altText`	`string`	Alternative text. The same string as the adjacent `delta.content`. When building the response text or counting characters, use only one of the two. What it contains depends on `origin` (see the table below).

Differences by `origin`

The object has the same shape either way, but origin changes where the values come from and how you should treat them. Check this table before deciding how to handle a UI resource.

Aspect	"first-party"	"external"
Producer	AGENTIC STAR	An external MCP server approved by your administrator
Content inspection	Content produced by AGENTIC STAR	AGENTIC STAR does not inspect the contents
Rendering hints (`meta`)	Set by AGENTIC STAR	Declared by the provider (the external MCP server)
Declared capabilities (`capabilities`)	Set by AGENTIC STAR	Declared by the provider
Alternative text (`altText`)	Describes what the UI shows	A fixed phrase that does not describe the UI
Input handling	When a reply is requested it is delivered via `delta.interaction`. The UI has no path for sending a reply; replies are sent as text	Display and input are not distinguished. The HTML may contain input fields, and what is entered may be sent to a destination chosen by the provider

The form (starting with ui://, presence of the required fields, the MIME type, and the size limit) is validated for both.

For origin: "external", altText is the fixed string An external MCP server returned a UI resource. Its content is not described here. The response text for that turn (delta.content) is the same string, and carries no substantive answer. Tell the user that, and do not present this string as the result.

Fields for `type: "html"`

Parameter	Type	Description
`tool_call_id`	`string`	Identifier of the UI resource. Use it as the key for retrieving the HTML.
`uri`	`string`	Identifier of the UI resource (`ui://` scheme). Not a retrieval URL.
`tool_name`	`string`	Name of the tool that produced the UI.
`server_name`	`string`	Name of the server that provided the UI. Do not use it to judge trust — use `origin`.
`mime_type`	`string`	Normally `"text/html;profile=mcp-app"`.
`meta`	`object?`	Rendering hints (`preferredHeight`, `connectDomains`, etc.). Where the values come from depends on `origin` (see Differences by origin).
`capabilities`	`object?`	Capabilities (`visibility`, `interaction_mode`, etc.). Where the values come from depends on `origin` (same as above).
`size`	`number?`	Size of the HTML in bytes, usable to decide before retrieving. May be omitted

size is never present in history or search, nor in A2A message/send / tasks/get. Even on SSE, MCP and A2A streams it may be absent.

JSON
"delta": {
  "content": "I created a chart of the sales trend.",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "I created a chart of the sales trend.",
    "uri": "ui://widget/chart",
    "server_name": "agentic-star-widgets",
    "tool_name": "widget_chart",
    "tool_call_id": "chart-7f3a2b1c9e4d5a6b7c8d9e0f1a2b3c4d",
    "mime_type": "text/html;profile=mcp-app",
    "size": 8421
  }
}

Fields for `type: "data"`

Parameter	Type	Description
`origin`	`string`	Always `"first-party"` for `type: "data"`.
`kind`	`string`	Kind of data (e.g. `"map"`). Ignore unknown kinds and use `altText` instead.
`data`	`object`	Kind-specific payload, included inline.
`generated_at`	`string?`	Generation timestamp.

JSON
"delta": {
  "content": "I found 3 cafes nearby.",
  "uiResource": {
    "type": "data",
    "origin": "first-party",
    "altText": "I found 3 cafes nearby.",
    "kind": "map",
    "data": {
      "places": [
        { "place_id": "ChIJ...", "name": "Cafe A", "distance_text": "5 min walk" }
      ],
      "center_place_id": "ChIJ..."
    }
  }
}

For kind: "map", places[] contains a place_id and display text (name, note, price, distance, rating) — no coordinates and no addresses. Rendering an actual map requires your own Google Maps integration. Without one, you can still build a link to https://www.google.com/maps/place/?q=place_id:<place_id>. Whether to send place_id to an external service is your decision.

Besides places[], data carries center_place_id (the map centre) and a title for the header. Both may be omitted.

Notes on rendering

caution

Whatever the origin: we recommend rendering the retrieved HTML sandboxed, for example in an isolated iframe. Rendering it in an iframe without the sandbox attribute, or with allow-same-origin granted, lets scripts inside that HTML execute with the privileges of your own origin. UI produced by AGENTIC STAR also contains scripts.

For origin: "external" there is more: the content is produced by an external MCP server your administrator has approved, and AGENTIC STAR does not inspect it (only its form is validated). The HTML may contain input fields, and what is entered may be sent to a destination chosen by the provider — what happens to it there is outside AGENTIC STAR's control. meta.connectDomains is declared by the provider, not a set of destinations approved by AGENTIC STAR.

delta.interaction

Sent when the agent requests interaction with the user. There are three types: option presentation (choice), confirmation dialog (confirmation), and a request to answer prompts (question).

Parameter	Type	Required	Description
`interactionType`	`string`	✓	`"choice"` \| `"confirmation"` \| `"question"`
`content`	`string`		Body of the interaction message
`options`	`string[]`		Array of options. For `choice`, the options to present; for `confirmation`, the approve/deny labels (usually 2). Do not assume a fixed number of elements — present the array as given. May be omitted.
`uiResource`	`object`		UI resource for this interaction — choice cards or a question form (same structure as delta.uiResource). It carries what the text of `content` cannot express — descriptions, images, the form layout — as material for building your own UI. Mutually exclusive with `options`. The UI has no path for sending a reply, so read `content` and reply as text to the next `chat/completions` call.

Type	Description	Included Fields
`choice`	Present options and ask the user to select one	`content`. Plus either `options` or `uiResource` (neither may be present).
`confirmation`	Ask the user for confirmation (approve / deny)	`content`. `options` may be present.
`question`	Asks the user to answer one or more prompts	`content` (plain text carrying the prompts and their choices), plus `uiResource` (the form UI, which may be absent). Even prompts that offer choices do not populate `options`.

Replies are sent in the next request

The uiResource on interaction is material for presenting the prompts to your user. It carries what the plain text of content cannot express — the arrangement of choices, descriptions, and layout. Render it as is, or read it and build your own input UI. The UI itself has no path for sending a reply (capabilities.interaction_mode is "closed"). Note that the history and search APIs can return "block" for past conversations, because they include conversations that were not started through the API. Use capabilities.interaction_mode to tell them apart.

Reply by sending text to POST /v1/chat/completions with the same conversationId. There is no way to reply within the SSE stream.

content is the body of the interaction message. Choices may appear in the content text, or in options. If you do not render the UI, present content — together with options as the choices when it is present — and send the user's reply as text.

Note that a uiResource attached to interaction is always origin: "first-party" — UI from origin: "external" is delivered in delta.uiResource and never arrives in interaction.

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": "This file will be deleted. Reply 'delete' to proceed, or 'cancel' to stop.",
  "options": ["delete", "cancel"]
}

Example of question:

JSON
"interaction": {
  "interactionType": "question",
  "content": "Three questions about your preferences\nPlease reply with your answers:\n1. What do you most enjoy on a day off?\n   \"Relaxing at home\" \"Going out to new places\" \"Focusing on a hobby or study\"",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "Three questions about your preferences\nPlease reply with your answers:\n1. What do you most enjoy on a day off?\n   \"Relaxing at home\" \"Going out to new places\" \"Focusing on a hobby or study\"",
    "uri": "ui://widget/form",
    "server_name": "agentic-star-widgets",
    "tool_name": "widget_form",
    "tool_call_id": "form-45435d5ede3b43ec9a4a82e280db1e98",
    "mime_type": "text/html;profile=mcp-app",
    "size": 3562
  }
}

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

Safely ignore unknown fields

Future implementations may add new fields to actionType / metadata / common fields. Client implementations should safely ignore any fields not documented here (same stance as the sub_event_type note below).

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 provider used (e.g., `"brave"`, `"bing"`, `"duckduckgo"`)
`resultCount`	`number`	Number of search results
`results`	`array`	Array of search results (`SearchResult` objects — see below)

note

The search completion state is in the Task-level status field (outside metadata). On failure, an error string is added at the Task top level.

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

note

The execution completion state is in the Task-level status field ("completed" / "error", outside metadata).

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.

mcp_tool has no metadata object. The MCP name / execution message is in the Task title, and execution details are in description.

note

Task.status (the Task-level status outside metadata) 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.uiResource​

Common fields​

Differences by origin​

Fields for type: "html"​

Fields for type: "data"​

Notes on rendering​

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.uiResource

Common fields

Differences by `origin`

Fields for `type: "html"`

Fields for `type: "data"`

Notes on rendering

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