Chat

What a reply carries

MessageTextis markdown — paragraphs, bold section leads, bullet lists, and inline code, which is how figures arrive (`$63,880`). The SDK doesn’t render it; AssetChat uses the RichText primitive, and a bespoke layer can render it however it likes.

The source line comes from the reply’s message metadata, which lands as the turn finishes:

{
  "type": "message-metadata",
  "messageMetadata": {
    "source": "From your P&L and bank feeds · Books current through Jul 18"
  }
}

Follow-up prompts arrive separately, as a data-suggestionspart on the reply. Each string is both the prompt’s label and the message clicking it sends. A turn carries at most one such part, and may carry none:

{
  "type": "data-suggestions",
  "id": "s1",
  "data": {
    "suggestions": ["Is this month's spending normal?", "How did Q2 compare to Q1?"]
  }
}

The part is persisted on the message, so a conversation reopened from history still offers its follow-ups. They surface as ChatSuggestions, rendered by Suggestion / SuggestionLabel— the same parts that render the starter prompts. Clicking one sends it as the next question.

Graphs

For a comparison question the agent may answer with a graph as well as prose. It arrives as a data-graphpart on the reply — live in the stream and persisted on the message, so a conversation reopened from history re-renders it — and surfaces as a ChatGraph on ChatMessage.graphs:

{
  "type": "data-graph",
  "id": "g_1",
  "data": {
    "type": "bar",
    "title": "Q2 vs Q1 · 2025",
    "summary": { "highlight": "Net profit up 48.3%.", "detail": "Revenue grew $22.5K…" },
    "series": [{ "key": "q1", "label": "Q1 (Jan–Mar)" }, { "key": "q2", "label": "Q2 (Apr–Jun)" }],
    "categories": [
      { "category": "Revenue", "values": [{ "series": "q1", "value": 116000 },
                                          { "series": "q2", "value": 138500 }] }
    ],
    "value_format": "currency",
    "currency": "USD",
    "footnote": "Built from your income and spending for both quarters."
  }
}

A data.type of linearrives the same way, differing only in its x-axis field — points (ordered, oldest first) in place of categories, each still { label, values }. Switch on graph.type to pick a bar or line chart.

The agent sends raw numbers and a valueFormat, never formatted strings — colours and formatting are the frontend’s. Everything a chart needs hangs off one hook, so the drawing itself stays yours:

function Graph() {
  const { graph, rows, groups, formatValue, formatCompactValue } = Chat.useChatGraph();
  // rows: [{ x: "Revenue", q1: 116000, q2: 138500 }, …] — x-axis label under `x`, one key per series
  const Chart = graph.type === "line" ? LineChart : BarChart;
  return <Chart data={rows} series={graph.series} tickFormat={formatCompactValue} />;
}

rowsis the x-axis groups pivoted for a charting library — each row’s label under the reserved x key. groupsis the same axis unpivoted (a bar’s categories or a line’s points, uniformly), for reading the numbers out. formatValue and formatCompactValuerender the graph’s numbers (“$116,000” and “$116K”) honouring its valueFormat and currency. Percentages arrive as whole numbers, so 18.7 means 18.7%, and any value may be negative.

bar and lineare the types today. A graph of any other type — or one missing its series or its x-axis groups — is dropped rather than rendered blank, and data parts the SDK doesn’t recognise are ignored, so a newer agent never breaks an older embed.

Forecasts

A forward-looking question may be answered with a forecast card — a data-forecast part, live in the stream and persisted like a graph, surfaced as a ChatForecast on ChatMessage.forecasts. It is its own part (never a data-graph) because a forecast splits booked history from projection and shades an uncertainty band. Two shapes, discriminated on type: a projection charts one scenario over time, a comparison charts several against each other.

{
  "type": "data-forecast",
  "id": "f_1",
  "data": {
    "type": "projection",
    "forecast_id": "fct_1",
    "scenario_id": "fsc_base",
    "scenario_name": "Base case",
    "title": "Cash through Sep 2026 · base case",
    "summary": { "highlight": "Cash dips to $41K in October." },
    "metric": "closing_cash",
    "currency": "USD",
    "points": [
      { "period": "2026-06", "actual": true,  "value": 22100 },
      { "period": "2026-07", "actual": false, "value": 15400,
        "band": { "p10": 9800, "p90": 21600 } }
    ],
    "readiness": { "status": "needs_input", "confidence": "medium", "summary": "…", "gaps": [ … ] },
    "drivers": [ { "id": "drv_rev", "label": "Monthly revenue", "kind": "revenue",
                   "value": { "mode": "scalar", "value": 48000 }, "source": "derived" } ]
  }
}

The chart reads the whole forecast off useChatForecast(): a projection splits its points at the actual boundary (solid history, dashed projection) and shades the band; a comparison draws a line per scenario over projected periods only (no history boundary — scenarios match over the past), the is_base one emphasised. Everything around the chart is a slottable part: ForecastTitle, ForecastHighlight, ForecastFootnote, the ForecastScenarioslegend, and — behind ForecastDetails / ForecastDetailsToggle — the readiness (ForecastConfidence, ForecastReadinessSummary, ForecastGaps) and driver assumptions (ForecastDrivers).

A gap is a question to the owner: ForecastGapPromptsends its question as the next user message, so the agent can fold the answer back into the forecast — distinct from data-suggestions, which are prompts fromthe user. A forecast the SDK can’t draw (an unknown type, a projection with no points) is dropped, so a newer agent never breaks an older embed.

Persisting conversations

Mount Root without a chatId to start a new conversation. The chat is created on the first message, not on mount, so a user who opens the panel and never types leaves nothing behind. Capture the id from onChatCreated and store it against the user to reopen the conversation later:

const [chatId, setChatId] = useState(savedChatId);

<Chat.Root chatId={chatId} onChatCreated={setChatId}>
  …
</Chat.Root>

Passing a chatId fetches the persisted transcript and renders it. If a turn was still streaming when the page reloaded, Root also rejoins that stream (see resume) so the reply finishes on screen rather than appearing only after a refresh.

Switching conversations needs nothing from you: clicking an entry in the history panel loads that transcript into the window, abandoning any turn in flight and clearing everything scoped to the old conversation (the draft message, the ratings). Swapping the chatId prop does the same, so a host driving the choice from a route works without remounting the Root behind a key.

Only one turn runs per chat at a time — posting a second message while one is in flight would reset the stream, so Submit disables itself for the duration and send() ignores the call.

Turns stream over the Vercel AI SDK’s DefaultChatTransport, which owns the UI message stream protocol. That is an implementation detail: Chat exposes flat ChatMessage objects, so nothing in your app needs to depend on ai or know the wire format.