@assistant-ui/mcp-docs-server 0.1.31 → 0.1.33

package/.docs/raw/docs/integrations/frameworks/cloudflare-agents/overview.mdx

@@ -0,0 +1,282 @@
+---
+title: Cloudflare Agents Integration
+description: Wire Cloudflare's stateful agent framework into a React chat UI with assistant-ui via the standard AI SDK runtime. WebSocket transport, server-side persistence, tool calling, all preserved.
+---
+
+import { CloudflareIcon } from "@/components/icons/cloudflare";
+import { VercelIcon } from "@/components/icons/vercel";
+
+[Cloudflare Agents](https://developers.cloudflare.com/agents/) is Cloudflare's framework for stateful AI agents that run on Durable Objects at the edge. Each agent owns its own SQLite-backed message history, exposes a WebSocket channel for low-latency streaming, and can call tools (server-side or client-side).
+
+<Callout type="info">
+This is an integration guide, not a runtime adapter. assistant-ui does not ship a `@assistant-ui/react-cloudflare-agents` package. `@cloudflare/ai-chat`'s `useAgentChat` returns a structural extension of the AI SDK's `useChat`, so the existing [AI SDK runtime](/docs/runtimes/ai-sdk/v6) consumes it directly.
+</Callout>
+
+## Architecture
+
+Cloudflare Agents handles the server half: a Durable Object subclasses `AIChatAgent` from `@cloudflare/ai-chat`, owns the message history, and streams responses back over a WebSocket. `@cloudflare/ai-chat/react`'s `useAgentChat` hook wraps that WebSocket and exposes the same `messages`, `sendMessage`, `regenerate`, `status`, `stop`, `setMessages`, `addToolOutput` surface that the AI SDK's `useChat` does, plus a few Cloudflare-specific extras (`clearHistory`, `isServerStreaming`, `isToolContinuation`).
+
+assistant-ui handles the client half. `useAISDKRuntime` from [`@assistant-ui/react-ai-sdk`](/docs/runtimes/ai-sdk/v6) reads exactly those AI SDK methods off whatever you pass in, so feeding it `useAgentChat`'s return value yields a fully-featured runtime: streaming, tool calling, edit, reload, history import and export, attachments, suggestions.
+
+Shared adapters (attachments, speech, feedback, history) work the same way as described in [adapters](/docs/runtimes/concepts/adapters). Multi-thread support needs a [custom thread list](/docs/runtimes/concepts/threads) wired around `useAISDKRuntime`; [AssistantCloud](/docs/cloud) integrates via `useChatRuntime` (which constructs its own `useChat` internally) and is not compatible with the `useAgentChat` wiring shown here.
+
+## Requirements
+
+- A Cloudflare account with Workers enabled and `wrangler` installed.
+- A frontend project (Next.js or any other AI-SDK-compatible React app).
+- Model API keys (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.) configured as Worker secrets.
+
+## Setup
+
+The setup has two halves. Steps 1 to 4 happen in the **Worker** project (Cloudflare side); steps 5 to 7 happen in a **separate assistant-ui frontend**. You'll have two dev processes running by the end: `wrangler dev` for the Worker, and your frontend's dev server.
+
+<Steps>
+
+<Step>
+
+### Scaffold the Worker project
+
+```sh
+npm create cloudflare@latest my-agent -- --type=hello-world --ts
+cd my-agent
+```
+
+Add the Cloudflare Agents packages and the AI SDK:
+
+<InstallCommand npm={["agents@0.12.4", "@cloudflare/ai-chat@0.7.0", "ai@latest", "@ai-sdk/openai@latest"]} />
+
+The two Cloudflare packages above are pinned to exact versions because `agents` and `@cloudflare/ai-chat` are pre-1.0 and ship breaking changes between minor releases. See [version stability](#version-stability) below before bumping them.
+
+</Step>
+
+<Step>
+
+### Define the agent
+
+`AIChatAgent` already implements message persistence, streaming protocol, and WebSocket plumbing. Override `onChatMessage` to plug in your model and tools.
+
+```ts title="src/chat.ts"
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { openai } from "@ai-sdk/openai";
+import { streamText, convertToModelMessages } from "ai";
+
+export type Env = {
+  OPENAI_API_KEY: string;
+  Chat: DurableObjectNamespace<Chat>;
+};
+
+export class Chat extends AIChatAgent<Env> {
+  async onChatMessage(onFinish: Parameters<typeof streamText>[0]["onFinish"]) {
+    return streamText({
+      model: openai("gpt-5.4-nano"),
+      messages: await convertToModelMessages(this.messages),
+      onFinish,
+    });
+  }
+}
+```
+
+`Env` is exported alongside `Chat` so the Worker entry point can reuse the same type. The `Chat: DurableObjectNamespace<Chat>` field mirrors the binding declared in `wrangler.jsonc` (next step) and is what `routeAgentRequest` looks up to resolve the agent. `DurableObjectNamespace` is a global from `@cloudflare/workers-types`, which the `npm create cloudflare` scaffold sets up by default.
+
+`this.messages` is the persisted history for this Durable Object instance. Each unique agent `name` you connect with from the client (step 7) gets its own instance and its own message log.
+
+</Step>
+
+<Step>
+
+### Register the Durable Object and route requests
+
+```ts title="src/index.ts"
+import { routeAgentRequest } from "agents";
+import { Chat, type Env } from "./chat";
+
+export { Chat };
+
+const cors = (request: Request) => ({
+  "Access-Control-Allow-Origin": request.headers.get("Origin") ?? "*",
+  "Access-Control-Allow-Headers": "Content-Type, Upgrade",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+});
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    if (request.method === "OPTIONS") {
+      return new Response(null, { headers: cors(request) });
+    }
+    const upstream =
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 });
+    const res = new Response(upstream.body, upstream);
+    for (const [k, v] of Object.entries(cors(request))) res.headers.set(k, v);
+    return res;
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`routeAgentRequest` handles WebSocket upgrades, agent lookup by URL path, and the `/get-messages` HTTP endpoint that the frontend uses for history rehydration. The `cors` helper reflects the request origin so the frontend can talk to the Worker across ports during local development. WebSocket upgrades bypass CORS in the browser, but the `/get-messages` HTTP fetch and any custom routes need these headers. For production, replace the wildcard fallback with an explicit allowlist.
+
+Wire the Durable Object binding in `wrangler.jsonc`:
+
+```jsonc title="wrangler.jsonc"
+{
+  "name": "my-agent",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [{ "name": "Chat", "class_name": "Chat" }]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["Chat"] }
+  ]
+}
+```
+
+The binding `name` and `class_name` must match the exported class. `new_sqlite_classes` is required so the Durable Object can use SQLite for message storage.
+
+</Step>
+
+<Step>
+
+### Run the Worker locally
+
+Local `wrangler dev` reads environment variables from a `.dev.vars` file in the project root (not from the remote secret store):
+
+```sh title=".dev.vars"
+OPENAI_API_KEY=sk-...
+```
+
+```sh
+wrangler dev
+```
+
+For production, upload the same key as a deployed Worker secret before `wrangler deploy`:
+
+```sh
+wrangler secret put OPENAI_API_KEY
+```
+
+The Worker boots on `http://localhost:8787`. Leave it running.
+
+</Step>
+
+<Step>
+
+### Initialize the assistant-ui frontend
+
+In a different directory:
+
+```sh title="New project"
+npx assistant-ui@latest create
+```
+
+```sh title="Existing project"
+npx assistant-ui@latest init
+```
+
+This creates a default chat page and a local API route at `app/api/chat/route.ts`. You won't use the local route, since the agent runs on the Worker; delete it once the next step is wired.
+
+</Step>
+
+<Step>
+
+### Install the Cloudflare client packages
+
+In the frontend project:
+
+<InstallCommand npm={["agents@0.12.4", "@cloudflare/ai-chat@0.7.0"]} />
+
+</Step>
+
+<Step>
+
+### Wire the runtime
+
+```tsx title="app/assistant.tsx"
+"use client";
+
+import { useAgent } from "agents/react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
+import { Thread } from "@/components/assistant-ui/thread";
+
+export const Assistant = () => {
+  const agent = useAgent({
+    agent: "Chat",
+    name: "default",
+    host: process.env.NEXT_PUBLIC_AGENT_HOST!,
+  });
+  const chat = useAgentChat({ agent });
+  const runtime = useAISDKRuntime(chat);
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+};
+```
+
+Set the Worker URL in your frontend environment:
+
+```sh title=".env.local"
+NEXT_PUBLIC_AGENT_HOST=http://localhost:8787
+```
+
+`NEXT_PUBLIC_*` exposes the value to the browser. In production, point this at your deployed Worker (e.g. `https://my-agent.example.workers.dev`).
+
+`name: "default"` is the Durable Object instance key. Pass a per-user value (a user ID, session ID, or chat ID) to give each user their own persisted history. Switching `name` from the client opens a new WebSocket connection to a different Durable Object instance.
+
+</Step>
+
+</Steps>
+
+## Notes
+
+### Type compatibility with `useChat`
+
+`useAgentChat`'s return type is `Omit<ReturnType<typeof useChat>, "addToolOutput"> & { ... }`. The `addToolOutput` option shape differs slightly between the two: `useChat` accepts `{ state, tool, toolCallId, ... }`; `useAgentChat` accepts `{ state, toolCallId, toolName?, ... }`. At runtime the call paths converge through `useAISDKRuntime` without issue (verified against `@cloudflare/ai-chat@0.7.0`). If the TypeScript compiler flags the call, cast at the call site: `useAISDKRuntime(chat as Parameters<typeof useAISDKRuntime>[0])`, or `chat as unknown as Parameters<typeof useAISDKRuntime>[0]` if TypeScript still refuses the direct cast. (`satisfies` does not help here; it validates assignability without changing the inferred type, so it surfaces the same error.)
+
+### Cloudflare-specific extras
+
+`useAgentChat` exposes three values that `useChat` does not:
+
+- `clearHistory()` sends a `cf_agent_chat_clear` frame and wipes the Durable Object's SQLite store. Bind it to a "Clear chat" button if you need server-side history reset; `setMessages([])` alone only clears the client view.
+- `isServerStreaming` is `true` while the server is pushing tokens, independent of client-initiated request state. Use it for a universal streaming indicator.
+- `isToolContinuation` distinguishes "server auto-continuing after a tool result" from "user just sent a new message". Useful for typing-indicator gating.
+
+Destructure these alongside `chat` and pass them into your UI directly; they don't need to flow through the runtime.
+
+### `setMessages` round-trips through the Durable Object
+
+`useAgentChat` overrides `setMessages` to broadcast the new list over the WebSocket so the Durable Object's SQLite history stays in sync. This means assistant-ui's `onImport`, `onEdit`, `onReload`, and pending-tool cancellation paths all persist server-side automatically. The tradeoff is one extra WebSocket round-trip per mutation, which can race if the connection is lagging; assume eventual consistency, not transactional.
+
+### Authenticate the Worker before going to production
+
+`routeAgentRequest` accepts any client that knows the agent class and `name`. If you derive `name` from a user ID (as recommended for per-user history), any client that knows or guesses another user's ID can connect to that Durable Object and read its full message log. Before deploying:
+
+- Gate the fetch handler with a header or cookie check (e.g. a JWT issued by your auth backend), and only call `routeAgentRequest` after the request is authenticated.
+- Pass the same credential from the frontend via `useAgent`'s `headers` or `query` options so the WebSocket upgrade carries it.
+- Tighten the CORS `Access-Control-Allow-Origin` to an explicit allowlist; the wildcard in the example above is for local development only.
+
+### Version stability
+
+`agents` and `@cloudflare/ai-chat` are pre-1.0 and ship breaking changes between minor versions. Pin both to exact versions in `package.json` and read the Cloudflare changelog before bumping. The `useAgentChat` return shape has been additive since 0.3.0, so the integration above should keep working across patch releases.
+
+## Related
+
+<Cards>
+  <Card
+    icon={<CloudflareIcon width={20} height={20} />}
+    title="Cloudflare Agents docs"
+    description="Cloudflare's official guide: Durable Object lifecycle, WebSocket protocol, tool patterns, multi-agent routing."
+    href="https://developers.cloudflare.com/agents/"
+  />
+  <Card
+    icon={<VercelIcon width={20} height={20} />}
+    title="AI SDK runtime"
+    description="The runtime that handles the client side of this integration."
+    href="/docs/runtimes/ai-sdk/v6"
+  />
+</Cards>

