ai 6.0.31 → 6.0.32

package/docs/05-ai-sdk-rsc/04-multistep-interfaces.mdx

@@ -0,0 +1,282 @@
+---
+title: Multistep Interfaces
+description: Overview of Building Multistep Interfaces with AI SDK RSC
+---
+
+# Designing Multistep Interfaces
+
+<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>
+
+Multistep interfaces refer to user interfaces that require multiple independent steps to be executed in order to complete a specific task.
+
+For example, if you wanted to build a Generative UI chatbot capable of booking flights, it could have three steps:
+
+- Search all flights
+- Pick flight
+- Check availability
+
+To build this kind of application you will leverage two concepts, **tool composition** and **application context**.
+
+**Tool composition** is the process of combining multiple [tools](/docs/ai-sdk-core/tools-and-tool-calling) to create a new tool. This is a powerful concept that allows you to break down complex tasks into smaller, more manageable steps. In the example above, _"search all flights"_, _"pick flight"_, and _"check availability"_ come together to create a holistic _"book flight"_ tool.
+
+**Application context** refers to the state of the application at any given point in time. This includes the user's input, the output of the language model, and any other relevant information. In the example above, the flight selected in _"pick flight"_ would be used as context necessary to complete the _"check availability"_ task.
+
+## Overview
+
+In order to build a multistep interface with `@ai-sdk/rsc`, you will need a few things:
+
+- A Server Action that calls and returns the result from the `streamUI` function
+- Tool(s) (sub-tasks necessary to complete your overall task)
+- React component(s) that should be rendered when the tool is called
+- A page to render your chatbot
+
+The general flow that you will follow is:
+
+- User sends a message (calls your Server Action with `useActions`, passing the message as an input)
+- Message is appended to the AI State and then passed to the model alongside a number of tools
+- Model can decide to call a tool, which will render the `<SomeTool />` component
+- Within that component, you can add interactivity by using `useActions` to call the model with your Server Action and `useUIState` to append the model's response (`<SomeOtherTool />`) to the UI State
+- And so on...
+
+## Implementation
+
+The turn-by-turn implementation is the simplest form of multistep interfaces. In this implementation, the user and the model take turns during the conversation. For every user input, the model generates a response, and the conversation continues in this turn-by-turn fashion.
+
+In the following example, you specify two tools (`searchFlights` and `lookupFlight`) that the model can use to search for flights and lookup details for a specific flight.
+
+```tsx filename="app/actions.tsx"
+import { streamUI } from '@ai-sdk/rsc';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const searchFlights = async (
+  source: string,
+  destination: string,
+  date: string,
+) => {
+  return [
+    {
+      id: '1',
+      flightNumber: 'AA123',
+    },
+    {
+      id: '2',
+      flightNumber: 'AA456',
+    },
+  ];
+};
+
+const lookupFlight = async (flightNumber: string) => {
+  return {
+    flightNumber: flightNumber,
+    departureTime: '10:00 AM',
+    arrivalTime: '12:00 PM',
+  };
+};
+
+export async function submitUserMessage(input: string) {
+  'use server';
+
+  const ui = await streamUI({
+    model: openai('gpt-4o'),
+    system: 'you are a flight booking assistant',
+    prompt: input,
+    text: async ({ content }) => <div>{content}</div>,
+    tools: {
+      searchFlights: {
+        description: 'search for flights',
+        inputSchema: z.object({
+          source: z.string().describe('The origin of the flight'),
+          destination: z.string().describe('The destination of the flight'),
+          date: z.string().describe('The date of the flight'),
+        }),
+        generate: async function* ({ source, destination, date }) {
+          yield `Searching for flights from ${source} to ${destination} on ${date}...`;
+          const results = await searchFlights(source, destination, date);
+
+          return (
+            <div>
+              {results.map(result => (
+                <div key={result.id}>
+                  <div>{result.flightNumber}</div>
+                </div>
+              ))}
+            </div>
+          );
+        },
+      },
+      lookupFlight: {
+        description: 'lookup details for a flight',
+        parameters: z.object({
+          flightNumber: z.string().describe('The flight number'),
+        }),
+        generate: async function* ({ flightNumber }) {
+          yield `Looking up details for flight ${flightNumber}...`;
+          const details = await lookupFlight(flightNumber);
+
+          return (
+            <div>
+              <div>Flight Number: {details.flightNumber}</div>
+              <div>Departure Time: {details.departureTime}</div>
+              <div>Arrival Time: {details.arrivalTime}</div>
+            </div>
+          );
+        },
+      },
+    },
+  });
+
+  return ui.value;
+}
+```
+
+Next, create an AI context that will hold the UI State and AI State.
+
+```ts filename='app/ai.ts'
+import { createAI } from '@ai-sdk/rsc';
+import { submitUserMessage } from './actions';
+
+export const AI = createAI<any[], React.ReactNode[]>({
+  initialUIState: [],
+  initialAIState: [],
+  actions: {
+    submitUserMessage,
+  },
+});
+```
+
+Next, wrap your application with your newly created context.
+
+```tsx filename='app/layout.tsx'
+import { type ReactNode } from 'react';
+import { AI } from './ai';
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: ReactNode }>) {
+  return (
+    <AI>
+      <html lang="en">
+        <body>{children}</body>
+      </html>
+    </AI>
+  );
+}
+```
+
+To call your Server Action, update your root page with the following:
+
+```tsx filename="app/page.tsx"
+'use client';
+
+import { useState } from 'react';
+import { AI } from './ai';
+import { useActions, useUIState } from '@ai-sdk/rsc';
+
+export default function Page() {
+  const [input, setInput] = useState<string>('');
+  const [conversation, setConversation] = useUIState<typeof AI>();
+  const { submitUserMessage } = useActions();
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setInput('');
+    setConversation(currentConversation => [
+      ...currentConversation,
+      <div>{input}</div>,
+    ]);
+    const message = await submitUserMessage(input);
+    setConversation(currentConversation => [...currentConversation, message]);
+  };
+
+  return (
+    <div>
+      <div>
+        {conversation.map((message, i) => (
+          <div key={i}>{message}</div>
+        ))}
+      </div>
+      <div>
+        <form onSubmit={handleSubmit}>
+          <input
+            type="text"
+            value={input}
+            onChange={e => setInput(e.target.value)}
+          />
+          <button>Send Message</button>
+        </form>
+      </div>
+    </div>
+  );
+}
+```
+
+This page pulls in the current UI State using the `useUIState` hook, which is then mapped over and rendered in the UI. To access the Server Action, you use the `useActions` hook which will return all actions that were passed to the `actions` key of the `createAI` function in your `actions.tsx` file. Finally, you call the `submitUserMessage` function like any other TypeScript function. This function returns a React component (`message`) that is then rendered in the UI by updating the UI State with `setConversation`.
+
+In this example, to call the next tool, the user must respond with plain text. **Given you are streaming a React component, you can add a button to trigger the next step in the conversation**.
+
+To add user interaction, you will have to convert the component into a client component and use the `useAction` hook to trigger the next step in the conversation.
+
+```tsx filename="components/flights.tsx"
+'use client';
+
+import { useActions, useUIState } from '@ai-sdk/rsc';
+import { ReactNode } from 'react';
+
+interface FlightsProps {
+  flights: { id: string; flightNumber: string }[];
+}
+
+export const Flights = ({ flights }: FlightsProps) => {
+  const { submitUserMessage } = useActions();
+  const [_, setMessages] = useUIState();
+
+  return (
+    <div>
+      {flights.map(result => (
+        <div key={result.id}>
+          <div
+            onClick={async () => {
+              const display = await submitUserMessage(
+                `lookupFlight ${result.flightNumber}`,
+              );
+
+              setMessages((messages: ReactNode[]) => [...messages, display]);
+            }}
+          >
+            {result.flightNumber}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+Now, update your `searchFlights` tool to render the new `<Flights />` component.
+
+```tsx filename="actions.tsx"
+...
+searchFlights: {
+  description: 'search for flights',
+  parameters: z.object({
+    source: z.string().describe('The origin of the flight'),
+    destination: z.string().describe('The destination of the flight'),
+    date: z.string().describe('The date of the flight'),
+  }),
+  generate: async function* ({ source, destination, date }) {
+    yield `Searching for flights from ${source} to ${destination} on ${date}...`;
+    const results = await searchFlights(source, destination, date);
+    return (<Flights flights={results} />);
+  },
+}
+...
+```
+
+In the above example, the `Flights` component is used to display the search results. When the user clicks on a flight number, the `lookupFlight` tool is called with the flight number as a parameter. The `submitUserMessage` action is then called to trigger the next step in the conversation.
+
+Learn more about tool calling in Next.js App Router by checking out examples [here](/examples/next-app/tools).

package/docs/05-ai-sdk-rsc/05-streaming-values.mdx

@@ -0,0 +1,158 @@
+---
+title: Streaming Values
+description: Overview of streaming RSCs
+---
+
+import { UIPreviewCard, Card } from '@/components/home/card';
+import { EventPlanning } from '@/components/home/event-planning';
+import { Searching } from '@/components/home/searching';
+import { Weather } from '@/components/home/weather';
+
+# Streaming Values
+
+<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>
+
+The RSC API provides several utility functions to allow you to stream values from the server to the client. This is useful when you need more granular control over what you are streaming and how you are streaming it.
+
+<Note>
+  These utilities can also be paired with [AI SDK Core](/docs/ai-sdk-core)
+  functions like [`streamText`](/docs/reference/ai-sdk-core/stream-text) and
+  [`streamObject`](/docs/reference/ai-sdk-core/stream-object) to easily stream
+  LLM generations from the server to the client.
+</Note>
+
+There are two functions provided by the RSC API that allow you to create streamable values:
+
+- [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value) - creates a streamable (serializable) value, with full control over how you create, update, and close the stream.
+- [`createStreamableUI`](/docs/reference/ai-sdk-rsc/create-streamable-ui) - creates a streamable React component, with full control over how you create, update, and close the stream.
+
+## `createStreamableValue`
+
+The RSC API allows you to stream serializable Javascript values from the server to the client using [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value), such as strings, numbers, objects, and arrays.
+
+This is useful when you want to stream:
+
+- Text generations from the language model in real-time.
+- Buffer values of image and audio generations from multi-modal models.
+- Progress updates from multi-step agent runs.
+
+## Creating a Streamable Value
+
+You can import `createStreamableValue` from `@ai-sdk/rsc` and use it to create a streamable value.
+
+```tsx file='app/actions.ts'
+'use server';
+
+import { createStreamableValue } from '@ai-sdk/rsc';
+
+export const runThread = async () => {
+  const streamableStatus = createStreamableValue('thread.init');
+
+  setTimeout(() => {
+    streamableStatus.update('thread.run.create');
+    streamableStatus.update('thread.run.update');
+    streamableStatus.update('thread.run.end');
+    streamableStatus.done('thread.end');
+  }, 1000);
+
+  return {
+    status: streamableStatus.value,
+  };
+};
+```
+
+## Reading a Streamable Value
+
+You can read streamable values on the client using `readStreamableValue`. It returns an async iterator that yields the value of the streamable as it is updated:
+
+```tsx file='app/page.tsx'
+import { readStreamableValue } from '@ai-sdk/rsc';
+import { runThread } from '@/actions';
+
+export default function Page() {
+  return (
+    <button
+      onClick={async () => {
+        const { status } = await runThread();
+
+        for await (const value of readStreamableValue(status)) {
+          console.log(value);
+        }
+      }}
+    >
+      Ask
+    </button>
+  );
+}
+```
+
+Learn how to stream a text generation (with `streamText`) using the Next.js App Router and `createStreamableValue` in this [example](/examples/next-app/basics/streaming-text-generation).
+
+## `createStreamableUI`
+
+`createStreamableUI` creates a stream that holds a React component. Unlike AI SDK Core APIs, this function does not call a large language model. Instead, it provides a primitive that can be used to have granular control over streaming a React component.
+
+## Using `createStreamableUI`
+
+Let's look at how you can use the `createStreamableUI` function with a Server Action.
+
+```tsx filename='app/actions.tsx'
+'use server';
+
+import { createStreamableUI } from '@ai-sdk/rsc';
+
+export async function getWeather() {
+  const weatherUI = createStreamableUI();
+
+  weatherUI.update(<div style={{ color: 'gray' }}>Loading...</div>);
+
+  setTimeout(() => {
+    weatherUI.done(<div>It&apos;s a sunny day!</div>);
+  }, 1000);
+
+  return weatherUI.value;
+}
+```
+
+First, you create a streamable UI with an empty state and then update it with a loading message. After 1 second, you mark the stream as done passing in the actual weather information as its final value. The `.value` property contains the actual UI that can be sent to the client.
+
+## Reading a Streamable UI
+
+On the client side, you can call the `getWeather` Server Action and render the returned UI like any other React component.
+
+```tsx filename='app/page.tsx'
+'use client';
+
+import { useState } from 'react';
+import { readStreamableValue } from '@ai-sdk/rsc';
+import { getWeather } from '@/actions';
+
+export default function Page() {
+  const [weather, setWeather] = useState<React.ReactNode | null>(null);
+
+  return (
+    <div>
+      <button
+        onClick={async () => {
+          const weatherUI = await getWeather();
+          setWeather(weatherUI);
+        }}
+      >
+        What&apos;s the weather?
+      </button>
+
+      {weather}
+    </div>
+  );
+}
+```
+
+When the button is clicked, the `getWeather` function is called, and the returned UI is set to the `weather` state and rendered on the page. Users will see the loading message first and then the actual weather information after 1 second.
+
+Learn more about handling multiple streams in a single request in the [Multiple Streamables](/docs/advanced/multiple-streamables) guide.
+
+Learn more about handling state for more complex use cases with [ AI/UI State ](/docs/ai-sdk-rsc/generative-ui-state).