Send a message to the agent

The model started (status: started) or finished (status: done) a stretch of reasoning. Sent only on a turn that reasons — every turn by default, none of them when the request sets thinking to none. Show a "thinking" state between the two — a summary may or may not follow, so this pair is the reliable signal. The stretch ends when text or a tool call begins.

{
  "status": "started"
}

A chunk of the model's reasoning summary, in order, between a thinking start and done. Written for a reader, not the raw chain of thought, and not part of the reply. Only on a turn that reasons.

{
  "delta": "They want a dinner look; I'll check dresses and heels first."
}

The reasoning summary began a new paragraph. The payload is empty. Only on a turn that reasons.

{}

A chunk of assistant text, in order. Append the chunks to render the reply as it is written. Text can arrive in more than one run inside a turn — typically a short opener before the tools run, and a closing line after — so treat a tool_called event as the end of the current paragraph.

{
  "delta": "Let me pull together a few options."
}

The model invoked a tool. arguments is the raw JSON string the model produced (parse it if you need the values), or null. Useful for showing progress — for instance "Searching…" while lookup_products runs. Tool names: get_articles, get_colors, get_details, lookup_products, find_product, show_products, create_looks, ask_question, suggest_replies; list_store_pages and read_store_page when the organization's catalogue is synced from a Shopify store; and — only when a cart was sent — get_cart, add_to_cart, set_cart_quantity, change_cart_size, remove_from_cart. Anything a tool draws on screen (search_results, looks, question, suggestions, cart_action) is emitted between that tool's tool_called and tool_output. When the model calls several tools in one step, every tool_called for that step arrives first, then the tools' display events in the order the tools produce them, then every tool_output — so match display events by their type, not by position.

{
  "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}"
}

A row of products to display, from show_products. kind is outfit when the items are meant to be worn together (at most one per slot) or list when they are alternatives to choose between — render them differently. query repeats label. results holds full Product records in the order the agent chose, which is part of the recommendation. The agent may emit several rows in one turn.

{
  "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",
        "variants": [
          {
            "variantId": "gid://shopify/ProductVariant/41611609636909",
            "sku": "CLS-NVY-M",
            "label": "M / Navy",
            "options": [
              {
                "name": "Size",
                "value": "M"
              },
              {
                "name": "Color",
                "value": "Navy"
              }
            ],
            "inStock": true,
            "quantity": 4,
            "price": 89,
            "compareAtPrice": null
          }
        ],
        "assets": {
          "images": [
            {
              "uploaded": {
                "key": "org_5f3a/ds_9c21/8f2c1a9e-4b7d/0.jpg"
              }
            }
          ]
        }
      }
    }
  ]
}

Two to four follow-up chips, written in the shopper's voice. Emitted by suggest_replies, and also alongside search_results and looks when the agent attached chips to them. When tapped, send the chip text as the next user message. A turn can emit this more than once; keep the latest. Never shown together with a question card.

{
  "suggestions": [
    "Show me trousers to match",
    "Something more formal",
    "Cheaper options"
  ]
}

A multiple-choice card from ask_question. The agent has stopped to wait for an answer, so the turn ends shortly after this event. Render the options; when the shopper picks one, send the option's label (or their typed text if allowFreeText) as the next user message. questionId is unique per card, for your own bookkeeping. A card can carry several questions — typically a size for each piece of an outfit being added to the cart. It then has a steps array holding every question, the first included, and question, options and allowFreeText repeat the first so a client that ignores steps still shows something answerable. Collect an answer to every step and send them as ONE user message, one line per step in order: <topic>: <label>, e.g. Shirt size: M / White. Do not send them as separate messages; the agent acts on the full set.

{
  "questionId": "5f0e8c3a-2b1d-4e7f-9a6c-3d2e1f0a9b8c",
  "question": "Who am I styling for?",
  "options": [
    {
      "label": "Menswear",
      "value": "mens"
    },
    {
      "label": "Womenswear",
      "value": "womens"
    }
  ],
  "allowFreeText": false
}

One or more complete outfits the agent wants rendered. Each look carries its label, its full Product records in items (two to six per look), and customInstructions — the agent's direction for anything the product photos cannot show, or null. Nothing has been rendered yet: call POST /v2/agent/looks once per look, passing the items' itemIds, the label and customInstructions, and show each image as it returns. The items may include pieces that were never shown as cards.

