# 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)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#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

```text
: 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":"command_execution","title":"Command execution","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.                                                                                                                                                                                                            |

> **Text is converted to plain text**
>
> Unless the request specifies `outputFormat: "markdown"`, delivered text is converted to plain text with Markdown notation removed. This applies to `delta.content` and to `delta.interaction.content`. A link becomes "text (URL)" (only the URL when the text is the same as the URL), and an image becomes its alt text only. Specify `outputFormat: "markdown"` to receive Markdown as written.

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

```text
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                                                                 |
| `cancelled`    | `boolean`        | Present as `true` only on the chunk that acknowledges a cancellation. The field is absent from ordinary chunks |

### 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](#delta-uiresource)                 |
| `draft`       | `object` | Conditional    | A draft made in the chat (a playbook, skill, project, agent change or schedule). See [delta.draft](#delta-draft) |

## 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.draft`         | Delta  | A draft made in the chat  |
| `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](#task-data-model).

An example of what is delivered. The `actionType` and `metadata` values vary with the implementation of the agent you connect to.

<!-- -->

<!-- -->

```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`](#deltainteraction).

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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#get-ui-resource); **rendering happens in your own application**. See [Notes on rendering](#rendering-notes) 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](#deltainteraction)                                                                                |
> | External MCP server | Display or input alike              | `delta.uiResource`             | Never arrives in `interaction`. **The HTML itself may contain input fields** (see [Notes on rendering](#rendering-notes)) |
>
> `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](#ui-resource-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 blocking sends and task retrieval (`message/send` / `tasks/get` on 0.3, `SendMessage` / `GetTask` / `ListTasks` on 1.0). 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.draft

When you ask the chat for a draft of a playbook, skill, project, agent change or schedule, `delta.draft` arrives in the same chunk as the draft card's UI (`delta.uiResource`). `draft` is the draft as data, holding the values needed to create or change it (how to send it is in the table below for each kind; schedules cannot be created with the external API). **Nothing is created at this point.**

The reply text (`delta.content`) tells the user to save it on the screen. The conversation also appears in the chat on the user's screen, where it can be saved from the card. **If your application creates it from `draft`, confirm with the user first and do not also have it saved on the screen** (saving both creates two). A card may appear without `draft`. In that case, tell the user to save it on the screen.

#### Common fields

| Field        | Type     | Description                                                                                                                                                                                                                                                                     |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind`       | `string` | One of "playbook", "skill", "project", "agentUpdate" and "schedule". Ignore unknown values                                                                                                                                                                                      |
| `toolCallId` | `string` | The same value as tool\_call\_id of the matching UI part (for SSE, delta.uiResource in the same chunk; for history and search, metadata.uiResource of the same task; for MCP, the item in uiResources\[] with the same tool\_call\_id; for A2A, the same ui-resource- artifact) |

#### Contents and how to create each kind

| kind          | Contents                                                                                                                                                                                           | How to create it                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `playbook`    | `playbook` (`name`, `description`, `category`, `tags`, `steps[]` with `title`, `description`, `guidance` and `success`), and `updateOf` (the name of the playbook to change; `null` for a new one) | If `updateOf` is `null`, send `playbook` to [Create a playbook](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#create-playbook). If it has a name, read every page of `GET /v1/playbooks?active_only=false`, find the playbooks whose trimmed name equals the trimmed `updateOf`, and only when exactly one matches, read it with [Get a playbook](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#get-playbook) (`GET /v1/playbooks/{playbookId}`; the list has no `digest`) and send it to [Update a playbook](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#update-playbook) with that `digest` as `baseDigest`. If none or several match, change nothing and check with the user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `skill`       | `skillMd` (the whole SKILL.md), `name` and `description` (the same values as the SKILL.md frontmatter), and `updateOf`                                                                             | If `updateOf` is `null`, send `skillMd` as `SKILL.md` in `files` of [Create a skill](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#create-skill). If it has a name, read every page of `GET /v1/skills?active_only=false`, find the skills whose trimmed name exactly equals the trimmed `updateOf`, and only when exactly one matches, send it to [Replace skill files](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#replace-skill-files) with the `digest` from listing its files as `baseDigest`. If none or several match, change nothing, and create a new one or check with the user                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `project`     | `definition` (the project definition, in the import shape)                                                                                                                                         | Send `{ "definition": … }` to [Import a project](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#import-project). As with an import, it is created paused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `agentUpdate` | `agentName`, `projectName` (`null` when absent), and `spec` (`goal` and `guardrail`; a field that is not changed has no key)                                                                       | Read every page of [List agents](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#list-agents) (it returns only your own agents; set `q` to the trimmed `agentName`, or leave `q` out if that is over 100 characters), and collect the agents whose trimmed name exactly equals the trimmed `agentName`. If `projectName` is set (a blank one after trimming counts as none), first find the projects whose trimmed name equals the trimmed `projectName` in [List projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#list-projects) (the projects you take part in; every page), and keep only the agents in `agentId` of their [List placements](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md#list-placements) (if two or more projects match, combine all their placements). **Only when exactly one remains**, read it with [Get an agent](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#get-agent) (`GET /v1/agents/{agentId}`; the list has no `digest`) and send `{ spec, baseDigest }` to [Update an agent](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md#update-agent) with that `digest` as `baseDigest`. If none match, change nothing and tell the user; if several match, let the user choose. Changing an agent affects every project the agent is placed in |
| `schedule`    | `name`, `goal` and `cron` (a five-field cron expression in the user's local time, with no time zone)                                                                                               | There is no API to create it in the external API. The user creates it from the draft in the scheduled runs on the screen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

An example of a playbook draft (`delta`):

```json
"delta": {
  "content": "I drafted a playbook for the weekly sales check.",
  "uiResource": {
    "type": "html",
    "origin": "first-party",
    "altText": "I drafted a playbook for the weekly sales check.",
    "uri": "ui://widget/playbook_draft",
    "server_name": "agentic-star-widgets",
    "tool_name": "propose_playbook",
    "tool_call_id": "playbook_draft-0123456789abcdef",
    "mime_type": "text/html;profile=mcp-app"
  },
  "draft": {
    "kind": "playbook",
    "toolCallId": "playbook_draft-0123456789abcdef",
    "playbook": {
      "name": "Weekly sales check",
      "description": "Every Monday, summarize last week's sales and report them",
      "category": "Operations",
      "tags": [
        "sales",
        "weekly"
      ],
      "steps": [
        {
          "title": "Collect",
          "description": "Read last week's sales table",
          "guidance": [
            "Compare with the week before"
          ],
          "success": "Totals for every store are ready"
        }
      ]
    },
    "updateOf": null
  }
}
```

### 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"`                                                                                                                                                                                                                                                                                                                                                                             |
| `interactionId`   | `string`   |          | The ID of the agent's question. When you answer, send it in interactionReply of the next request. It may be absent (for example, for a question asked with a UI component)                                                                                                                                                                                                                                                 |
| `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](#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. To answer a question that has an `interactionId`, send `interactionReply: { interactionId, optionIndex? }` with it (for an answer chosen from the options, set `optionIndex` to the number of the chosen option, starting from 0). With it, the reply is recorded as the answer to that question, and you can answer even after the monthly usage limit is used up. When you do not send `interactionReply`, do not set `agentMode: false` (if you do, the reply does not reach the agent that asked the question).
>
> `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). An empty string when unknown                                                                 |
| `mimeType`  | `string`  | MIME type (e.g., `"application/pdf"`, `"image/png"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined |
| `size`      | `number?` | File size (bytes). Omitted when 0 or below                                                                                         |

```json
"deliverables": [{
  "filename": "report.pdf",
  "filepath": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/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`".

> **What the platform guarantees, and what the agent decides**
>
> The SSE connection lifecycle, the `ChatCompletionChunk` / `Choice` / `Delta` structures, `choice.status`, `choice.deliverables`, and the Task field names and defaults listed under "Common fields" below are guaranteed by the platform.
>
> The `actionType` values, the keys and structure of `metadata`, and the wording of `title` / `description` / `content` are decided by **the agent that produces the response**. The platform neither validates nor transforms them; it delivers them as sent.

### 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 details](#action-type))                                                                                                                                                                                                                                                                                                                                                         |
| `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 [actionType details](#action-type))                                                                                                                                                                                                                                                                                                                                                                        |
| `files`          | `TaskFile[]`     | Related files. Mainly used with `file_operation` (TaskFile structure — [see below](#taskfile))                                                                                                                                                                                                                                                                                                                                                   |
| `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. a tool name or target 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.

#### 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., `"application/pdf"`, `"image/png"`, `"text/markdown"`). Omitted when it cannot be determined from filename |

### Overview

```text
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 "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"`.

### 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](#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](#sub-event-type))                                                                                                                                                                                                                                                   |
| `status`         | `string` | Tool-specific execution result status. **This is a different field from [Task.status](#common-fields) (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. If a value not in this list arrives, 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) |

For the structure of each element of `files`, see [TaskFile structure](#taskfile).

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

```text
GET /v1/chat/completions/{conversationId}
```

### Usage Example

```bash
# 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.

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

### Usage Example

```bash
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
}
```

#### What the stream receives

Once a cancellation is accepted, a connected SSE stream receives one chunk like the following, followed by `data: [DONE]`.

```json
{
  "createdAt": "2026-03-14T10:30:07.000Z",
  "model": "AGENTIC STAR",
  "choices": [{
    "index": 0,
    "delta": { "content": "Cancelled" },
    "finishReason": "stop",
    "cancelled": true
  }]
}
```

`delta.content` is the fixed string `"Cancelled"`. `finishReason` is `"stop"`, not `"error"`, so use `choice.cancelled` to tell a cancellation apart from a normal completion.

## 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".

```text
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.

```text
// 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": "/users/11111111-2222-3333-4444-555555555555/plans/550e8400-e29b-41d4-a716-446655440000/deliverables/report.pdf",
      "source": "agent",
      "isPrimary": true,
      "createdAt": "2026-03-14T10:30:05.000Z",
      "mimeType": "application/pdf",
      "size": 4201846
    }]
  }]
}

// 4. Stream end
data: [DONE]
```
