@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.13

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

@@ -64,7 +64,7 @@ Once you have your API routes set up, you can use them in the [`useChat()`](#use
 
 ### 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.
+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/custom-api-routes) feature for this.
 
 :::info
 
@@ -390,15 +390,582 @@ export async function POST(req: Request) {
 
 </Tabs>
 
+## Custom UI
+
+Custom UI (also known as Generative UI) allows you to render custom React components based on data streamed from Mastra. Instead of displaying raw text or JSON, you can create visual components for tool outputs, workflow progress, agent network execution, and custom events.
+
+Use Custom UI when you want to:
+
+- Render tool outputs as visual components (e.g., a weather card instead of JSON)
+- Display workflow step progress with status indicators
+- Visualize agent network execution with step-by-step updates
+- Show progress indicators or status updates during long-running operations
+
+### Data part types
+
+Mastra streams data to the frontend as "parts" within messages. Each part has a `type` that determines how to render it. The `@mastra/ai-sdk` package transforms Mastra streams into AI SDK-compatible [UI Message DataParts](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#datauipart).
+
+| Data Part Type | Source | Description |
+|----------------|--------|-------------|
+| `tool-{toolKey}` | AI SDK built-in | Tool invocation with states: `input-available`, `output-available`, `output-error` |
+| `data-workflow` | `workflowRoute()` | Workflow execution with step inputs, outputs, and status |
+| `data-network` | `networkRoute()` | Agent network execution with ordered steps and outputs |
+| `data-tool-agent` | Nested agent in tool | Agent output streamed from within a tool's `execute()` |
+| `data-tool-workflow` | Nested workflow in tool | Workflow output streamed from within a tool's `execute()` |
+| `data-tool-network` | Nested network in tool | Network output streamed from within a tool's `execute()` |
+| `data-{custom}` | `writer.custom()` | Custom events for progress indicators, status updates, etc. |
+
+### Rendering tool outputs
+
+AI SDK automatically creates `tool-{toolKey}` parts when an agent calls a tool. These parts include the tool's state and output, which you can use to render custom components.
+
+The tool part cycles through states:
+- `input-streaming`: Tool input is being streamed (when tool call streaming is enabled)
+- `input-available`: Tool has been called with complete input, waiting for execution
+- `output-available`: Tool execution completed with output
+- `output-error`: Tool execution failed
+
+Here's an example of rendering a weather tool's output as a custom `WeatherCard` component.
+
+<Tabs>
+
+<TabItem value="backend" label="Backend">
+
+Define a tool with an `outputSchema` so the frontend knows the shape of the data to render.
+
+```typescript title="src/mastra/tools/weather-tool.ts" {10-17} copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "get-weather",
+  description: "Get current weather for a location",
+  inputSchema: z.object({
+    location: z.string().describe("The location to get the weather for"),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    feelsLike: z.number(),
+    humidity: z.number(),
+    windSpeed: z.number(),
+    conditions: z.string(),
+    location: z.string(),
+  }),
+  execute: async ({ location }) => {
+    const response = await fetch(
+      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${location}`
+    );
+    const data = await response.json();
+    return {
+      temperature: data.current.temp_c,
+      feelsLike: data.current.feelslike_c,
+      humidity: data.current.humidity,
+      windSpeed: data.current.wind_kph,
+      conditions: data.current.condition.text,
+      location: data.location.name,
+    };
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Check for `tool-{toolKey}` parts in the message and render a custom component based on the tool's state and output.
+
+```typescript title="src/components/chat.tsx" {24-35} copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { WeatherCard } from "./weather-card";
+import { Loader } from "./loader";
+
+export function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/chat/weatherAgent",
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            // Handle user text messages
+            if (part.type === "text" && message.role === "user") {
+              return <p key={index}>{part.text}</p>;
+            }
+
+            // Handle weather tool output
+            if (part.type === "tool-weatherTool") {
+              switch (part.state) {
+                case "input-available":
+                  return <Loader key={index} />;
+                case "output-available":
+                  return <WeatherCard key={index} {...part.output} />;
+                case "output-error":
+                  return <div key={index}>Error: {part.errorText}</div>;
+                default:
+                  return null;
+              }
+            }
+
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+:::tip
+
+The tool part type follows the pattern `tool-{toolKey}`, where `toolKey` is the key used when registering the tool with the agent. For example, if you register tools as `tools: { weatherTool }`, the part type will be `tool-weatherTool`.
+
+:::
+
+### Rendering workflow data
+
+When using `workflowRoute()` or `handleWorkflowStream()`, Mastra emits `data-workflow` parts that contain the workflow's execution state, including step statuses and outputs.
+
+<Tabs>
+
+<TabItem value="backend" label="Backend">
+
+Define a workflow with multiple steps that will emit `data-workflow` parts as it executes.
+
+```typescript title="src/mastra/workflows/activities-workflow.ts" copy
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const fetchWeather = createStep({
+  id: "fetch-weather",
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    // Fetch weather data...
+    return { temperature: 22, conditions: "Sunny" };
+  },
+});
+
+const planActivities = createStep({
+  id: "plan-activities",
+  inputSchema: z.object({
+    temperature: z.number(),
+    conditions: z.string(),
+  }),
+  outputSchema: z.object({
+    activities: z.string(),
+  }),
+  execute: async ({ inputData, mastra }) => {
+    const agent = mastra?.getAgent("activityAgent");
+    const response = await agent?.generate(
+      `Suggest activities for ${inputData.conditions} weather at ${inputData.temperature}°C`
+    );
+    return { activities: response?.text || "" };
+  },
+});
+
+export const activitiesWorkflow = createWorkflow({
+  id: "activities-workflow",
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    activities: z.string(),
+  }),
+})
+  .then(fetchWeather)
+  .then(planActivities);
+
+activitiesWorkflow.commit();
+```
+
+Register the workflow with Mastra and expose it via `workflowRoute()` to stream workflow events to the frontend.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  workflows: { activitiesWorkflow },
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow/activitiesWorkflow",
+        workflow: "activitiesWorkflow",
+      }),
+    ],
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Check for `data-workflow` parts and render each step's status and output using the `WorkflowDataPart` type for type safety.
+
+```typescript title="src/components/workflow-chat.tsx" {3,5,45-47} copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import type { WorkflowDataPart } from "@mastra/ai-sdk";
+
+type WorkflowData = WorkflowDataPart["data"];
+type StepStatus = "running" | "success" | "failed" | "suspended" | "waiting";
+
+function StepIndicator({ name, status, output }: { 
+  name: string; 
+  status: StepStatus; 
+  output: unknown;
+}) {
+  return (
+    <div className="step">
+      <div className="step-header">
+        <span>{name}</span>
+        <span className={`status status-${status}`}>{status}</span>
+      </div>
+      {status === "success" && output && (
+        <pre>{JSON.stringify(output, null, 2)}</pre>
+      )}
+    </div>
+  );
+}
+
+export function WorkflowChat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/workflow/activitiesWorkflow",
+      prepareSendMessagesRequest: ({ messages }) => ({
+        body: {
+          inputData: {
+            location: messages[messages.length - 1]?.parts[0]?.text,
+          },
+        },
+      }),
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            if (part.type === "data-workflow") {
+              const workflowData = part.data as WorkflowData;
+              const steps = Object.values(workflowData.steps);
+              
+              return (
+                <div key={index} className="workflow-progress">
+                  <h3>Workflow: {workflowData.name}</h3>
+                  <p>Status: {workflowData.status}</p>
+                  {steps.map((step) => (
+                    <StepIndicator
+                      key={step.name}
+                      name={step.name}
+                      status={step.status}
+                      output={step.output}
+                    />
+                  ))}
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+For more details on workflow streaming, see [Workflow Streaming](/docs/v1/streaming/workflow-streaming).
+
+### Rendering network data
+
+When using `networkRoute()` or `handleNetworkStream()`, Mastra emits `data-network` parts that contain the agent network's execution state, including which agents were called and their outputs.
+
+<Tabs>
+
+<TabItem value="backend" label="Backend">
+
+Register agents with Mastra and expose the routing agent via `networkRoute()` to stream network execution events to the frontend.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { networkRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  agents: { routingAgent, researchAgent, weatherAgent },
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: "/network",
+        agent: "routingAgent",
+      }),
+    ],
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Check for `data-network` parts and render each agent's execution step using the `NetworkDataPart` type for type safety.
+
+```typescript title="src/components/network-chat.tsx" {3,5,42-44} copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import type { NetworkDataPart } from "@mastra/ai-sdk";
+
+type NetworkData = NetworkDataPart["data"];
+
+function AgentStep({ step }: { step: NetworkData["steps"][number] }) {
+  return (
+    <div className="agent-step">
+      <div className="step-header">
+        <span className="agent-name">{step.name}</span>
+        <span className={`status status-${step.status}`}>{step.status}</span>
+      </div>
+      {step.input && (
+        <div className="step-input">
+          <strong>Input:</strong>
+          <pre>{JSON.stringify(step.input, null, 2)}</pre>
+        </div>
+      )}
+      {step.output && (
+        <div className="step-output">
+          <strong>Output:</strong>
+          <pre>{typeof step.output === "string" ? step.output : JSON.stringify(step.output, null, 2)}</pre>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function NetworkChat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/network",
+    }),
+  });
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            if (part.type === "data-network") {
+              const networkData = part.data as NetworkData;
+              
+              return (
+                <div key={index} className="network-execution">
+                  <div className="network-header">
+                    <h3>Agent Network: {networkData.name}</h3>
+                    <span className={`status status-${networkData.status}`}>
+                      {networkData.status}
+                    </span>
+                  </div>
+                  <div className="network-steps">
+                    {networkData.steps.map((step, stepIndex) => (
+                      <AgentStep key={stepIndex} step={step} />
+                    ))}
+                  </div>
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+For more details on agent networks, see [Agent Networks](/docs/v1/agents/networks).
+
+### Custom events
+
+Use `writer.custom()` within a tool's `execute()` function to emit custom data parts. This is useful for progress indicators, status updates, or any custom UI updates during tool execution.
+
+Custom event types must start with `data-` to be recognized as data parts.
+
+:::warning
+
+You must `await` the `writer.custom()` call, otherwise you may encounter a `WritableStream is locked` error.
+
+:::
+
+<Tabs>
+
+<TabItem value="backend" label="Backend">
+
+Use `writer.custom()` inside the tool's `execute()` function to emit custom `data-` prefixed events at different stages of execution.
+
+```typescript title="src/mastra/tools/task-tool.ts" {18-24,30-36} copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const taskTool = createTool({
+  id: "process-task",
+  description: "Process a task with progress updates",
+  inputSchema: z.object({
+    task: z.string().describe("The task to process"),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+    status: z.string(),
+  }),
+  execute: async (inputData, context) => {
+    const { task } = inputData;
+
+    // Emit "in progress" custom event
+    await context?.writer?.custom({
+      type: "data-tool-progress",
+      data: {
+        status: "in-progress",
+        message: "Gathering information...",
+      },
+    });
+
+    // Simulate work
+    await new Promise((resolve) => setTimeout(resolve, 3000));
+
+    // Emit "done" custom event
+    await context?.writer?.custom({
+      type: "data-tool-progress",
+      data: {
+        status: "done",
+        message: `Successfully processed "${task}"`,
+      },
+    });
+
+    return {
+      result: `Task "${task}" has been completed successfully!`,
+      status: "completed",
+    };
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Filter message parts for your custom event type and render a progress indicator that updates as new events arrive.
+
+```typescript title="src/components/task-chat.tsx" {31-41,45} copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useMemo } from "react";
+
+type ProgressData = {
+  status: "in-progress" | "done";
+  message: string;
+};
+
+function ProgressIndicator({ progress }: { progress: ProgressData }) {
+  return (
+    <div className="progress-indicator">
+      {progress.status === "in-progress" ? (
+        <span className="spinner" />
+      ) : (
+        <span className="check-icon" />
+      )}
+      <span className={`status-${progress.status}`}>{progress.message}</span>
+    </div>
+  );
+}
+
+export function TaskChat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/chat/taskAgent",
+    }),
+  });
+
+  // Extract the latest progress event from messages
+  const latestProgress = useMemo(() => {
+    const allProgressParts: ProgressData[] = [];
+    messages.forEach((message) => {
+      message.parts.forEach((part) => {
+        if (part.type === "data-tool-progress") {
+          allProgressParts.push(part.data as ProgressData);
+        }
+      });
+    });
+    return allProgressParts[allProgressParts.length - 1];
+  }, [messages]);
+
+  return (
+    <div>
+      {latestProgress && <ProgressIndicator progress={latestProgress} />}
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            if (part.type === "text") {
+              return <p key={index}>{part.text}</p>;
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+### Tool streaming
+
+Tools can also stream data using `context.writer.write()` for lower-level control, or pipe an agent's stream directly to the tool's writer. For more details, see [Tool Streaming](/docs/v1/streaming/tool-streaming).
+
+### Examples
+
+For live examples of Custom UI patterns, visit [Mastra's UI Dojo](https://ui-dojo.mastra.ai/). The repository includes implementations for:
+
+- [Generative UIs](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/generative-user-interfaces.tsx) - Custom components for tool outputs
+- [Workflows](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/workflow.tsx) - Workflow step visualization
+- [Agent Networks](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/network.tsx) - Network execution display
+- [Custom Events](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/generative-user-interfaces-with-custom-events.tsx) - Progress indicators with custom events
+
 ## 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.
 
+### Loading historical messages
+
+When loading messages from Mastra's memory to display in a chat UI, use [`toAISdkV5Messages()`](/reference/v1/ai-sdk/to-ai-sdk-v5-messages) or [`toAISdkV4Messages()`](/reference/v1/ai-sdk/to-ai-sdk-v4-messages) to convert them to the appropriate AI SDK format for `useChat()`'s `initialMessages`.
+
 ### Passing additional data
 
-[`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).
+[`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/request-context).
 
 Here's an example of the frontend code:
 
@@ -477,7 +1044,7 @@ export const mastra = new Mastra({
 
 :::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.
+You can access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](/docs/v1/server/request-context) for more details.
 
 :::
 
@@ -518,49 +1085,305 @@ export async function POST(req: Request) {
 
 </Tabs>
 
-### Custom UI
+### Workflow suspend/resume with user approval
 
-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.
+Workflows can suspend execution and wait for user input before continuing. This is useful for approval flows, confirmations, or any human-in-the-loop scenario.
 
-- **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.
+The workflow uses:
+- `suspendSchema` / `resumeSchema` - Define the data structure for suspend payload and resume input
+- `suspend()` - Pauses the workflow and sends the suspend payload to the UI
+- `resumeData` - Contains the user's response when the workflow resumes
+- `bail()` - Exits the workflow early (e.g., when user rejects)
 
-- **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.
+<Tabs>
 
-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:
+<TabItem value="backend" label="Backend">
+
+Create a workflow step that suspends for approval. The step checks `resumeData` to determine if it's resuming, and calls `suspend()` on first execution.
+
+```typescript title="src/mastra/workflows/approval-workflow.ts" copy
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+
+const requestApproval = createStep({
+  id: "request-approval",
+  inputSchema: z.object({ requestId: z.string(), summary: z.string() }),
+  outputSchema: z.object({
+    approved: z.boolean(),
+    requestId: z.string(),
+    approvedBy: z.string().optional(),
+  }),
+  resumeSchema: z.object({
+    approved: z.boolean(),
+    approverName: z.string().optional(),
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    requestId: z.string(),
+  }),
+  execute: async ({ inputData, resumeData, suspend, bail }) => {
+    // User rejected - bail out
+    if (resumeData?.approved === false) {
+      return bail({ message: "Request rejected" });
+    }
+    // User approved - continue
+    if (resumeData?.approved) {
+      return {
+        approved: true,
+        requestId: inputData.requestId,
+        approvedBy: resumeData.approverName || "User",
+      };
+    }
+    // First execution - suspend and wait
+    return await suspend({
+      message: `Please approve: ${inputData.summary}`,
+      requestId: inputData.requestId,
+    });
+  },
+});
 
-```typescript title="app/page.tsx" copy
-"use client";
+export const approvalWorkflow = createWorkflow({
+  id: "approval-workflow",
+  inputSchema: z.object({ requestId: z.string(), summary: z.string() }),
+  outputSchema: z.object({
+    approved: z.boolean(),
+    requestId: z.string(),
+    approvedBy: z.string().optional(),
+  }),
+})
+  .then(requestApproval);
+
+approvalWorkflow.commit();
+```
+
+Register the workflow. Storage is required for suspend/resume to persist state.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+import { LibSQLStore } from "@mastra/libsql";
 
+export const mastra = new Mastra({
+  workflows: { approvalWorkflow },
+  storage: new LibSQLStore({
+    url: "file:../mastra.db",
+  }),
+  server: {
+    apiRoutes: [
+      workflowRoute({ path: "/workflow/approvalWorkflow", workflow: "approvalWorkflow" }),
+    ],
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Detect when the workflow is suspended and send resume data with `runId`, `step`, and `resumeData`.
+
+```typescript title="src/components/approval-workflow.tsx" copy
 import { useChat } from "@ai-sdk/react";
-import { AgentTool } from '../ui/agent-tool';
-import { DefaultChatTransport } from 'ai';
+import { DefaultChatTransport } from "ai";
+import { useMemo, useState } from "react";
+import type { WorkflowDataPart } from "@mastra/ai-sdk";
+
+type WorkflowData = WorkflowDataPart["data"];
+
+export function ApprovalWorkflow() {
+  const [requestId, setRequestId] = useState("");
+  const [summary, setSummary] = useState("");
+
+  const { messages, sendMessage, setMessages, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/workflow/approvalWorkflow",
+      prepareSendMessagesRequest: ({ messages }) => {
+        const lastMessage = messages[messages.length - 1];
+        const text = lastMessage.parts.find((p) => p.type === "text")?.text;
+        const metadata = lastMessage.metadata as Record<string, string>;
+
+        // Resuming: send runId, step, and resumeData
+        if (text === "Approve" || text === "Reject") {
+          return {
+            body: {
+              runId: metadata.runId,
+              step: "request-approval",
+              resumeData: { approved: text === "Approve" },
+            },
+          };
+        }
+        // Starting: send inputData
+        return {
+          body: { inputData: { requestId: metadata.requestId, summary: metadata.summary } },
+        };
+      },
+    }),
+  });
+
+  // Find suspended workflow
+  const suspended = useMemo(() => {
+    for (const m of messages) {
+      for (const p of m.parts) {
+        if (p.type === "data-workflow" && (p.data as WorkflowData).status === "suspended") {
+          return { data: p.data as WorkflowData, runId: p.id };
+        }
+      }
+    }
+    return null;
+  }, [messages]);
+
+  const handleApprove = () => {
+    setMessages([]);
+    sendMessage({ text: "Approve", metadata: { runId: suspended?.runId } });
+  };
+
+  const handleReject = () => {
+    setMessages([]);
+    sendMessage({ text: "Reject", metadata: { runId: suspended?.runId } });
+  };
+
+  return (
+    <div>
+      {!suspended ? (
+        <form onSubmit={(e) => {
+          e.preventDefault();
+          setMessages([]);
+          sendMessage({ text: "Start", metadata: { requestId, summary } });
+        }}>
+          <input value={requestId} onChange={(e) => setRequestId(e.target.value)} placeholder="Request ID" />
+          <input value={summary} onChange={(e) => setSummary(e.target.value)} placeholder="Summary" />
+          <button type="submit" disabled={status !== "ready"}>Submit</button>
+        </form>
+      ) : (
+        <div>
+          <p>{(suspended.data.steps["request-approval"]?.suspendPayload as { message: string })?.message}</p>
+          <button onClick={handleApprove}>Approve</button>
+          <button onClick={handleReject}>Reject</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+Key points:
+- The suspend payload is accessible via `step.suspendPayload`
+- To resume, send `runId`, `step` (the step ID), and `resumeData` in the request body
+- Storage must be configured for suspend/resume to persist workflow state
+
+For a complete implementation, see the [workflow-suspend-resume example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/workflow-suspend-resume.tsx) in UI Dojo.
+
+### Nested agent streams in tools
+
+Tools can call agents internally and stream the agent's output back to the UI. This creates `data-tool-agent` parts that can be rendered alongside the tool's final output.
+
+The pattern uses:
+- `context.mastra.getAgent()` - Get an agent instance from within a tool
+- `agent.stream()` - Stream the agent's response
+- `stream.fullStream.pipeTo(context.writer)` - Pipe the agent's stream to the tool's writer
+
+<Tabs>
+
+<TabItem value="backend" label="Backend">
+
+Create a tool that calls an agent and pipes its stream to the tool's writer.
+
+```typescript title="src/mastra/tools/nested-agent-tool.ts" copy
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const nestedAgentTool = createTool({
+  id: "nested-agent-stream",
+  description: "Analyze weather using a nested agent",
+  inputSchema: z.object({
+    city: z.string().describe("The city to analyze"),
+  }),
+  outputSchema: z.object({
+    summary: z.string(),
+  }),
+  execute: async (inputData, context) => {
+    const agent = context?.mastra?.getAgent("weatherAgent");
+    if (!agent) {
+      return { summary: "Weather agent not available" };
+    }
+
+    const stream = await agent.stream(
+      `Analyze the weather in ${inputData.city} and provide a summary.`
+    );
+
+    // Pipe the agent's stream to emit data-tool-agent parts
+    await stream.fullStream.pipeTo(context!.writer!);
+
+    return { summary: (await stream.text) ?? "No summary available" };
+  },
+});
+```
+
+Create an agent that uses this tool.
+
+```typescript title="src/mastra/agents/forecast-agent.ts" copy
+import { Agent } from "@mastra/core/agent";
+import { nestedAgentTool } from "../tools/nested-agent-tool";
+
+export const forecastAgent = new Agent({
+  id: "forecast-agent",
+  instructions: "Use the nested-agent-stream tool when asked about weather.",
+  model: "openai/gpt-4o-mini",
+  tools: { nestedAgentTool },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Handle `data-tool-agent` parts to display the nested agent's streamed output.
+
+```typescript title="src/components/nested-agent-chat.tsx" copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useState } from "react";
 import type { AgentDataPart } from "@mastra/ai-sdk";
 
-export default function Page() {
-  const { messages } = useChat({
+export function NestedAgentChat() {
+  const [input, setInput] = useState("");
+  const { messages, sendMessage, status } = useChat({
     transport: new DefaultChatTransport({
-      api: 'http://localhost:4111/chat',
+      api: "http://localhost:4111/chat/forecastAgent",
     }),
   });
 
   return (
     <div>
+      <form onSubmit={(e) => {
+        e.preventDefault();
+        sendMessage({ text: input });
+        setInput("");
+      }}>
+        <input value={input} onChange={(e) => setInput(e.target.value)} placeholder="Enter a city" />
+        <button type="submit" disabled={status !== "ready"}>Get Forecast</button>
+      </form>
+
       {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;
+          {message.parts.map((part, index) => {
+            if (part.type === "text") {
+              return <p key={index}>{part.text}</p>;
+            }
+            if (part.type === "data-tool-agent") {
+              const { id, data } = part as AgentDataPart;
+              return (
+                <div key={index} className="nested-agent">
+                  <strong>Nested Agent: {id}</strong>
+                  {data.text && <p>{data.text}</p>}
+                </div>
+              );
             }
+            return null;
           })}
         </div>
       ))}
@@ -569,59 +1392,190 @@ export default function Page() {
 }
 ```
 
-```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>
-  );
-};
-```
+</Tabs>
 
-### Custom Tool streaming
+Key points:
+- Piping `fullStream` to `context.writer` creates `data-tool-agent` parts
+- The `AgentDataPart` has `id` (on the part) and `data.text` (the agent's streamed text)
+- The tool still returns its own output after the stream completes
 
-To stream custom data parts from within your tool execution function, use the `writer.custom()` method.
+For a complete implementation, see the [tool-nested-streams example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/tool-nested-streams.tsx) in UI Dojo.
 
-:::tip
+### Streaming agent text from workflow steps
 
-It is important that you `await` the `writer.custom()` call.
+Workflow steps can stream an agent's text output in real-time by piping the agent's stream to the step's `writer`. This lets users see the agent "thinking" while the workflow executes, rather than waiting for the step to complete.
 
-:::
+The pattern uses:
+- `writer` in workflow step - Pipe the agent's `fullStream` to the step's writer
+- `text` and `data-workflow` parts - The frontend receives streaming text alongside step progress
 
-```typescript {4,7-10,14-17} copy
-import { createTool } from "@mastra/core/tools";
+<Tabs>
 
-export const testTool = createTool({
-  execute: async (inputData, context) => {
-    const { value } = inputData;
+<TabItem value="backend" label="Backend">
 
-    await context?.writer?.custom({
-      type: "data-tool-progress",
-      status: "pending"
-    });
+Create a workflow step that streams an agent's response by piping to the step's `writer`.
 
-    const response = await fetch(...);
+```typescript title="src/mastra/workflows/weather-workflow.ts" copy
+import { createStep, createWorkflow } from "@mastra/core/workflows";
+import { z } from "zod";
+import { weatherAgent } from "../agents/weather-agent";
 
-    await context?.writer?.custom({
-      type: "data-tool-progress",
-      status: "success"
-    });
+const analyzeWeather = createStep({
+  id: "analyze-weather",
+  inputSchema: z.object({ location: z.string() }),
+  outputSchema: z.object({ analysis: z.string(), location: z.string() }),
+  execute: async ({ inputData, writer }) => {
+    const response = await weatherAgent.stream(
+      `Analyze the weather in ${inputData.location} and provide insights.`
+    );
+
+    // Pipe agent stream to step writer for real-time text streaming
+    await response.fullStream.pipeTo(writer);
 
     return {
-      value: ""
+      analysis: await response.text,
+      location: inputData.location,
     };
-  }
+  },
 });
+
+const calculateScore = createStep({
+  id: "calculate-score",
+  inputSchema: z.object({ analysis: z.string(), location: z.string() }),
+  outputSchema: z.object({ score: z.number(), summary: z.string() }),
+  execute: async ({ inputData }) => {
+    const score = inputData.analysis.includes("sunny") ? 85 : 50;
+    return { score, summary: `Comfort score for ${inputData.location}: ${score}/100` };
+  },
+});
+
+export const weatherWorkflow = createWorkflow({
+  id: "weather-workflow",
+  inputSchema: z.object({ location: z.string() }),
+  outputSchema: z.object({ score: z.number(), summary: z.string() }),
+})
+  .then(analyzeWeather)
+  .then(calculateScore);
+
+weatherWorkflow.commit();
 ```
 
-For more information about tool streaming see [Tool streaming documentation](/docs/v1/streaming/tool-streaming).
+Register the workflow with a `workflowRoute()`. Text streaming is enabled by default.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+  workflows: { weatherWorkflow },
+  server: {
+    apiRoutes: [
+      workflowRoute({ path: "/workflow/weather", workflow: "weatherWorkflow" }),
+    ],
+  },
+});
+```
+
+</TabItem>
+
+<TabItem value="frontend" label="Frontend">
+
+Render both `text` parts (streaming agent output) and `data-workflow` parts (step progress).
+
+```typescript title="src/components/weather-workflow.tsx" copy
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useState } from "react";
+import type { WorkflowDataPart } from "@mastra/ai-sdk";
+
+type WorkflowData = WorkflowDataPart["data"];
+
+export function WeatherWorkflow() {
+  const [location, setLocation] = useState("");
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({
+      api: "http://localhost:4111/workflow/weather",
+      prepareSendMessagesRequest: ({ messages }) => ({
+        body: {
+          inputData: {
+            location: messages[messages.length - 1].parts.find((p) => p.type === "text")?.text,
+          },
+        },
+      }),
+    }),
+  });
+
+  return (
+    <div>
+      <form onSubmit={(e) => {
+        e.preventDefault();
+        sendMessage({ text: location });
+        setLocation("");
+      }}>
+        <input value={location} onChange={(e) => setLocation(e.target.value)} placeholder="Enter city" />
+        <button type="submit" disabled={status !== "ready"}>Analyze</button>
+      </form>
+
+      {messages.map((message) => (
+        <div key={message.id}>
+          {message.parts.map((part, index) => {
+            // Streaming agent text
+            if (part.type === "text" && message.role === "assistant") {
+              return (
+                <div key={index}>
+                  {status === "streaming" && <p><em>Agent analyzing...</em></p>}
+                  <p>{part.text}</p>
+                </div>
+              );
+            }
+            // Workflow step progress
+            if (part.type === "data-workflow") {
+              const workflow = part.data as WorkflowData;
+              return (
+                <div key={index}>
+                  {Object.entries(workflow.steps).map(([stepId, step]) => (
+                    <div key={stepId}>
+                      <strong>{stepId}</strong>: {step.status}
+                    </div>
+                  ))}
+                </div>
+              );
+            }
+            return null;
+          })}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+Key points:
+- The step's `writer` is available in the `execute` function (not via `context`)
+- `includeTextStreamParts` defaults to `true` on `workflowRoute()`, so text streams by default
+- Text parts stream in real-time while `data-workflow` parts update with step status
+
+For a complete implementation, see the [workflow-agent-text-stream example](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/workflow-agent-text-stream.tsx) in UI Dojo.
+
+### Multi-stage progress with branching workflows
+
+For workflows with conditional branching (e.g., express vs standard shipping), you can track progress across different branches by including a identifier in your custom events.
+
+The UI Dojo example uses a `stage` field in the event data to identify which branch is executing (e.g., `"validation"`, `"standard-processing"`, `"express-processing"`). The frontend groups events by this field to show a pipeline-style progress UI.
+
+See the [branching-workflow.ts](https://github.com/mastra-ai/ui-dojo/blob/main/src/mastra/workflows/branching-workflow.ts) (backend) and [workflow-custom-events.tsx](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/workflow-custom-events.tsx) (frontend) in UI Dojo.
+
+### Progress indicators in agent networks
+
+When using agent networks, you can emit custom progress events from tools used by sub-agents to show which agent is currently active.
+
+The UI Dojo example includes a `stage` field in the event data to identify which sub-agent is running (e.g., `"report-generation"`, `"report-review"`). The frontend groups events by this field and displays the latest status for each.
+
+See the [report-generation-tool.ts](https://github.com/mastra-ai/ui-dojo/blob/main/src/mastra/tools/report-generation-tool.ts) (backend) and [agent-network-custom-events.tsx](https://github.com/mastra-ai/ui-dojo/blob/main/src/pages/ai-sdk/agent-network-custom-events.tsx) (frontend) in UI Dojo.