{
  "looks": [
    {
      "label": "Garden wedding",
      "items": [
        {
          "itemId": "8f2c1a9e-4b7d-4c1e-9a3f-2d6b7e5c1a90",
          "product": {
            "name": "Coastal Linen Shirt",
            "price": 89,
            "currency": "USD"
          }
        },
        {
          "itemId": "1b7e33c0-9a2d-4f8e-b5c6-7d8e9f0a1b2c",
          "product": {
            "name": "Everyday Chino",
            "price": 79,
            "currency": "USD"
          }
        },
        {
          "itemId": "c4d5e6f7-0a1b-4c2d-8e9f-0a1b2c3d4e5f",
          "product": {
            "name": "Suede Loafer",
            "price": 129,
            "currency": "USD"
          }
        }
      ],
      "customInstructions": "Shirt untucked with the top button open; outdoor daylight setting."
    }
  ]
}

The agent read or wants to change the shopper's cart. Only possible when the request carried a cart snapshot. action is one of read, add, quantity, swap or remove, and the rest of the payload depends on it — see the CartAction schema. A read is already satisfied (it was answered from your snapshot) and can be shown as a receipt. Every other action is a request: the server has verified the item, variant and stock, but your client must perform the change on the storefront and show the outcome. add and swap carry an intent token (or null when no sessionId was sent) for reporting the result — see the cart guide.

{
  "action": "add",
  "itemId": "8f2c1a9e-4b7d-4c1e-9a3f-2d6b7e5c1a90",
  "name": "Coastal Linen Shirt",
  "url": "https://shop.example.com/products/coastal-linen-shirt",
  "sku": "CLS-NVY-M",
  "size": "M / Navy",
  "quantity": 1,
  "price": 89,
  "currency": "USD",
  "image": "org_5f3a/ds_9c21/8f2c1a9e-4b7d/0.jpg",
  "intent": "eyJ2IjoxLCJqdGkiOiI3ZjFlIn0.q8vT2rN9…"
}

A tool call finished. output is the value the model saw — usually an object with a note written for the model, sometimes an error key when the tool could not do its job (for example an invalid dataset scope). Product searches return compact summaries here, never full products; the full records travel on search_results. output is a plain string rather than an object when the tool could not run at all — for example when the model produced arguments that failed validation, in which case it reads An error occurred while running the tool. Please try again. Error: …. The agent sees that text and usually retries; it does not end the stream.

{
  "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."
  }
}

The turn finished. output is the assistant's final text (may be an empty string when a card or a row was the whole answer) and history is the complete, replay-ready conversation — every user message, assistant message, tool call and tool result. Store `history` and send it back as `messages` on the next turn. The stream closes after this event.

{
  "output": "All three are linen, so they will breathe on a warm afternoon.",
  "history": [
    {
      "role": "user",
      "content": "I need something for a summer wedding, menswear, under $300."
    },
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Let me pull together a few options."
        }
      ]
    },
    {
      "type": "function_call",
      "callId": "call_8kP2wN7r",
      "name": "show_products",
      "arguments": "{\"label\":\"Wedding shirts\",\"kind\":\"list\",\"itemIds\":[\"8f2c1a9e-4b7d\",\"1b7e33c0-9a2d\",\"c4d5e6f7-0a1b\"],\"suggestions\":[\"Show me trousers to match\",\"Something more formal\"]}",
      "status": "completed"
    },
    {
      "type": "function_call_result",
      "callId": "call_8kP2wN7r",
      "name": "show_products",
      "status": "completed",
      "output": {
        "type": "text",
        "text": "{\"shown\":3,\"note\":\"3 cards are now on the shopper's screen under \\\"Wedding shirts\\\".\"}"
      }
    },
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "All three are linen, so they will breathe on a warm afternoon."
        }
      ]
    }
  ]
}

The run failed after the stream had started — for example the model exceeded the ten-call cap or the model provider returned an error. The HTTP status is already 200; this event is the only signal. The message is always Agent run failed.; the cause is logged on our side. No done follows and no history is returned, so replay the previous turn's history plus the shopper's message to retry. The stream closes after this event.

{
  "error": "Agent run failed."
}