package/.docs/raw/docs/integrations/frameworks/mastra/overview.mdx

@@ -1,6 +1,6 @@
 ---
-title: Overview
-description: Wire up the Mastra TypeScript agent framework with assistant-ui.
+title: Mastra Integration
+description: Wire the Mastra TypeScript agent framework into a React chat UI with assistant-ui — full streaming, tool calling, multi-agent support, and thread management.
 ---
 
 import { MastraIcon } from "@/components/icons/mastra";

package/.docs/raw/docs/integrations/frameworks/mastra/separate-server.mdx

@@ -50,7 +50,7 @@ export const chefAgent = new Agent({
   instructions:
     "You are Michel, a practical and experienced home chef. " +
     "You help people cook with whatever ingredients they have available.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.4-nano",
 });
 ```
 

package/.docs/raw/docs/integrations/gateways/index.mdx

@@ -1,8 +1,11 @@
 ---
-title: LLM gateways
-description: Route assistant-ui traffic through OpenAI-compatible gateways for cost, fallback, and BYOK.
+title: LLM Gateway Integrations
+description: Route AI chat traffic through OpenAI-compatible LLM gateways (OpenRouter, LiteLLM, Portkey, etc.) for cost, fallback, and BYOK in assistant-ui apps.
 ---
 
+import { HeliconeIcon } from "@/components/icons/helicone";
+import { VercelIcon } from "@/components/icons/vercel";
+
 LLM gateways sit between your route handler and the upstream provider. They give you a single endpoint that fronts many providers, plus features like multi-provider fallback, prompt caching, and BYOK (bring-your-own-key) flows. Most are OpenAI API-compatible, so the integration is a `baseURL` swap on `createOpenAI` from `@ai-sdk/openai`.
 
 For pure observability (proxy that logs every call) see [Helicone](/docs/integrations/observability/helicone). The gateways here overlap in spirit but are positioned around routing rather than logging.
@@ -45,7 +48,7 @@ The rest of this page is what to put in `baseURL`, `headers`, and `model(...)` f
 
 ## OpenRouter
 
-[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4`, `openai/gpt-5.4-mini`, `meta-llama/llama-3.3-70b-instruct`).
+[OpenRouter](https://openrouter.ai/) aggregates 100+ models behind one OpenAI-compatible endpoint. The model ID is `provider/model` (e.g., `anthropic/claude-sonnet-4.6`, `openai/gpt-5.4-mini`, `meta-llama/llama-3.3-70b-instruct`).
 
 ```sh title=".env.local"
 OPENROUTER_API_KEY=sk-or-...
@@ -69,7 +72,7 @@ const openrouter = createOpenAI({
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const result = streamText({
-    model: openrouter("anthropic/claude-sonnet-4"),
+    model: openrouter("anthropic/claude-sonnet-4.6"),
     messages: await convertToModelMessages(messages),
   });
   return result.toUIMessageStreamResponse();
@@ -145,11 +148,13 @@ When to pick: self-host requirement, BYOK metering for end-users, or unified bil
 
 <Cards>
   <Card
+    icon={<HeliconeIcon width={20} height={20} />}
     title="Helicone"
     description="The observability-first proxy. Same shape, different goal."
     href="/docs/integrations/observability/helicone"
   />
   <Card
+    icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries gateway responses to the chat UI."
     href="/docs/runtimes/ai-sdk/v6"

package/.docs/raw/docs/integrations/index.mdx

@@ -1,11 +1,15 @@
 ---
 title: Integrations
-description: Third-party services and adapter recipes that plug into a working assistant-ui app.
+description: Adapters for Vercel AI SDK, LangChain, LangGraph, Mastra, plus auth, persistence, observability, and tool services — drop into a React chat UI built with assistant-ui.
 ---
 
+import { CloudflareIcon } from "@/components/icons/cloudflare";
+import { HeliconeIcon } from "@/components/icons/helicone";
 import { MastraIcon } from "@/components/icons/mastra";
-import { VercelIcon } from "@/components/icons/vercel";
+import { LangfuseIcon } from "@/components/icons/langfuse";
 import { LangChainIcon } from "@/components/icons/langchain";
+import { McpIcon } from "@/components/icons/mcp";
+import { VercelIcon } from "@/components/icons/vercel";
 
 Integrations are wiring guides for using third-party services with assistant-ui, plus canonical recipes for the adapter slots (persistence, attachments). They are distinct from [runtimes](/docs/runtimes/pick-a-runtime), which are the React adapter packages (`@assistant-ui/react-ai-sdk`, `@assistant-ui/react-langgraph`, etc.) that connect the UI to a backend. An integration assumes you already have a working runtime and adds something on top.
 
@@ -39,6 +43,12 @@ Framework integrations that pair with assistant-ui at the API-route layer.
     href="/docs/integrations/frameworks/ai-sdk"
   />
   <PlatformOnly platforms={["react"]}>
+    <Card
+      icon={<CloudflareIcon width={20} height={20} />}
+      title="Cloudflare Agents"
+      description="Stateful Durable Object agents. Wired through the AI SDK runtime with WebSocket streaming."
+      href="/docs/integrations/frameworks/cloudflare-agents/overview"
+    />
     <Card
       icon={<MastraIcon width={20} height={20} />}
       title="Mastra"
@@ -50,13 +60,14 @@ Framework integrations that pair with assistant-ui at the API-route layer.
 
 ## Tools
 
-Pluggable tool catalogs and protocols.
+Tool catalogs and protocols have their own [Tools](/docs/tools) section.
 
 <Cards>
   <Card
+    icon={<McpIcon width={20} height={20} />}
     title="Model Context Protocol (MCP)"
     description="Connect any MCP server as a tool catalog through the AI SDK MCP client."
-    href="/docs/integrations/tools/mcp"
+    href="/docs/tools/mcp"
   />
 </Cards>
 
@@ -78,12 +89,13 @@ Log, monitor, trace, and evaluate LLM calls. These pair with any runtime.
 
 <Cards>
   <Card
+    icon={<HeliconeIcon width={20} height={20} />}
     title="Helicone"
     description="Observability proxy. Drop-in baseURL swap that logs cost, latency, and prompts."
     href="/docs/integrations/observability/helicone"
   />
   <Card
-    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    icon={<LangfuseIcon width={20} height={20} />}
     title="Langfuse"
     description="OpenTelemetry-based tracing and evals. Open source, self-hostable."
     href="/docs/integrations/observability/langfuse"

package/.docs/raw/docs/integrations/observability/langfuse.mdx

@@ -3,6 +3,10 @@ title: Langfuse
 description: Trace AI SDK calls into Langfuse via OpenTelemetry for tracing, evals, and prompt management.
 ---
 
+import { HeliconeIcon } from "@/components/icons/helicone";
+import { LangChainIcon } from "@/components/icons/langchain";
+import { VercelIcon } from "@/components/icons/vercel";
+
 [Langfuse](https://langfuse.com/) is an open-source LLM observability platform. It gives you a hierarchical trace per request (planner → tool calls → final LLM step), prompt-level analytics, datasets, and LLM-as-judge evals. Self-hostable, OpenTelemetry-native.
 
 Pick Langfuse when you want to see the agent's full call tree inside a single turn. It's complementary to [Helicone](/docs/integrations/observability/helicone), which proxies and logs individual provider calls; many teams run both, with Helicone capturing the request log and Langfuse capturing the trace.
@@ -99,7 +103,7 @@ export async function POST(req: Request) {
     { traceName: "chat-completion", userId, sessionId },
     async () =>
       streamText({
-        model: openai("gpt-4o"),
+        model: openai("gpt-5.4-nano"),
         messages: await convertToModelMessages(messages),
         experimental_telemetry: { isEnabled: true },
       }),
@@ -139,16 +143,19 @@ If nothing appears, check the server logs for OTel errors and confirm `LANGFUSE_
 
 <Cards>
   <Card
+    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
     title="LangSmith"
     description="LangChain ecosystem alternative, uses wrapAISDK instead of OpenTelemetry."
     href="/docs/integrations/observability/langsmith"
   />
   <Card
+    icon={<HeliconeIcon width={20} height={20} />}
     title="Helicone"
     description="Proxy-based request logging with cost, latency, and prompt diffs per call."
     href="/docs/integrations/observability/helicone"
   />
   <Card
+    icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that emits the telemetry Langfuse consumes."
     href="/docs/runtimes/ai-sdk/v6"

package/.docs/raw/docs/integrations/observability/langsmith.mdx

@@ -3,7 +3,9 @@ title: LangSmith
 description: Trace AI SDK calls into LangSmith with the wrapAISDK helper.
 ---
 
-import { LangChainIcon } from "@/components/icons/langchain";
+import { LangfuseIcon } from "@/components/icons/langfuse";
+import { LangGraphIcon } from "@/components/icons/langgraph";
+import { VercelIcon } from "@/components/icons/vercel";
 
 [LangSmith](https://www.langchain.com/langsmith) is LangChain's observability and eval platform. If you are already in the LangChain or LangGraph ecosystem, LangSmith is the natural pairing: traces, datasets, prompt versioning, and LLM-as-judge evals share state with the rest of the LangChain stack.
 
@@ -60,7 +62,7 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
 
   const result = streamText({
-    model: openai("gpt-4o"),
+    model: openai("gpt-5.4-nano"),
     messages: await ai.convertToModelMessages(messages),
   });
 
@@ -81,7 +83,7 @@ Pass a `langsmith` provider option to tag traces with user, session, or run iden
 import { createLangSmithProviderOptions } from "langsmith/experimental/vercel";
 
 const result = streamText({
-  model: openai("gpt-4o"),
+  model: openai("gpt-5.4-nano"),
   messages: await ai.convertToModelMessages(messages),
   providerOptions: {
     langsmith: createLangSmithProviderOptions({
@@ -128,17 +130,19 @@ Send a message. The trace should appear in your LangSmith project within seconds
 
 <Cards>
   <Card
-    icon={<LangChainIcon width={20} height={20} className="text-[#7FC8FF]" />}
+    icon={<LangGraphIcon width={20} height={20} className="text-[#1C3C3C] dark:text-[#5b9595]" />}
     title="LangGraph runtime"
     description="If your backend is LangGraph, tracing flows through LangGraph Cloud automatically."
     href="/docs/runtimes/langgraph"
   />
   <Card
+    icon={<LangfuseIcon width={20} height={20} />}
     title="Langfuse"
     description="OpenTelemetry-based alternative; OSS and self-hostable."
     href="/docs/integrations/observability/langfuse"
   />
   <Card
+    icon={<VercelIcon width={20} height={20} />}
     title="AI SDK runtime"
     description="The runtime that ferries traces from the route to the chat UI."
     href="/docs/runtimes/ai-sdk/v6"

package/.docs/raw/docs/integrations/persistence/custom-adapter.mdx

@@ -65,7 +65,22 @@ export const messages = pgTable(
 );
 ```
 
-The four message columns (`id`, `parent_id`, `format`, `content`) are the contract `withFormat` writes against. `format` lets multiple runtimes coexist on one row (e.g., `"aisdk-v6"` from `useChatRuntime`, a different value from another runtime).
+The four message columns (`id`, `parent_id`, `format`, `content`) are the contract `withFormat` writes against. `format` records which adapter encoded the row so multiple runtimes can coexist on one table; `useChatRuntime` sets it from `fmt.format`.
+
+<Callout type="warn">
+  `content` is not arbitrary JSON. It must be the payload the active format adapter produced via `fmt.encode(item)`, and it is read back through `fmt.decode`; the route handlers below are a pass-through that never inspects it. For `useChatRuntime` (AI SDK v6) a valid stored row looks like:
+
+  ```json
+  {
+    "id": "msg_abc",
+    "parent_id": null,
+    "format": "ai-sdk/v6",
+    "content": { "role": "user", "parts": [{ "type": "text", "text": "hello" }] }
+  }
+  ```
+
+  A row that satisfies the column types but carries a different shape (e.g. `{ "foo": "bar" }`) is accepted on write, then fails history reload. Seed test data through the adapter, not by hand-crafting `content`.
+</Callout>
 
 ## Setup
 
@@ -678,7 +693,7 @@ Send a message in a fresh thread. Check the database:
 
 - The `threads` table has a new row with the current `userId`.
 - The `messages` table has at least two rows (user + assistant) for that thread.
-- `format` is `"aisdk-v6"` (or whatever AI SDK's current format string is).
+- `format` matches what `fmt.format` wrote (`"ai-sdk/v6"` for AI SDK v6) and `content` is the encoded `UIMessage` (a `role` plus `parts`), not a placeholder blob.
 - Reload the page; the thread list and the messages survive.
 
 </Step>