ai 6.0.31 → 6.0.32

package/docs/04-ai-sdk-ui/50-stream-protocol.mdx

@@ -0,0 +1,477 @@
+---
+title: Stream Protocols
+description: Learn more about the supported stream protocols in the AI SDK.
+---
+
+# Stream Protocols
+
+AI SDK UI functions such as `useChat` and `useCompletion` support both text streams and data streams.
+The stream protocol defines how the data is streamed to the frontend on top of the HTTP protocol.
+
+This page describes both protocols and how to use them in the backend and frontend.
+
+You can use this information to develop custom backends and frontends for your use case, e.g.,
+to provide compatible API endpoints that are implemented in a different language such as Python.
+
+For instance, here's an example using [FastAPI](https://github.com/vercel/ai/tree/main/examples/next-fastapi) as a backend.
+
+## Text Stream Protocol
+
+A text stream contains chunks in plain text, that are streamed to the frontend.
+Each chunk is then appended together to form a full text response.
+
+Text streams are supported by `useChat`, `useCompletion`, and `useObject`.
+When you use `useChat` or `useCompletion`, you need to enable text streaming
+by setting the `streamProtocol` options to `text`.
+
+You can generate text streams with `streamText` in the backend.
+When you call `toTextStreamResponse()` on the result object,
+a streaming HTTP response is returned.
+
+<Note>
+  Text streams only support basic text data. If you need to stream other types
+  of data such as tool calls, use data streams.
+</Note>
+
+### Text Stream Example
+
+Here is a Next.js example that uses the text stream protocol:
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { TextStreamChatTransport } from 'ai';
+import { useState } from 'react';
+
+export default function Chat() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat({
+    transport: new TextStreamChatTransport({ api: '/api/chat' }),
+  });
+
+  return (
+    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
+      {messages.map(message => (
+        <div key={message.id} className="whitespace-pre-wrap">
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, i) => {
+            switch (part.type) {
+              case 'text':
+                return <div key={`${message.id}-${i}`}>{part.text}</div>;
+            }
+          })}
+        </div>
+      ))}
+
+      <form
+        onSubmit={e => {
+          e.preventDefault();
+          sendMessage({ text: input });
+          setInput('');
+        }}
+      >
+        <input
+          className="fixed dark:bg-zinc-900 bottom-0 w-full max-w-md p-2 mb-8 border border-zinc-300 dark:border-zinc-800 rounded shadow-xl"
+          value={input}
+          placeholder="Say something..."
+          onChange={e => setInput(e.currentTarget.value)}
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+```ts filename='app/api/chat/route.ts'
+import { streamText, UIMessage, convertToModelMessages } from 'ai';
+__PROVIDER_IMPORT__;
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toTextStreamResponse();
+}
+```
+
+## Data Stream Protocol
+
+A data stream follows a special protocol that the AI SDK provides to send information to the frontend.
+
+The data stream protocol uses Server-Sent Events (SSE) format for improved standardization, keep-alive through ping, reconnect capabilities, and better cache handling.
+
+<Note>
+  When you provide data streams from a custom backend, you need to set the
+  `x-vercel-ai-ui-message-stream` header to `v1`.
+</Note>
+
+The following stream parts are currently supported:
+
+### Message Start Part
+
+Indicates the beginning of a new message with metadata.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"start","messageId":"..."}
+
+```
+
+### Text Parts
+
+Text content is streamed using a start/delta/end pattern with unique IDs for each text block.
+
+#### Text Start Part
+
+Indicates the beginning of a text block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"text-start","id":"msg_68679a454370819ca74c8eb3d04379630dd1afb72306ca5d"}
+
+```
+
+#### Text Delta Part
+
+Contains incremental text content for the text block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"text-delta","id":"msg_68679a454370819ca74c8eb3d04379630dd1afb72306ca5d","delta":"Hello"}
+
+```
+
+#### Text End Part
+
+Indicates the completion of a text block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"text-end","id":"msg_68679a454370819ca74c8eb3d04379630dd1afb72306ca5d"}
+
+```
+
+### Reasoning Parts
+
+Reasoning content is streamed using a start/delta/end pattern with unique IDs for each reasoning block.
+
+#### Reasoning Start Part
+
+Indicates the beginning of a reasoning block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"reasoning-start","id":"reasoning_123"}
+
+```
+
+#### Reasoning Delta Part
+
+Contains incremental reasoning content for the reasoning block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"reasoning-delta","id":"reasoning_123","delta":"This is some reasoning"}
+
+```
+
+#### Reasoning End Part
+
+Indicates the completion of a reasoning block.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"reasoning-end","id":"reasoning_123"}
+
+```
+
+### Source Parts
+
+Source parts provide references to external content sources.
+
+#### Source URL Part
+
+References to external URLs.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"source-url","sourceId":"https://example.com","url":"https://example.com"}
+
+```
+
+#### Source Document Part
+
+References to documents or files.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"source-document","sourceId":"https://example.com","mediaType":"file","title":"Title"}
+
+```
+
+### File Part
+
+The file parts contain references to files with their media type.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"file","url":"https://example.com/file.png","mediaType":"image/png"}
+
+```
+
+### Data Parts
+
+Custom data parts allow streaming of arbitrary structured data with type-specific handling.
+
+Format: Server-Sent Event with JSON object where the type includes a custom suffix
+
+Example:
+
+```
+data: {"type":"data-weather","data":{"location":"SF","temperature":100}}
+
+```
+
+The `data-*` type pattern allows you to define custom data types that your frontend can handle specifically.
+
+### Error Part
+
+The error parts are appended to the message as they are received.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"error","errorText":"error message"}
+
+```
+
+### Tool Input Start Part
+
+Indicates the beginning of tool input streaming.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"tool-input-start","toolCallId":"call_fJdQDqnXeGxTmr4E3YPSR7Ar","toolName":"getWeatherInformation"}
+
+```
+
+### Tool Input Delta Part
+
+Incremental chunks of tool input as it's being generated.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"tool-input-delta","toolCallId":"call_fJdQDqnXeGxTmr4E3YPSR7Ar","inputTextDelta":"San Francisco"}
+
+```
+
+### Tool Input Available Part
+
+Indicates that tool input is complete and ready for execution.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"tool-input-available","toolCallId":"call_fJdQDqnXeGxTmr4E3YPSR7Ar","toolName":"getWeatherInformation","input":{"city":"San Francisco"}}
+
+```
+
+### Tool Output Available Part
+
+Contains the result of tool execution.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"tool-output-available","toolCallId":"call_fJdQDqnXeGxTmr4E3YPSR7Ar","output":{"city":"San Francisco","weather":"sunny"}}
+
+```
+
+### Start Step Part
+
+A part indicating the start of a step.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"start-step"}
+
+```
+
+### Finish Step Part
+
+A part indicating that a step (i.e., one LLM API call in the backend) has been completed.
+
+This part is necessary to correctly process multiple stitched assistant calls, e.g. when calling tools in the backend, and using steps in `useChat` at the same time.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"finish-step"}
+
+```
+
+### Finish Message Part
+
+A part indicating the completion of a message.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"finish"}
+
+```
+
+### Abort Part
+
+Indicates the stream was aborted.
+
+Format: Server-Sent Event with JSON object
+
+Example:
+
+```
+data: {"type":"abort","reason":"user cancelled"}
+
+```
+
+### Stream Termination
+
+The stream ends with a special `[DONE]` marker.
+
+Format: Server-Sent Event with literal `[DONE]`
+
+Example:
+
+```
+data: [DONE]
+
+```
+
+The data stream protocol is supported
+by `useChat` and `useCompletion` on the frontend and used by default.
+`useCompletion` only supports the `text` and `data` stream parts.
+
+On the backend, you can use `toUIMessageStreamResponse()` from the `streamText` result object to return a streaming HTTP response.
+
+### UI Message Stream Example
+
+Here is a Next.js example that uses the UI message stream protocol:
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+
+export default function Chat() {
+  const [input, setInput] = useState('');
+  const { messages, sendMessage } = useChat();
+
+  return (
+    <div className="flex flex-col w-full max-w-md py-24 mx-auto stretch">
+      {messages.map(message => (
+        <div key={message.id} className="whitespace-pre-wrap">
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, i) => {
+            switch (part.type) {
+              case 'text':
+                return <div key={`${message.id}-${i}`}>{part.text}</div>;
+            }
+          })}
+        </div>
+      ))}
+
+      <form
+        onSubmit={e => {
+          e.preventDefault();
+          sendMessage({ text: input });
+          setInput('');
+        }}
+      >
+        <input
+          className="fixed dark:bg-zinc-900 bottom-0 w-full max-w-md p-2 mb-8 border border-zinc-300 dark:border-zinc-800 rounded shadow-xl"
+          value={input}
+          placeholder="Say something..."
+          onChange={e => setInput(e.currentTarget.value)}
+        />
+      </form>
+    </div>
+  );
+}
+```
+
+```ts filename='app/api/chat/route.ts'
+import { streamText, UIMessage, convertToModelMessages } from 'ai';
+__PROVIDER_IMPORT__;
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages }: { messages: UIMessage[] } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```

package/docs/04-ai-sdk-ui/index.mdx

@@ -0,0 +1,64 @@
+---
+title: AI SDK UI
+description: Learn about the AI SDK UI.
+---
+
+# AI SDK UI
+
+<IndexCards
+  cards={[
+    {
+      title: 'Overview',
+      description: 'Get an overview about the AI SDK UI.',
+      href: '/docs/ai-sdk-ui/overview'
+    },
+    {
+      title: 'Chatbot',
+      description: 'Learn how to integrate an interface for a chatbot.',
+      href: '/docs/ai-sdk-ui/chatbot'
+    },
+    {
+      title: 'Chatbot Message Persistence',
+      description: 'Learn how to store and load chat messages in a chatbot.',
+      href: '/docs/ai-sdk-ui/chatbot-message-persistence'
+    },
+    {
+      title: 'Chatbot Tool Usage',
+      description:
+        'Learn how to integrate an interface for a chatbot with tool calling.',
+      href: '/docs/ai-sdk-ui/chatbot-tool-usage'
+    },
+    {
+      title: 'Completion',
+      description: 'Learn how to integrate an interface for text completion.',
+      href: '/docs/ai-sdk-ui/completion'
+    },
+    {
+      title: 'Object Generation',
+      description: 'Learn how to integrate an interface for object generation.',
+      href: '/docs/ai-sdk-ui/object-generation'
+    },
+    {
+      title: 'Streaming Data',
+      description: 'Learn how to stream data.',
+      href: '/docs/ai-sdk-ui/streaming-data'
+    },
+    {
+      title: 'Reading UI Message Streams',
+      description: 'Learn how to read UIMessage streams for terminal UIs, custom clients, and server components.',
+      href: '/docs/ai-sdk-ui/reading-ui-message-streams'
+    },
+    {
+      title: 'Error Handling',
+      description: 'Learn how to handle errors.',
+      href: '/docs/ai-sdk-ui/error-handling'
+    },
+    {
+      title: 'Stream Protocol',
+      description:
+        'The stream protocol defines how data is sent from the backend to the AI SDK UI frontend.',
+      href: '/docs/ai-sdk-ui/stream-protocol'
+    }
+
+]}
+/>

package/docs/05-ai-sdk-rsc/01-overview.mdx

@@ -0,0 +1,45 @@
+---
+title: Overview
+description: An overview of AI SDK RSC.
+---
+
+# AI SDK RSC
+
+<Note type="warning">
+  AI SDK RSC is currently experimental. We recommend using [AI SDK
+  UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from
+  RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui).
+</Note>
+
+<Note>
+  The `@ai-sdk/rsc` package is compatible with frameworks that support React
+  Server Components.
+</Note>
+
+[React Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) (RSC) allow you to write UI that can be rendered on the server and streamed to the client. RSCs enable [ Server Actions ](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations#with-client-components), a new way to call server-side code directly from the client just like any other function with end-to-end type-safety. This combination opens the door to a new way of building AI applications, allowing the large language model (LLM) to generate and stream UI directly from the server to the client.
+
+## AI SDK RSC Functions
+
+AI SDK RSC has various functions designed to help you build AI-native applications with React Server Components. These functions:
+
+1. Provide abstractions for building Generative UI applications.
+   - [`streamUI`](/docs/reference/ai-sdk-rsc/stream-ui): calls a model and allows it to respond with React Server Components.
+   - [`useUIState`](/docs/reference/ai-sdk-rsc/use-ui-state): returns the current UI state and a function to update the UI State (like React's `useState`). UI State is the visual representation of the AI state.
+   - [`useAIState`](/docs/reference/ai-sdk-rsc/use-ai-state): returns the current AI state and a function to update the AI State (like React's `useState`). The AI state is intended to contain context and information shared with the AI model, such as system messages, function responses, and other relevant data.
+   - [`useActions`](/docs/reference/ai-sdk-rsc/use-actions): provides access to your Server Actions from the client. This is particularly useful for building interfaces that require user interactions with the server.
+   - [`createAI`](/docs/reference/ai-sdk-rsc/create-ai): creates a client-server context provider that can be used to wrap parts of your application tree to easily manage both UI and AI states of your application.
+2. Make it simple to work with streamable values between the server and client.
+   - [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value): creates a stream that sends values from the server to the client. The value can be any serializable data.
+   - [`readStreamableValue`](/docs/reference/ai-sdk-rsc/read-streamable-value): reads a streamable value from the client that was originally created using `createStreamableValue`.
+   - [`createStreamableUI`](/docs/reference/ai-sdk-rsc/create-streamable-ui): creates a stream that sends UI from the server to the client.
+   - [`useStreamableValue`](/docs/reference/ai-sdk-rsc/use-streamable-value): accepts a streamable value created using `createStreamableValue` and returns the current value, error, and pending state.
+
+## Templates
+
+Check out the following templates to see AI SDK RSC in action.
+
+<Templates type="generative-ui" />
+
+## API Reference
+
+Please check out the [AI SDK RSC API Reference](/docs/reference/ai-sdk-rsc) for more details on each function.