@mastra/mcp-docs-server 1.0.0-beta.6 → 1.0.0-beta.8

package/.docs/raw/guides/build-your-ui/ai-sdk-ui.mdx

@@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem";
 
 # Using AI SDK UI
 
-[AI SDK UI](https://sdk.vercel.ai) is a free open-source library that gives you the tools you need to build AI-powered products. Mastra has great integration with AI SDK UI, including model routing, streaming support, custom React hooks, custom tool/UI, and more.
+[AI SDK UI](https://sdk.vercel.ai) is a library of React utilities and components for building AI-powered interfaces. In this guide, you'll learn how to use `@mastra/ai-sdk` to convert Mastra's output to AI SDK-compatible formats, enabling you to use its hooks and components in your frontend.
 
 :::note
 Migrating from AI SDK v4 to v5? See the [migration guide](/guides/v1/migrations/ai-sdk-v4-to-v5).
@@ -16,40 +16,69 @@ Migrating from AI SDK v4 to v5? See the [migration guide](/guides/v1/migrations/
 
 :::tip
 
-Visit Mastra's [**UI Dojo**](https://ui-dojo.mastra.ai/) to see real-world examples of AI SDK integrated with Mastra.
+Want to see more examples? Visit Mastra's [**UI Dojo**](https://ui-dojo.mastra.ai/) or the [Next.js quickstart guide](/guides/v1/getting-started/next-js).
 
 :::
 
-## Streaming
+## Getting Started
 
-The recommended way of using Mastra and AI SDK together is by installing the `@mastra/ai-sdk` package. `@mastra/ai-sdk` provides custom API routes and utilities for streaming Mastra agents in AI SDK-compatible formats. Including chat, workflow, and network route handlers, along with utilities and exported types for UI integrations.
+Use Mastra and AI SDK UI together by installing the `@mastra/ai-sdk` package. `@mastra/ai-sdk` provides custom API routes and utilities for streaming Mastra agents in AI SDK-compatible formats. This includes chat, workflow, and network route handlers, along with utilities and exported types for UI integrations.
+
+`@mastra/ai-sdk` integrates with AI SDK UI's three main hooks: [`useChat()`](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot), [`useCompletion()`](https://ai-sdk.dev/docs/ai-sdk-ui/completion), and [`useObject()`](https://ai-sdk.dev/docs/ai-sdk-ui/object-generation).
+
+Install the required packages to get started:
 
 <Tabs>
   <TabItem value="npm" label="npm">
     ```bash copy
-    npm install @mastra/ai-sdk@beta
+    npm install @mastra/ai-sdk@beta @ai-sdk/react ai
     ```
   </TabItem>
   <TabItem value="pnpm" label="pnpm">
     ```bash copy
-    pnpm add @mastra/ai-sdk@beta
+    pnpm add @mastra/ai-sdk@beta @ai-sdk/react ai
     ```
   </TabItem>
   <TabItem value="yarn" label="yarn">
     ```bash copy
-    yarn add @mastra/ai-sdk@beta
+    yarn add @mastra/ai-sdk@beta @ai-sdk/react ai
     ```
   </TabItem>
   <TabItem value="bun" label="bun">
     ```bash copy
-    bun add @mastra/ai-sdk@beta
+    bun add @mastra/ai-sdk@beta @ai-sdk/react ai
     ```
   </TabItem>
 </Tabs>
 
-### `chatRoute()`
+You're now ready to follow the integration guides and recipes below!
+
+## Integration Guides
+
+Typically, you'll set up API routes that stream Mastra content in AI SDK-compatible format, and then use those routes in AI SDK UI hooks like `useChat()`. Below you'll find two main approaches to achieve this:
+
+- [Mastra's server](#mastras-server)
+- [Framework-agnostic](#framework-agnostic)
+
+Once you have your API routes set up, you can use them in the [`useChat()`](#usechat) hook.
+
+### Mastra's server
+
+Run Mastra as a standalone server and connect your frontend (e.g. using Vite + React) to its API endpoints. You'll be using Mastra's [custom API routes](/docs/v1/server-db/custom-api-routes) feature for this.
+
+:::info
+
+Mastra's [**UI Dojo**](https://ui-dojo.mastra.ai/) is an example of this setup.
+
+:::
 
-When setting up a [custom API route](/docs/v1/server-db/custom-api-routes), use the `chatRoute()` utility to create a route handler that automatically formats the agent stream into an AI SDK-compatible format.
+You can use [`chatRoute()`](/reference/v1/ai-sdk/chat-route), [`workflowRoute()`](/reference/v1/ai-sdk/workflow-route), and [`networkRoute()`](/reference/v1/ai-sdk/network-route) to create API routes that stream Mastra content in AI SDK-compatible format. Once implemented, you can use these API routes in [`useChat()`](#usechat).
+
+<Tabs>
+
+<TabItem value="chatRoute" label="chatRoute()">
+
+This example shows how to set up a chat route at the `/chat` endpoint that uses an agent with the ID `weatherAgent`.
 
 ```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
@@ -67,41 +96,13 @@ export const mastra = new Mastra({
 });
 ```
 
-Once you have your `/chat` API route set up, you can call the `useChat()` hook in your application.
+You can also use dynamic agent routing, see the [`chatRoute()` reference documentation](/reference/v1/ai-sdk/chat-route) for more details.
 
-```typescript
-const { error, status, sendMessage, messages, regenerate, stop } = useChat({
-  transport: new DefaultChatTransport({
-    api: "http://localhost:4111/chat",
-  }),
-});
-```
+</TabItem>
 
-Pass extra agent stream execution options:
-
-```typescript
-const { error, status, sendMessage, messages, regenerate, stop } = useChat({
-  transport: new DefaultChatTransport({
-    api: "http://localhost:4111/chat",
-    prepareSendMessagesRequest({ messages }) {
-      return {
-        body: {
-          messages,
-          // Pass memory config
-          memory: {
-            thread: "user-1",
-            resource: "user-1",
-          },
-        },
-      };
-    },
-  }),
-});
-```
+<TabItem value="workflowRoute" label="workflowRoute()">
 
-### `workflowRoute()`
-
-Use the `workflowRoute()` utility to create a route handler that automatically formats the workflow stream into an AI SDK-compatible format.
+This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
 
 ```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
@@ -112,45 +113,28 @@ export const mastra = new Mastra({
     apiRoutes: [
       workflowRoute({
         path: "/workflow",
-        agent: "weatherAgent",
+        workflow: "weatherWorkflow",
       }),
     ],
   },
 });
 ```
 
-Once you have your `/workflow` API route set up, you can call the `useChat()` hook in your application.
-
-```typescript
-const { error, status, sendMessage, messages, regenerate, stop } = useChat({
-  transport: new DefaultChatTransport({
-    api: "http://localhost:4111/workflow",
-    prepareSendMessagesRequest({ messages }) {
-      return {
-        body: {
-          inputData: {
-            city: messages[messages.length - 1].parts[0].text,
-          },
-          //Or resumeData for resuming a suspended workflow
-          resumeData: {
-            confirmation: messages[messages.length - 1].parts[0].text
-          }
-        },
-      };
-    },
-  }),
-});
-```
+You can also use dynamic workflow routing, see the [`workflowRoute()` reference documentation](/reference/v1/ai-sdk/workflow-route) for more details.
 
 :::tip Agent streaming in workflows
-When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are automatically streamed to the UI in real-time. This provides a seamless streaming experience even when agents are running inside workflow steps.
 
-Learn more in [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui).
+When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
+
+See [Workflow Streaming](/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui) for more details.
+
 :::
 
-### `networkRoute()`
+</TabItem>
 
-Use the `networkRoute()` utility to create a route handler that automatically formats the agent network stream into an AI SDK-compatible format.
+<TabItem value="networkRoute" label="networkRoute()">
+
+This example shows how to set up a network route at the `/network` endpoint that uses an agent with the ID `weatherAgent`.
 
 ```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
@@ -168,333 +152,106 @@ export const mastra = new Mastra({
 });
 ```
 
-Once you have your `/network` API route set up, you can call the `useChat()` hook in your application.
-
-```typescript
-const { error, status, sendMessage, messages, regenerate, stop } = useChat({
-  transport: new DefaultChatTransport({
-    api: "http://localhost:4111/network",
-  }),
-});
-```
-
-### Custom UI
-
-The `@mastra/ai-sdk` package transforms and emits Mastra streams (e.g workflow, network streams) into AI SDK-compatible [uiMessages DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart) format.
-
-- **Top-level parts**: These are streamed via direct workflow and network stream transformations (e.g in `workflowRoute()` and `networkRoute()`)
-  - `data-workflow`: Aggregates a workflow run with step inputs/outputs and final usage.
-  - `data-network`: Aggregates a routing/network run with ordered steps (agent/workflow/tool executions) and outputs.
-
-- **Nested parts**: These are streamed via nested and merged streams from within a tool's `execute()` method.
-  - `data-tool-workflow`: Nested workflow emitted from within a tool stream.
-  - `data-tool-network`: Nested network emitted from within an tool stream.
-  - `data-tool-agent`: Nested agent emitted from within an tool stream.
-
-Here's an example: For a [nested agent stream within a tool](/docs/v1/streaming/tool-streaming#tool-using-an-agent), `data-tool-agent` UI message parts will be emitted and can be leveraged on the client as documented below:
-
-```typescript title="app/page.tsx" copy
-"use client";
-
-import { useChat } from "@ai-sdk/react";
-import { AgentTool } from '../ui/agent-tool';
-import { DefaultChatTransport } from 'ai';
-import type { AgentDataPart } from "@mastra/ai-sdk";
-
-export default function Page() {
-  const { messages } = useChat({
-    transport: new DefaultChatTransport({
-    api: 'http://localhost:4111/chat',
-    }),
-  });
-
-  return (
-    <div>
-      {messages.map((message) => (
-        <div key={message.id}>
-          {message.parts.map((part, i) => {
-            switch (part.type) {
-              case 'data-tool-agent':
-                return (
-                  <AgentTool {...part.data as AgentDataPart} key={`${message.id}-${i}`} />
-                );
-              default:
-                return null;
-            }
-          })}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
+You can also use dynamic network routing, see the [`networkRoute()` reference documentation](/reference/v1/ai-sdk/network-route) for more details.
 
-```typescript title="ui/agent-tool.ts" copy
-import { Tool, ToolContent, ToolHeader, ToolOutput } from "../ai-elements/tool";
-import type { AgentDataPart } from "@mastra/ai-sdk";
+</TabItem>
 
-export const AgentTool = ({ id, text, status }: AgentDataPart) => {
-  return (
-    <Tool>
-      <ToolHeader
-        type={`${id}`}
-        state={status === 'finished' ? 'output-available' : 'input-available'}
-      />
-      <ToolContent>
-        <ToolOutput output={text} />
-      </ToolContent>
-    </Tool>
-  );
-};
-```
-
-### Custom Tool streaming
-
-To stream custom data parts from within your tool execution function, use the
-`writer.custom()` method.
-
-```typescript {5,8,15} showLineNumbers copy
-import { createTool } from "@mastra/core/tools";
+</Tabs>
 
-export const testTool = createTool({
-  // ...
-  execute: async ({ context, writer }) => {
-    const { value } = context;
+### Framework-agnostic
 
-   await writer?.custom({
-      type: "data-tool-progress",
-      status: "pending"
-    });
+If you don't want to run Mastra's server and instead use frameworks like Next.js or Express, you can use the [`handleChatStream()`](/reference/v1/ai-sdk/handle-chat-stream), [`handleWorkflowStream()`](/reference/v1/ai-sdk/handle-workflow-stream), and [`handleNetworkStream()`](/reference/v1/ai-sdk/handle-network-stream) functions in your own API route handlers.
 
-    const response = await fetch(...);
-
-   await writer?.custom({
-      type: "data-tool-progress",
-      status: "success"
-    });
+They return a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
 
-    return {
-      value: ""
-    };
-  }
-});
-```
+The examples below show you how to use them with Next.js App Router.
 
-For more information about tool streaming see [Tool streaming documentation](/docs/v1/streaming/tool-streaming)
+<Tabs>
 
-### Stream Transformations
+<TabItem value="handleChatStream" label="handleChatStream()">
 
-To manually transform Mastra's streams to AI SDK-compatible format, use the `toAISdkStream()` utility.
+This example shows how to set up a chat route at the `/chat` endpoint that uses an agent with the ID `weatherAgent`.
 
-```typescript title="app/api/chat/route.ts" copy {3,13}
-import { mastra } from "../../mastra";
-import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
-import { toAISdkStream } from "@mastra/ai-sdk";
+```typescript title="app/chat/route.ts" copy
+import { handleChatStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
 
 export async function POST(req: Request) {
-  const { messages } = await req.json();
-  const myAgent = mastra.getAgent("weatherAgent");
-  const stream = await myAgent.stream(messages);
-
-  // Transform stream into AI SDK format and create UI messages stream
-  const uiMessageStream = createUIMessageStream({
-    originalMessages: messages,
-    execute: async ({ writer }) => {
-      for await (const part of toAISdkStream(stream, { from: "agent" })!) {
-        writer.write(part);
-      }
-    },
-  });
-
-  // Create a Response that streams the UI message stream to the client
-  return createUIMessageStreamResponse({
-    stream: uiMessageStream,
+  const params = await req.json();
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params,
   });
+  return createUIMessageStreamResponse({ stream });
 }
 ```
 
-#### Stream Transformation Options
+</TabItem>
 
-The `toAISdkStream()` function accepts the following options:
+<TabItem value="handleWorkflowStream" label="handleWorkflowStream()">
 
-<PropertiesTable
-  content={[
-    {
-      name: "from",
-      type: "'agent' | 'network' | 'workflow'",
-      isRequired: true,
-      description: "The type of Mastra stream being converted.",
-    },
-    {
-      name: "lastMessageId",
-      type: "string",
-      isOptional: true,
-      description: "(Agent only) The ID of the last message in the conversation.",
-    },
-    {
-      name: "sendStart",
-      type: "boolean",
-      isOptional: true,
-      defaultValue: "true",
-      description: "(Agent only) Whether to send start events.",
-    },
-    {
-      name: "sendFinish",
-      type: "boolean",
-      isOptional: true,
-      defaultValue: "true",
-      description: "(Agent only) Whether to send finish events.",
-    },
-    {
-      name: "sendReasoning",
-      type: "boolean",
-      isOptional: true,
-      defaultValue: "false",
-      description: "(Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream the actual reasoning content from models that support extended thinking.",
-    },
-    {
-      name: "sendSources",
-      type: "boolean",
-      isOptional: true,
-      defaultValue: "false",
-      description: "(Agent only) Whether to include source citations in the output.",
-    },
-    {
-      name: "messageMetadata",
-      type: "Function",
-      isOptional: true,
-      description: "(Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.",
-    },
-    {
-      name: "onError",
-      type: "Function",
-      isOptional: true,
-      description: "(Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.",
-    },
-  ]}
-/>
+This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
 
-**Example with reasoning enabled:**
-
-```typescript title="app/api/chat/route.ts" copy {11-14}
-import { mastra } from "../../mastra";
-import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
-import { toAISdkStream } from "@mastra/ai-sdk";
+```typescript title="app/workflow/route.ts" copy
+import { handleWorkflowStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
 
 export async function POST(req: Request) {
-  const { messages } = await req.json();
-  const myAgent = mastra.getAgent("reasoningAgent");
-  const stream = await myAgent.stream(messages, {
-    providerOptions: {
-      openai: { reasoningEffort: "high" },
-    },
-  });
-
-  const uiMessageStream = createUIMessageStream({
-    initialMessages: messages,
-    execute: async ({ writer }) => {
-      for await (const part of toAISdkStream(stream, {
-        from: "agent",
-        sendReasoning: true, // Enable reasoning content streaming
-      })!) {
-        writer.write(part);
-      }
-    },
-  });
-
-  return createUIMessageStreamResponse({
-    stream: uiMessageStream,
+  const params = await req.json();
+  const stream = await handleWorkflowStream({
+    mastra,
+    workflowId: 'weatherWorkflow',
+    params,
   });
+  return createUIMessageStreamResponse({ stream });
 }
 ```
 
-### Client Side Stream Transformations
+</TabItem>
 
-If you have a client-side `response` from `agent.stream(...)` and want AI SDK-formatted parts without custom SSE parsing, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and pipe it through `toAISdkStream`:
+<TabItem value="handleNetworkStream" label="handleNetworkStream()">
 
-```typescript title="client-stream-to-ai-sdk.ts" copy
-import { createUIMessageStream } from "ai";
-import { toAISdkStream } from "@mastra/ai-sdk";
-import type { ChunkType, MastraModelOutput } from "@mastra/core/stream";
+This example shows how to set up a network route at the `/network` endpoint that uses an agent with the ID `routingAgent`.
 
-// Client SDK agent stream
-const response = await agent.stream({
-  messages: "What is the weather in Tokyo",
-});
-
-const chunkStream: ReadableStream<ChunkType> = new ReadableStream<ChunkType>({
-  start(controller) {
-    response
-      .processDataStream({
-        onChunk: async (chunk) => {
-          controller.enqueue(chunk as ChunkType);
-        },
-      })
-      .finally(() => controller.close());
-  },
-});
+```typescript title="app/network/route.ts" copy
+import { handleNetworkStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
 
-const uiMessageStream = createUIMessageStream({
-  execute: async ({ writer }) => {
-    for await (const part of toAISdkStream(
-      chunkStream as unknown as MastraModelOutput,
-      { from: "agent" },
-    )) {
-      writer.write(part);
-    }
-  },
-});
-
-for await (const part of uiMessageStream) {
-  console.log(part);
+export async function POST(req: Request) {
+  const params = await req.json();
+  const stream = await handleNetworkStream({
+    mastra,
+    agentId: 'routingAgent',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
 }
 ```
 
-## UI Hooks
-
-Mastra supports AI SDK UI hooks for connecting frontend components directly to agents using HTTP streams.
+</TabItem>
 
-Install the required AI SDK React package:
-
-<Tabs>
-  <TabItem value="npm" label="npm">
-    ```bash copy
-    npm install @ai-sdk/react
-    ```
-  </TabItem>
-  <TabItem value="pnpm" label="pnpm">
-    ```bash copy
-    pnpm add @ai-sdk/react
-    ```
-  </TabItem>
-  <TabItem value="yarn" label="yarn">
-    ```bash copy
-    yarn add @ai-sdk/react
-    ```
-  </TabItem>
-  <TabItem value="bun" label="bun">
-    ```bash copy
-    bun add @ai-sdk/react
-    ```
-  </TabItem>
 </Tabs>
 
-### Using `useChat()`
+### `useChat()`
 
-The `useChat()` hook handles real-time chat interactions between your frontend and a Mastra agent, enabling you to send prompts and receive streaming responses over HTTP.
+Whether you created API routes through [Mastra's server](#mastras-server) or used a [framework of your choice](#framework-agnostic), you can now use the API endpoints in the `useChat()` hook.
 
-```typescript {8-12} title="app/test/chat.tsx" copy
-"use client";
+Assuming you set up a route at `/chat` that uses a weather agent, you can ask it questions as seen below. It's important that you set the correct `api` URL.
 
+```ts {9}
 import { useChat } from "@ai-sdk/react";
 import { useState } from "react";
-import { DefaultChatTransport } from 'ai';
+import { DefaultChatTransport } from "ai";
 
-export function Chat() {
-  const [inputValue, setInputValue] = useState('')
-  const { messages, sendMessage} = useChat({
+export default function Chat() {
+  const [inputValue, setInputValue] = useState("")
+  const { messages, sendMessage } = useChat({
     transport: new DefaultChatTransport({
-      api: 'http://localhost:4111/chat',
+      api: "http://localhost:4111/chat",
     }),
   });
 
@@ -507,86 +264,154 @@ export function Chat() {
     <div>
       <pre>{JSON.stringify(messages, null, 2)}</pre>
       <form onSubmit={handleFormSubmit}>
-        <input value={inputValue} onChange={e=>setInputValue(e.target.value)} placeholder="Name of city" />
+        <input value={inputValue} onChange={e => setInputValue(e.target.value)} placeholder="Name of the city" />
       </form>
     </div>
   );
 }
 ```
 
-Requests sent using the `useChat()` hook are handled by a standard server route. This example shows how to define a POST route using a Next.js Route Handler.
-
-```typescript title="app/api/chat/route.ts" copy
-import { mastra } from "../../mastra";
+Use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the chat route, for example to pass additional configuration to the agent.
 
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-  const myAgent = mastra.getAgent("weatherAgent");
-  const stream = await myAgent.stream(messages, { format: "aisdk" });
-
-  return stream.toUIMessageStreamResponse();
-}
-```
-
-> When using `useChat()` with agent memory, refer to the [Agent Memory section](/docs/v1/agents/agent-memory) for key implementation details.
-
-### Using `useCompletion()`
+### `useCompletion()`
 
 The `useCompletion()` hook handles single-turn completions between your frontend and a Mastra agent, allowing you to send a prompt and receive a streamed response over HTTP.
 
-```typescript {6-8} title="app/test/completion.tsx" copy
-"use client";
+Your frontend could look like this:
 
-import { useCompletion } from "@ai-sdk/react";
+```typescript title="app/page.tsx" copy
+import { useCompletion } from '@ai-sdk/react';
 
-export function Completion() {
+export default function Page() {
   const { completion, input, handleInputChange, handleSubmit } = useCompletion({
-    api: "api/completion"
+    api: '/api/completion',
   });
 
   return (
-    <div>
-      <form onSubmit={handleSubmit}>
-        <input value={input} onChange={handleInputChange} placeholder="Name of city" />
-      </form>
-      <p>Completion result: {completion}</p>
-    </div>
+    <form onSubmit={handleSubmit}>
+      <input
+        name="prompt"
+        value={input}
+        onChange={handleInputChange}
+        id="input"
+      />
+      <button type="submit">Submit</button>
+      <div>{completion}</div>
+    </form>
   );
 }
 ```
 
-Requests sent using the `useCompletion()` hook are handled by a standard server route. This example shows how to define a POST route using a Next.js Route Handler.
+Below are two approaches to implementing the backend:
+
+<Tabs>
+
+<TabItem value="mastra-server" label="Mastra Server">
+
+```ts title="src/mastra/index.ts" copy
+import { Mastra } from '@mastra/core/mastra';
+import { registerApiRoute } from '@mastra/core/server';
+import { handleChatStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      registerApiRoute('/completion', {
+        method: 'POST',
+        handler: async (c) => {
+          const { prompt } = await c.req.json();
+          const mastra = c.get('mastra');
+          const stream = await handleChatStream({
+            mastra,
+            agentId: 'weatherAgent',
+            params: {
+              messages: [
+                {
+                  id: "1",
+                  role: 'user',
+                  parts: [
+                    {
+                      type: 'text',
+                      text: prompt
+                    }
+                  ]
+                }
+              ],
+            }
+          })
+
+          return createUIMessageStreamResponse({ stream });
+        }
+      })
+    ]
+  }
+});
+```
+
+</TabItem>
 
-```typescript title="app/api/completion/route.ts" copy
-import { mastra } from "../../../mastra";
+<TabItem value="nextjs" label="Next.js">
+
+```ts title="app/completion/route.ts" copy
+import { handleChatStream } from '@mastra/ai-sdk';
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
+
+// Allow streaming responses up to 30 seconds
+export const maxDuration = 30;
 
 export async function POST(req: Request) {
-  const { prompt } = await req.json();
-  const myAgent = mastra.getAgent("weatherAgent");
-  const stream = await myAgent.stream([{ role: "user", content: prompt }], {
-    format: "aisdk",
+  const { prompt }: { prompt: string } = await req.json();
+
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params: {
+      messages: [
+        {
+          id: "1",
+          role: 'user',
+          parts: [
+            {
+              type: 'text',
+              text: prompt
+            }
+          ]
+        }
+      ],
+    },
   });
-
-  return stream.toUIMessageStreamResponse();
+  return createUIMessageStreamResponse({ stream });
 }
 ```
 
+</TabItem>
+
+</Tabs>
+
+## Recipes
+
+### Stream transformations
+
+To manually transform Mastra's streams to AI SDK-compatible format, use the [`toAISdkStream()`](/reference/v1/ai-sdk/to-ai-sdk-stream) utility. See the [examples](/reference/v1/ai-sdk/to-ai-sdk-stream#examples) for concrete usage patterns.
+
 ### Passing additional data
 
-`sendMessage()` allows you to pass additional data from the frontend to Mastra. This data can then be used on the server as `RequestContext`.
+[`sendMessage()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#send-message) allows you to pass additional data from the frontend to Mastra. This data can then be used on the server as [`RequestContext`](/docs/v1/server-db/request-context).
 
-```typescript {16-26} title="app/test/chat-extra.tsx" copy
-"use client";
+Here's an example of the frontend code:
 
+```typescript {15-25} copy
 import { useChat } from "@ai-sdk/react";
 import { useState } from "react";
 import { DefaultChatTransport } from 'ai';
 
-export function ChatExtra() {
+export function ChatAdditional() {
   const [inputValue, setInputValue] = useState('')
   const { messages, sendMessage } = useChat({
     transport: new DefaultChatTransport({
-      api: 'http://localhost:4111/chat',
+      api: 'http://localhost:4111/chat-extra',
     }),
   });
 
@@ -609,20 +434,65 @@ export function ChatExtra() {
     <div>
       <pre>{JSON.stringify(messages, null, 2)}</pre>
       <form onSubmit={handleFormSubmit}>
-        <input value={inputValue} onChange={e=>setInputValue(e.target.value)} placeholder="Name of city" />
+        <input value={inputValue} onChange={e => setInputValue(e.target.value)} placeholder="Name of the city" />
       </form>
     </div>
   );
 }
 ```
 
-```typescript {8,12} title="app/api/chat-extra/route.ts" copy
-import { mastra } from "../../../mastra";
+Two examples on how to implement the backend portion of it.
+
+<Tabs>
+
+<TabItem value="mastra-server" label="Mastra Server">
+
+Add a `chatRoute()` to your Mastra configuration like shown above. Then, add a server-level middleware:
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+
+export const mastra = new Mastra({
+  server: {
+    middleware: [
+      async (c, next) => {
+        const requestContext = c.get("requestContext");
+
+        if (c.req.method === "POST") {
+          const clonedReq = c.req.raw.clone();
+          const body = await clonedReq.json();
+
+          if (body?.data) {
+            for (const [key, value] of Object.entries(body.data)) {
+              requestContext.set(key, value);
+            }
+          }
+        }
+        await next();
+      },
+    ],
+  },
+});
+```
+
+:::info
+
+You can access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](/docs/v1/server-db/request-context) for more details.
+
+:::
+
+</TabItem>
+
+<TabItem value="nextjs" label="Next.js">
+
+```typescript title="app/chat-extra/route.ts" copy
+import { handleChatStream } from '@mastra/ai-sdk';
 import { RequestContext } from "@mastra/core/request-context";
+import { createUIMessageStreamResponse } from 'ai';
+import { mastra } from '@/src/mastra';
 
 export async function POST(req: Request) {
   const { messages, data } = await req.json();
-  const myAgent = mastra.getAgent("weatherAgent");
 
   const requestContext = new RequestContext();
 
@@ -632,46 +502,126 @@ export async function POST(req: Request) {
     }
   }
 
-  const stream = await myAgent.stream(messages, {
-    requestContext,
-    format: "aisdk",
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params: {
+      messages,
+      requestContext,
+    },
   });
-  return stream.toUIMessageStreamResponse();
+  return createUIMessageStreamResponse({ stream });
 }
 ```
 
-### Handling `requestContext` with `server.middleware`
+</TabItem>
 
-You can also populate the `RequestContext` by reading custom data in a server middleware:
+</Tabs>
 
-```typescript {8,17} title="mastra/index.ts" copy
-import { Mastra } from "@mastra/core";
+### Custom UI
 
-export const mastra = new Mastra({
-  agents: { weatherAgent },
-  server: {
-    middleware: [
-      async (c, next) => {
-        const requestContext = c.get("requestContext");
+The `@mastra/ai-sdk` package transforms and emits Mastra streams (e.g workflow, network streams) into AI SDK-compatible [uiMessages DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart) format.
 
-        if (c.req.method === "POST") {
-          try {
-            const clonedReq = c.req.raw.clone();
-            const body = await clonedReq.json();
-
-            if (body?.data) {
-              for (const [key, value] of Object.entries(body.data)) {
-                requestContext.set(key, value);
-              }
+- **Top-level parts**: These are streamed via direct workflow and network stream transformations (e.g in `workflowRoute()` and `networkRoute()`)
+  - `data-workflow`: Aggregates a workflow run with step inputs/outputs and final usage.
+  - `data-network`: Aggregates a routing/network run with ordered steps (agent/workflow/tool executions) and outputs.
+
+- **Nested parts**: These are streamed via nested and merged streams from within a tool's `execute()` method.
+  - `data-tool-workflow`: Nested workflow emitted from within a tool stream.
+  - `data-tool-network`: Nested network emitted from within an tool stream.
+  - `data-tool-agent`: Nested agent emitted from within an tool stream.
+
+Here's an example: For a [nested agent stream within a tool](/docs/v1/streaming/tool-streaming#tool-using-an-agent), `data-tool-agent` UI message parts will be emitted and can be leveraged on the client as documented below:
+
+```typescript title="app/page.tsx" copy
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { AgentTool } from '../ui/agent-tool';
+import { DefaultChatTransport } from 'ai';
+import type { AgentDataPart } from "@mastra/ai-sdk";
+
+export default function Page() {
+  const { messages } = useChat({
+    transport: new DefaultChatTransport({
+      api: 'http://localhost:4111/chat',
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, i) => {
+            switch (part.type) {
+              case 'data-tool-agent':
+                return (
+                  <AgentTool {...part.data as AgentDataPart} key={`${message.id}-${i}`} />
+                );
+              default:
+                return null;
             }
-          } catch {}
-        }
-        await next();
-      },
-    ],
-  },
-});
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
 ```
 
-> You can then access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](/docs/v1/server-db/request-context) for more details.
+```typescript title="ui/agent-tool.ts" copy
+import { Tool, ToolContent, ToolHeader, ToolOutput } from "../ai-elements/tool";
+import type { AgentDataPart } from "@mastra/ai-sdk";
+
+export const AgentTool = ({ id, text, status }: AgentDataPart) => {
+  return (
+    <Tool>
+      <ToolHeader
+        type={`${id}`}
+        state={status === 'finished' ? 'output-available' : 'input-available'}
+      />
+      <ToolContent>
+        <ToolOutput output={text} />
+      </ToolContent>
+    </Tool>
+  );
+};
+```
+
+### Custom Tool streaming
+
+To stream custom data parts from within your tool execution function, use the `writer.custom()` method.
+
+:::tip
+
+It is important that you `await` the `writer.custom()` call.
+
+:::
+
+```typescript {4,7-10,14-17} copy
+import { createTool } from "@mastra/core/tools";
+
+export const testTool = createTool({
+  execute: async ({ context, writer }) => {
+    const { value } = context;
+
+    await writer?.custom({
+      type: "data-tool-progress",
+      status: "pending"
+    });
+
+    const response = await fetch(...);
+
+    await writer?.custom({
+      type: "data-tool-progress",
+      status: "success"
+    });
+
+    return {
+      value: ""
+    };
+  }
+});
+```
 
+For more information about tool streaming see [Tool streaming documentation](/docs/v1/streaming/tool-streaming).