# Streaming the agent By default, `POST /v2/agent/chat` responds with a Server-Sent Events stream. A single turn can call several tools one after another, and each result is sent to you as soon as it exists. Your interface can show the opening sentence, then product cards, then the closing line, instead of waiting for the whole turn. This guide covers the wire format, every event the server sends, their order, how to carry conversation state, and how to handle errors and retries. ## Before the stream: check the response Authentication, quota, rate-limit and validation failures are all decided before any stream opens. Those responses are ordinary JSON with a real HTTP status: ```http HTTP/1.1 422 Unprocessable Entity Content-Type: application/json {"error":"messages cannot be empty."} ``` Always check both the status and the `Content-Type` before you start reading the body as a stream: ```javascript const type = res.headers.get('content-type') || ''; if (!res.ok || !type.includes('text/event-stream')) { const body = await res.json().catch(() => ({})); throw new Error(body.error || `HTTP ${res.status}`); } ``` A successful stream responds with `200`, `Content-Type: text/event-stream`, `Cache-Control: no-cache` and the usual `X-RateLimit-*` headers. ## Frame format Each event is one frame: an `event:` line, one `data:` line holding a JSON object, and a blank line. ```text event: text_delta data: {"delta":"Let me pull together a few options."} event: done data: {"output":"...","history":[...]} ``` - The server never sends comments, `id:` lines or `retry:` lines. - `data` is always a single line of JSON. - Split the byte stream on a blank line (`\n\n`). A network chunk can end partway through a frame, so keep whatever follows the last blank line in a buffer. The endpoint is a `POST`, so the browser's built-in `EventSource` cannot call it. Use `fetch` with a stream reader, or an SSE client library that supports POST. ## Event catalogue | Event | Sent when | Payload | | --- | --- | --- | | `thinking` | The model starts or finishes reasoning (every turn, unless `thinking` is `none`) | `{ status }` | | `thinking_delta` | A chunk of the reasoning summary (same condition) | `{ delta }` | | `thinking_break` | A new summary paragraph (same condition) | `{}` | | `text_delta` | The model writes text | `{ delta }` | | `tool_called` | The model calls a tool | `{ name, arguments }` | | `search_results` | The agent puts a row of products on screen | `{ label, kind, query, count, results }` | | `suggestions` | The agent offers follow-up chips | `{ suggestions }` | | `question` | The agent asks one or more multiple-choice questions on one card | `{ questionId, question, options, allowFreeText, steps? }` | | `looks` | The agent composes outfits to render | `{ looks: [{ label, items, customInstructions }] }` | | `cart_action` | The agent reads or wants to change the cart | `{ action, ... }` | | `tool_output` | A tool call finishes | `{ name, output }` | | `done` | The turn finished | `{ output, history }` | | `error` | The run failed after the stream opened | `{ error }` | ### thinking, thinking_delta, thinking_break Only on a turn that reasons, which by default is every turn (`low`). A request that sets `thinking` to `none` gets no reasoning and none of these events. A client that ignores them loses nothing. `thinking` marks the start and end of a stretch of reasoning: `{ "status": "started" }` then `{ "status": "done" }`. Show a thinking state between the two. A summary may stream in between as `thinking_delta` chunks, with `thinking_break` between paragraphs, or the provider may send no summary at all for a short stretch — the start/done pair is the reliable signal, the summary is a bonus. The stretch is over when text or a tool call begins. ```json { "status": "started" } { "delta": "They want a dinner look; I'll check dresses and heels first." } { "status": "done" } ``` Set `thinking` in the request to choose for yourself: `none` to switch it off on a turn, `true` for the lightest effort, or a level (`low`, `medium`, `high`, `xhigh`, `max`). A level the model does not accept is a `422` before the stream opens. Reasoning adds about 700 ms to the wait before the first word at `low`; `none` gives that back, at the cost of an occasional turn that ends on a promise with nothing on screen. ### text_delta A piece of the assistant's reply. Append the pieces in order. A turn often writes text in two separate runs: a short opening line before the tools run, and a closing line afterwards. Treat `tool_called` as the end of the current paragraph. ```json { "delta": "Let me pull together a few options." } ``` ### tool_called The model called a tool. `arguments` is the model's raw JSON string, or `null`. Use it to show progress, for example "Searching..." while `lookup_products` runs. ```json { "name": "lookup_products", "arguments": "{\"query\":\"linen wedding shirt\",\"slot\":null,\"family\":[\"shirt\"],\"age_group\":null,\"gender\":\"mens\",\"colors\":null,\"pattern\":null,\"fit\":null,\"materials\":[\"linen\"],\"features\":null,\"minPrice\":null,\"maxPrice\":300,\"onSale\":null,\"exclude_terms\":null,\"limit\":8}" } ``` These tools are always available: `get_articles`, `get_colors`, `get_details`, `lookup_products`, `find_product`, `show_products`, `create_looks`, `ask_question` and `suggest_replies`. When the organization's catalogue is synced from a Shopify store, `list_store_pages` and `read_store_page` let the agent answer policy, FAQ and sizing questions from the store's own pages. When the request includes a `cart`, five more are added: `get_cart`, `add_to_cart`, `set_cart_quantity`, `change_cart_size` and `remove_from_cart`. ### Links in replies The agent's text can contain markdown links. It is instructed to link only to the store's own site: a page it read (as a path, such as `[Our story](https://stylor.ai/pages/our-story)`) or a product. Resolve a path against the storefront page your UI is on. Do not rely on the instruction alone. Before you make a link clickable, check that it stays on the store's site: the same host, or a subdomain of it. Draw anything else as plain text. The hosted widget does this. `mailto:` and `tel:` links are safe to keep. ### tool_output A tool finished. `output` is what the model received. It is usually an object with a `note` written for the model, and sometimes an `error` key. Product searches return short summaries here; the full product records arrive on `search_results`. One exception: when a store page is a picture (a size chart saved as an image), `read_store_page` shows the model that picture. Images are never sent to you. In that case `output` is an array of text parts, with a line of text standing where each picture was. The same applies to `history`: pictures a tool showed the model are replaced by that line before the history is returned. ```json { "name": "lookup_products", "output": { "count": 8, "items": [ { "id": "8f2c1a9e-4b7d", "description": "Coastal Linen Shirt, navy, linen, relaxed fit, $89" } ], "note": "The shopper saw NOTHING. This was for your eyes only." } } ``` An `error` inside `output` is not a failed request. The model reads it and adapts. An invalid dataset scope, for example, shows up only here. When the model's arguments fail validation, `output` is a plain string that starts with `An error occurred while running the tool.` You can show these payloads in a debug view, but don't show them to shoppers. ### search_results A row of products the agent chose to show. `kind` is `outfit` when the items are worn together (at most one per slot) and `list` when they are alternatives, so lay the two out differently. `query` repeats `label`. `results` holds full product records in the agent's chosen order, and that order is part of the recommendation. A turn can include several rows. ```json { "label": "Wedding shirts", "kind": "list", "query": "Wedding shirts", "count": 3, "results": [ { "itemId": "8f2c1a9e-4b7d-4c1e-9a3f-2d6b7e5c1a90", "datasetId": "9c21f0aa-3e4b-4d2a-b6d1-0f7e8a9b1c2d", "status": "active", "metadata": { "gender": "mens", "color_family": "navy", "slot": "top", "family": "shirt" }, "product": { "name": "Coastal Linen Shirt", "url": "https://shop.example.com/products/coastal-linen-shirt", "price": 89, "currency": "USD", "sizes": [{ "label": "M / Navy", "sku": "CLS-NVY-M", "price": 89, "inStock": true }], "assets": { "images": [{ "uploaded": { "key": "org_5f3a/ds_9c21/8f2c1a9e-4b7d/0.jpg" } }] } } } ] } ``` Image `key` values are storage keys, not URLs. Build the URL as `https://stylor.ai/api/v1/image/`, or use `originalImageUrl` instead. ### suggestions Two to four follow-up replies, written as the shopper would say them. They are sent alongside `search_results` or `looks` when the agent attaches them, and by `suggest_replies` after a text-only answer. If a turn sends more than one set, keep the latest. When the shopper taps a chip, send its text as the next user message. The agent never sends chips in the same turn as a `question`. ```json { "suggestions": ["Show me trousers to match", "Something more formal", "Cheaper options"] } ``` ### question A multiple-choice card. The agent has stopped to wait for the answer, so the turn ends shortly after this event. When the shopper picks an option, send that option's `label` as the next user message. If `allowFreeText` is `true`, also let them type their own answer. ```json { "questionId": "5f0e8c3a-2b1d-4e7f-9a6c-3d2e1f0a9b8c", "question": "Who am I styling for?", "options": [ { "label": "Menswear", "value": "mens" }, { "label": "Womenswear", "value": "womens" } ], "allowFreeText": false } ``` A card can ask several questions at once, most often a size for each piece of an outfit going into the cart. It then carries a `steps` array with every question, the first included. `question`, `options` and `allowFreeText` repeat the first step, so a client that ignores `steps` still shows something answerable. ```json { "questionId": "0b9c1f7e-4d2a-4c1b-8e55-7a1d2c3b4e5f", "question": "Which size in the shirt?", "options": [{ "label": "S", "value": "s" }, { "label": "M", "value": "m" }], "allowFreeText": false, "steps": [ { "topic": "Shirt size", "question": "Which size in the shirt?", "options": [{ "label": "S", "value": "s" }, { "label": "M", "value": "m" }], "allowFreeText": false }, { "topic": "Shoe size", "question": "Which size in the loafers?", "options": [{ "label": "9", "value": "9" }, { "label": "10", "value": "10" }], "allowFreeText": false } ] } ``` Let the shopper answer every step, then reply once. Send one user message with a line per step, in order, as `: