@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/raw/docs/runtimes/custom/data-stream.mdx

@@ -1,339 +0,0 @@
----
-title: Data Stream Protocol
-description: Standard message-streaming protocol on top of LocalRuntime.
----
-
-`@assistant-ui/react-data-stream` consumes the data stream protocol, a standardized format for streaming AI responses. It is layered on `LocalRuntime` (see [architecture](/docs/runtimes/concepts/architecture)), so all `LocalRuntime` features apply.
-
-The protocol supports streaming text, tool calls, conversation context, error handling, cancellation, and attachments.
-
-## When to use it
-
-Pick this runtime when:
-
-- Your backend already speaks the data stream protocol (or you can make it do so).
-- You want a thin message-stream contract without writing a `ChatModelAdapter`.
-- You are migrating from AI SDK v4 and want the v4 pattern preserved (see [v4 docs](/docs/runtimes/ai-sdk/v4-legacy)).
-
-If your backend exposes a richer state surface, consider [`AssistantTransport`](/docs/runtimes/custom/assistant-transport) instead.
-
-## Wire protocols
-
-`useDataStreamRuntime` accepts two wire formats. When `protocol` is omitted, it
-detects known Vercel AI response markers before falling back to UI message
-stream for compatibility.
-
-| Protocol | Detection | Matching backend |
-| --- | --- | --- |
-| `"ui-message-stream"` | `x-vercel-ai-ui-message-stream: v1`, otherwise fallback | AI SDK v5+'s `result.toUIMessageStreamResponse()` (SSE) |
-| `"data-stream"` | `x-vercel-ai-data-stream: v1` | `createAssistantStreamResponse` from `assistant-stream`, or AI SDK v4's `toDataStreamResponse()` (Vercel data stream v1) |
-
-Set `protocol` explicitly only for custom endpoints that do not preserve or
-expose the response marker.
-
-## Install
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-data-stream"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-data-stream"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-data-stream", "ink", "react"]} />
-
-</Tab>
-</PlatformTabs>
-
-## Quickstart
-
-<Steps>
-<Step>
-
-### Set up the runtime
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="app/page.tsx"
-"use client";
-
-import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { Thread } from "@/components/assistant-ui/thread";
-
-export default function ChatPage() {
-  const runtime = useDataStreamRuntime({ api: "/api/chat" });
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="app/index.tsx"
-import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import { View } from "react-native";
-import { Thread } from "@/components/assistant-ui/thread";
-
-const API_URL = process.env.EXPO_PUBLIC_API_URL ?? "http://localhost:3000";
-
-export default function ChatPage() {
-  const runtime = useDataStreamRuntime({ api: `${API_URL}/api/chat` });
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <View style={{ flex: 1 }}>
-        <Thread />
-      </View>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="app.tsx"
-import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
-import { Box } from "ink";
-import { Thread } from "./components/thread.js";
-
-export function App() {
-  const runtime = useDataStreamRuntime({
-    api: "http://localhost:3000/api/chat",
-  });
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Box flexDirection="column">
-        <Thread />
-      </Box>
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-</Step>
-<Step>
-
-### Create the backend endpoint
-
-Your backend should accept POST requests and return data stream responses:
-For React Native and Ink, host this endpoint in a separate backend project and
-point the client runtime at its absolute URL.
-
-```ts title="app/api/chat/route.ts"
-import { createAssistantStreamResponse } from "assistant-stream";
-
-export async function POST(request: Request) {
-  const { messages, tools, system, threadId } = await request.json();
-
-  return createAssistantStreamResponse(async (controller) => {
-    const stream = await processWithAI({ messages, tools, system });
-    for await (const chunk of stream) {
-      controller.appendText(chunk.text);
-    }
-  });
-}
-```
-
-The request body includes `messages`, `tools`, `system` (if configured), and `threadId`.
-
-`createAssistantStreamResponse` returns a standard Web `Response`. It drops into any Fetch-style route (Next.js App Router, Hono, Bun.serve, Deno, Cloudflare Workers) without ceremony. On frameworks that use their own response object (Express, Fastify), copy `status` and `headers` over, then pipe `response.body` into the framework's writable stream. Avoid sending the `Response` body into a `res` object whose lifecycle is already controlled by the framework (that is the `ERR_INVALID_STATE: Controller is already closed` failure mode).
-
-</Step>
-</Steps>
-
-## Headers and authentication
-
-```tsx
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  headers: { Authorization: `Bearer ${token}`, "X-Custom-Header": "value" },
-  credentials: "include",
-});
-```
-
-Evaluate per-request:
-
-```tsx
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  headers: async () => ({
-    Authorization: `Bearer ${await getAuthToken()}`,
-  }),
-  body: async () => ({
-    requestId: crypto.randomUUID(),
-    timestamp: Date.now(),
-    signature: await computeSignature(),
-  }),
-});
-```
-
-## Event callbacks
-
-```tsx
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  onResponse: (response) => console.log("status:", response.status),
-  onFinish: (message) => console.log("done:", message),
-  onError: (error) => console.error(error),
-  onCancel: () => console.log("cancelled"),
-});
-```
-
-## Tool integration
-
-<Callout type="warn">
-Human-in-the-loop tools (`unstable_humanToolNames`, `human()` interrupts) are not supported in the data stream runtime. Use [`LocalRuntime`](/docs/runtimes/custom/local-runtime#human-in-the-loop-tools) directly if you need them.
-</Callout>
-
-### Frontend tools
-
-Serialize client-side tools with `toToolsJSONSchema`:
-
-```tsx
-import { tool } from "@assistant-ui/react";
-import { toToolsJSONSchema } from "assistant-stream";
-
-const myTools = {
-  get_weather: tool({
-    description: "Get current weather",
-    parameters: z.object({ location: z.string() }),
-    execute: async ({ location }) => {
-      const weather = await fetchWeather(location);
-      return `Weather in ${location}: ${weather}`;
-    },
-  }),
-};
-
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  body: { tools: toToolsJSONSchema(myTools) },
-});
-```
-
-### Backend tool processing
-
-```ts title="Backend tool handling"
-const { tools } = await request.json();
-const response = await ai.generateText({ messages, tools });
-```
-
-Tool results stream back automatically.
-
-## Message conversion
-
-### Generic (recommended)
-
-```tsx
-import { toGenericMessages, toToolsJSONSchema } from "assistant-stream";
-
-const genericMessages = toGenericMessages(messages);
-const toolSchemas = toToolsJSONSchema(tools);
-```
-
-`GenericMessage` is a union of `system`, `user` (with text and file parts), `assistant` (with text and tool-call parts), and `tool` (with tool-result parts). It is easy to convert to any LLM provider format.
-
-### AI SDK specific
-
-```tsx
-import { toLanguageModelMessages } from "@assistant-ui/react-data-stream";
-
-const languageModelMessages = toLanguageModelMessages(messages, {
-  unstable_includeId: true,
-});
-```
-
-`toLanguageModelMessages` internally uses `toGenericMessages` with AI-SDK-specific transformations. For new integrations prefer `toGenericMessages` directly.
-
-## Assistant Cloud integration
-
-```tsx
-import { useCloudRuntime } from "@assistant-ui/react-data-stream";
-
-const runtime = useCloudRuntime({
-  cloud: assistantCloud,
-  assistantId: "my-assistant-id",
-});
-```
-
-<Callout type="info">
-`useCloudRuntime` is currently under active development and not yet ready for production.
-</Callout>
-
-## LocalRuntimeOptions
-
-`useDataStreamRuntime` accepts every `LocalRuntimeOptions` option in addition to its own. The `chatModel` adapter slot is handled internally and cannot be overridden.
-
-```tsx
-const runtime = useDataStreamRuntime({
-  api: "/api/chat",
-  initialMessages: [
-    { role: "user", content: [{ type: "text", text: "Hello" }] },
-    { role: "assistant", content: [{ type: "text", text: "Hi!" }] },
-  ],
-  maxSteps: 5,
-  cloud, // see "AssistantCloud" in /docs/runtimes/concepts/threads
-  adapters: {
-    attachments: myAttachmentAdapter,
-    history: myHistoryAdapter,
-    speech: mySpeechAdapter,
-    feedback: myFeedbackAdapter,
-    suggestion: mySuggestionAdapter,
-  },
-});
-```
-
-See [adapters](/docs/runtimes/concepts/adapters) for adapter contracts and [LocalRuntime](/docs/runtimes/custom/local-runtime) for inherited options.
-
-## Error handling
-
-The runtime handles common error scenarios automatically:
-
-- Network errors: retried with exponential backoff.
-- Stream interruptions: gracefully handled with partial content preserved.
-- Tool execution errors: displayed in the UI with error states.
-- Cancellation: clean abort signal handling.
-
-## Examples
-
-[`examples/`](https://github.com/assistant-ui/assistant-ui/tree/main/examples) contains reference implementations.
-
-## API reference
-
-For the full hook reference, see [`@assistant-ui/react-data-stream` API](/docs/api-reference/integrations/react-data-stream).
-
-## Related
-
-<Cards>
-  <Card
-    title="LocalRuntime"
-    description="The core runtime data-stream is built on."
-    href="/docs/runtimes/custom/local-runtime"
-  />
-  <Card
-    title="Assistant Transport"
-    description="State-streaming protocol alternative."
-    href="/docs/runtimes/custom/assistant-transport"
-  />
-  <Card
-    title="Adapters"
-    description="Attachments, speech, feedback, history, suggestions."
-    href="/docs/runtimes/concepts/adapters"
-  />
-</Cards>