Vercel AI SDK

This guide is OPTIONAL.

Use it only if your app already uses Vercel AI SDK or you want that specific loop style.

ToonUI does NOT require Vercel AI SDK.

The important rule with Vercel AI SDK is simple:

Let the model generate ToonUI, but let your app keep the chat state and side effects.

Recommended pattern

Use toon.messages.toUIMessage(payload) to append structured user intent back into useChat-style state.

onReply={(payload) => {
  const next = toon.messages.toUIMessage(payload);
  append(next);
}}

Why this matters

This keeps three things separate:

• the model output
• the rendered interaction surface
• the app-owned message loop

When to use toModelMessage

If your host loop expects a compact normalized user message for the next model turn, use:

const next = toon.messages.toModelMessage(payload);

That gives you:

• content for the model
• displayContent for UI
• the original typed payload

Practical rule

• use toUIMessage() for UI state
• use toModelMessage() for LLM loop integration

What ToonUI already resolves vs what you still compose

Recommended composition

Use this mental model:

• ToonUI owns the protocol
• your app owns the message history
• AI SDK owns the transport and message loop

So the right composition is:

const system = prependToonProtocolPrompt(systemPrompt, toon.prompt);

ToonUI gives you the protocol prompt.

Your app still decides how to merge that prompt with the rest of your system instructions and how to read arbitrary stored UIMessage objects.

Read next

1. Events and Messages
2. React Runtime and Hooks