@mastra/mcp-docs-server 1.1.5 → 1.1.6-alpha.0

package/.docs/reference/agents/network.md

@@ -0,0 +1,133 @@
+# Agent.network()
+
+The `.network()` method enables multi-agent collaboration and routing. This method accepts messages and optional execution options.
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { agent1, agent2 } from './agents'
+import { workflow1 } from './workflows'
+import { tool1, tool2 } from './tools'
+
+const agent = new Agent({
+  id: 'network-agent',
+  name: 'Network Agent',
+  instructions: 'You are a network agent that can help users with a variety of tasks.',
+  model: 'openai/gpt-5.1',
+  agents: {
+    agent1,
+    agent2,
+  },
+  workflows: {
+    workflow1,
+  },
+  tools: {
+    tool1,
+    tool2,
+  },
+})
+
+await agent.network(`
+  Find me the weather in Tokyo.
+  Based on the weather, plan an activity for me.
+`)
+```
+
+## Parameters
+
+**messages:** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): The messages to send to the agent. Can be a single string, array of strings, or structured message objects.
+
+**options?:** (`MultiPrimitiveExecutionOptions`): Optional configuration for the network process.
+
+### Options
+
+**maxSteps?:** (`number`): Maximum number of steps to run during execution.
+
+**memory?:** (`object`): thread:string | { id: string; metadata?: Record\<string, any>, title?: string }The conversation thread, as a string ID or an object with an \`id\` and optional \`metadata\`.resource:stringIdentifier for the user or resource associated with the thread.options?:MemoryConfigConfiguration for memory behavior, like message history and semantic recall.
+
+**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
+
+**tracingOptions?:** (`TracingOptions`): metadata?:Record\<string, any>Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.requestContextKeys?:string\[]Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.tags?:string\[]Tags to apply to this trace. String labels for categorizing and filtering traces.
+
+**telemetry?:** (`TelemetrySettings`): isEnabled?:booleanEnable or disable telemetry. Disabled by default while experimental.recordInputs?:booleanEnable or disable input recording. Enabled by default. You might want to disable input recording to avoid recording sensitive information.recordOutputs?:booleanEnable or disable output recording. Enabled by default. You might want to disable output recording to avoid recording sensitive information.functionId?:stringIdentifier for this function. Used to group telemetry data by function.
+
+**modelSettings?:** (`CallSettings`): temperature?:numberControls randomness in generation (0-2). Higher values make output more random.maxOutputTokens?:numberMaximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.maxRetries?:numberMaximum number of retry attempts for failed requests.topP?:numberNucleus sampling parameter (0-1). Controls diversity of generated text.topK?:numberTop-k sampling parameter. Limits vocabulary to k most likely tokens.presencePenalty?:numberPenalty for token presence (-2 to 2). Reduces repetition.frequencyPenalty?:numberPenalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.stopSequences?:string\[]Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
+
+**structuredOutput?:** (`StructuredOutputOptions`): schema:ZodSchema | JSONSchema7The schema to validate the output against. Can be a Zod schema or JSON Schema.model?:MastraModelConfigModel to use for generating the structured output. Defaults to the agent's model.instructions?:stringCustom instructions for generating the structured output.
+
+**runId?:** (`string`): Unique ID for this generation run. Useful for tracking and debugging purposes.
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
+
+**traceId?:** (`string`): The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.
+
+## Returns
+
+**stream:** (`MastraAgentNetworkStream<NetworkChunkType>`): A custom stream that extends ReadableStream\<NetworkChunkType> with additional network-specific properties
+
+**status:** (`Promise<RunStatus>`): A promise that resolves to the current workflow run status
+
+**result:** (`Promise<WorkflowResult<TState, TOutput, TSteps>>`): A promise that resolves to the final workflow result
+
+**usage:** (`Promise<{ promptTokens: number; completionTokens: number; totalTokens: number }>`): A promise that resolves to token usage statistics
+
+**object:** (`Promise<OUTPUT | undefined>`): A promise that resolves to the structured output object. Only available when structuredOutput option is provided. Resolves to undefined if no schema was specified.
+
+**objectStream:** (`ReadableStream<Partial<OUTPUT>>`): A stream of partial objects during structured output generation. Useful for streaming partial results as they're being generated.
+
+## Structured Output
+
+When you need typed, validated results from your network, use the `structuredOutput` option. The network will generate a response matching your schema after task completion.
+
+```typescript
+import { z } from 'zod'
+
+const resultSchema = z.object({
+  summary: z.string().describe('A brief summary of the findings'),
+  recommendations: z.array(z.string()).describe('List of recommendations'),
+  confidence: z.number().min(0).max(1).describe('Confidence score'),
+})
+
+const stream = await agent.network('Research AI trends and summarize', {
+  structuredOutput: {
+    schema: resultSchema,
+  },
+})
+
+// Consume the stream
+for await (const chunk of stream) {
+  // Handle streaming events
+}
+
+// Get the typed result
+const result = await stream.object
+// result is typed as { summary: string; recommendations: string[]; confidence: number }
+console.log(result?.summary)
+console.log(result?.recommendations)
+```
+
+### Streaming Partial Objects
+
+You can also stream partial objects as they're being generated:
+
+```typescript
+const stream = await agent.network('Analyze data', {
+  structuredOutput: { schema: resultSchema },
+})
+
+// Stream partial objects
+for await (const partial of stream.objectStream) {
+  console.log('Partial result:', partial)
+}
+
+// Get final result
+const final = await stream.object
+```
+
+### Chunk Types
+
+When using structured output, additional chunk types are emitted:
+
+- `network-object`: Emitted with partial objects during streaming
+- `network-object-result`: Emitted with the final structured object

package/.docs/reference/ai-sdk/chat-route.md

@@ -0,0 +1,82 @@
+# chatRoute()
+
+Creates a chat route handler for streaming agent conversations using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
+
+Use [`handleChatStream()`](https://mastra.ai/reference/ai-sdk/handle-chat-stream) if you need a framework-agnostic handler.
+
+## Usage example
+
+This example shows how to set up a chat route at the `/chat` endpoint that uses an agent with the ID `weatherAgent`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { chatRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+})
+```
+
+You can also use dynamic agent routing based on an `agentId`. The URL `/chat/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { chatRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: '/chat/:agentId',
+      }),
+    ],
+  },
+})
+```
+
+## Parameters
+
+**path:** (`string`): The route path (e.g., \`/chat\` or \`/chat/:agentId\`). Include \`:agentId\` for dynamic agent routing. (Default: `'/chat/:agentId'`)
+
+**agent?:** (`string`): The ID of the agent to use for this chat route. Required if the path doesn't include \`:agentId\`.
+
+**defaultOptions?:** (`AgentExecutionOptions`): Default options passed to agent execution. These can include instructions, memory configuration, maxSteps, and other execution settings.
+
+**sendStart?:** (`boolean`): Whether to send start events in the stream. (Default: `true`)
+
+**sendFinish?:** (`boolean`): Whether to send finish events in the stream. (Default: `true`)
+
+**sendReasoning?:** (`boolean`): Whether to include reasoning steps in the stream. (Default: `false`)
+
+**sendSources?:** (`boolean`): Whether to include source citations in the stream. (Default: `false`)
+
+## Additional configuration
+
+You can 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:
+
+```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',
+          },
+        },
+      }
+    },
+  }),
+})
+```

package/.docs/reference/ai-sdk/handle-chat-stream.md

@@ -0,0 +1,53 @@
+# handleChatStream()
+
+Framework-agnostic handler for streaming agent chat in AI SDK-compatible format. Use this function directly when you need to handle chat streaming outside Hono or Mastra's own [apiRoutes](https://mastra.ai/docs/server/custom-api-routes) feature.
+
+`handleChatStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
+
+Use [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) if you want to create a chat route inside a Mastra server.
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { handleChatStream } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function POST(req: Request) {
+  const params = await req.json()
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params,
+  })
+  return createUIMessageStreamResponse({ stream })
+}
+```
+
+## Parameters
+
+**mastra:** (`Mastra`): The Mastra instance containing registered agents.
+
+**agentId:** (`string`): The ID of the agent to use for chat.
+
+**params:** (`ChatStreamHandlerParams`): Parameters for the chat stream, including messages and optional resume data.
+
+**params.messages:** (`UIMessage[]`): Array of messages in the conversation.
+
+**params.resumeData?:** (`Record<string, any>`): Data for resuming a suspended agent execution. Requires \`runId\` to be set.
+
+**params.runId?:** (`string`): The run ID. Required when \`resumeData\` is provided.
+
+**params.requestContext?:** (`RequestContext`): Request context to pass to the agent execution.
+
+**defaultOptions?:** (`AgentExecutionOptions`): Default options passed to agent execution. These are merged with params, with params taking precedence.
+
+**sendStart?:** (`boolean`): Whether to send start events in the stream. (Default: `true`)
+
+**sendFinish?:** (`boolean`): Whether to send finish events in the stream. (Default: `true`)
+
+**sendReasoning?:** (`boolean`): Whether to include reasoning steps in the stream. (Default: `false`)
+
+**sendSources?:** (`boolean`): Whether to include source citations in the stream. (Default: `false`)

package/.docs/reference/ai-sdk/handle-network-stream.md

@@ -0,0 +1,37 @@
+# handleNetworkStream()
+
+Framework-agnostic handler for streaming network execution in AI SDK-compatible format. Use this function directly when you need to handle network streaming outside Hono or Mastra's own [apiRoutes](https://mastra.ai/docs/server/custom-api-routes) feature.
+
+`handleNetworkStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
+
+Use [`networkRoute()`](https://mastra.ai/reference/ai-sdk/network-route) if you want to create a network route inside a Mastra server.
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { handleNetworkStream } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function POST(req: Request) {
+  const params = await req.json()
+  const stream = await handleNetworkStream({
+    mastra,
+    agentId: 'routingAgent',
+    params,
+  })
+  return createUIMessageStreamResponse({ stream })
+}
+```
+
+## Parameters
+
+**mastra:** (`Mastra`): The Mastra instance to use for agent lookup and execution.
+
+**agentId:** (`string`): The ID of the routing agent to execute as a network.
+
+**params:** (`NetworkStreamHandlerParams`): The request parameters containing messages and execution options. Includes \`messages\` (required) and any AgentExecutionOptions like \`memory\`, \`maxSteps\`, \`runId\`, etc.
+
+**defaultOptions?:** (`AgentExecutionOptions`): Default options passed to agent execution. These are merged with params, with params taking precedence.

package/.docs/reference/ai-sdk/handle-workflow-stream.md

@@ -0,0 +1,55 @@
+# handleWorkflowStream()
+
+Framework-agnostic handler for streaming workflow execution in AI SDK-compatible format. Use this function directly when you need to handle workflow streaming outside Hono or Mastra's own [apiRoutes](https://mastra.ai/docs/server/custom-api-routes) feature.
+
+`handleWorkflowStream()` returns a `ReadableStream` that you can wrap with [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).
+
+Use [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route) if you want to create a workflow route inside a Mastra server.
+
+> **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 forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
+>
+> See [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming) for more details.
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { handleWorkflowStream } from '@mastra/ai-sdk'
+import { createUIMessageStreamResponse } from 'ai'
+import { mastra } from '@/src/mastra'
+
+export async function POST(req: Request) {
+  const params = await req.json()
+  const stream = await handleWorkflowStream({
+    mastra,
+    workflowId: 'weatherWorkflow',
+    params,
+  })
+  return createUIMessageStreamResponse({ stream })
+}
+```
+
+## Parameters
+
+**mastra:** (`Mastra`): The Mastra instance containing registered workflows.
+
+**workflowId:** (`string`): The ID of the workflow to execute.
+
+**params:** (`WorkflowStreamHandlerParams`): Parameters for the workflow stream.
+
+**params.runId?:** (`string`): Optional run ID for the workflow execution.
+
+**params.resourceId?:** (`string`): Optional resource ID for the workflow run.
+
+**params.inputData?:** (`Record<string, any>`): Input data for starting a new workflow execution.
+
+**params.resumeData?:** (`Record<string, any>`): Data for resuming a suspended workflow execution.
+
+**params.requestContext?:** (`RequestContext`): Request context to pass to the workflow execution.
+
+**params.tracingOptions?:** (`TracingOptions`): Options for tracing and observability.
+
+**params.step?:** (`string`): Specific step to target in the workflow.
+
+**includeTextStreamParts?:** (`boolean`): Whether to include text stream parts in the output. (Default: `true`)

package/.docs/reference/ai-sdk/network-route.md

@@ -0,0 +1,74 @@
+# networkRoute()
+
+Creates a network route handler for streaming network execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent network, and streams the response back to the client in AI SDK-compatible format. Agent networks allow a routing agent to delegate tasks to other agents. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
+
+Use [`handleNetworkStream()`](https://mastra.ai/reference/ai-sdk/handle-network-stream) if you need a framework-agnostic handler.
+
+## Usage example
+
+This example shows how to set up a network route at the `/network` endpoint that uses an agent with the ID `weatherAgent`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { networkRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: '/network',
+        agent: 'weatherAgent',
+      }),
+    ],
+  },
+})
+```
+
+You can also use dynamic agent routing based on an `agentId`. The URL `/network/weatherAgent` will resolve to the agent with the ID `weatherAgent`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { networkRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: '/network/:agentId',
+      }),
+    ],
+  },
+})
+```
+
+## Parameters
+
+**path:** (`string`): The route path (e.g., \`/network\` or \`/network/:agentId\`). Include \`:agentId\` for dynamic agent routing. (Default: `'/network/:agentId'`)
+
+**agent?:** (`string`): The ID of the routing agent to use for this network route. Required if the path doesn't include \`:agentId\`.
+
+**defaultOptions?:** (`AgentExecutionOptions`): Default options passed to agent execution. These can include instructions, memory configuration, maxSteps, and other execution settings.
+
+## Additional configuration
+
+You can 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 network route, for example to pass additional configuration to the agent:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } = useChat({
+  transport: new DefaultChatTransport({
+    api: 'http://localhost:4111/network',
+    prepareSendMessagesRequest({ messages }) {
+      return {
+        body: {
+          messages,
+          // Pass memory config
+          memory: {
+            thread: 'user-1',
+            resource: 'user-1',
+          },
+        },
+      }
+    },
+  }),
+})
+```

package/.docs/reference/ai-sdk/to-ai-sdk-stream.md

@@ -0,0 +1,231 @@
+# toAISdkStream()
+
+Converts Mastra streams (agent, network, or workflow) to AI SDK-compatible streams. Use this function when you need to manually transform Mastra streams for use with AI SDK's `createUIMessageStream()` and `createUIMessageStreamResponse()`.
+
+This is useful when building custom streaming endpoints outside Mastra's provided route helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) or [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route).
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const myAgent = mastra.getAgent('weatherAgent')
+  const stream = await myAgent.stream(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'agent' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+> **Tip:** Pass `messages` to `originalMessages` in `createUIMessageStream()` to avoid duplicated assistant messages in the UI. See [Troubleshooting: Repeated Assistant Messages](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages) for details.
+
+## Parameters
+
+The first parameter is the Mastra stream to convert. It can be one of:
+
+- `MastraModelOutput` - An agent stream from `agent.stream()`
+- `MastraAgentNetworkStream` - A network stream from `agent.network()`
+- `MastraWorkflowStream` or `WorkflowRunOutput` - A workflow stream
+
+The second parameter is an options object:
+
+**from:** (`'agent' | 'network' | 'workflow'`): The type of Mastra stream being converted. (Default: `'agent'`)
+
+**lastMessageId?:** (`string`): (Agent only) The ID of the last message in the conversation.
+
+**sendStart?:** (`boolean`): (Agent only) Whether to send start events in the stream. (Default: `true`)
+
+**sendFinish?:** (`boolean`): (Agent only) Whether to send finish events in the stream. (Default: `true`)
+
+**sendReasoning?:** (`boolean`): (Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream reasoning content from models that support extended thinking. (Default: `false`)
+
+**sendSources?:** (`boolean`): (Agent only) Whether to include source citations in the output. (Default: `false`)
+
+**includeTextStreamParts?:** (`boolean`): (Workflow only) Whether to include text stream parts in the output. (Default: `true`)
+
+**messageMetadata?:** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): (Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.
+
+**onError?:** (`(error: unknown) => string`): (Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.
+
+## Examples
+
+### Converting a workflow stream
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { input } = await req.json()
+  const workflow = mastra.getWorkflow('myWorkflow')
+  const run = workflow.createRun()
+  const stream = await run.stream({ inputData: input })
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'workflow' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Converting a network stream
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const routingAgent = mastra.getAgent('routingAgent')
+  const stream = await routingAgent.network(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'network' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Converting an agent stream with reasoning enabled
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const reasoningAgent = mastra.getAgent('reasoningAgent')
+  const stream = await reasoningAgent.stream(messages, {
+    providerOptions: {
+      openai: { reasoningEffort: 'high' },
+    },
+  })
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: 'agent',
+        sendReasoning: true,
+      })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Using messageMetadata
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const myAgent = mastra.getAgent('weatherAgent')
+  const stream = await myAgent.stream(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: 'agent',
+        messageMetadata: ({ part }) => ({
+          timestamp: Date.now(),
+          partType: part.type,
+        }),
+      })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Client-side stream transformation
+
+If you're using the Mastra client SDK (`@mastra/client-js`) on the client side and want to convert streams to AI SDK format:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { createUIMessageStream } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+})
+
+const agent = client.getAgent('weatherAgent')
+const response = await agent.stream('What is the weather in Tokyo?')
+
+// Convert the client SDK stream to a ReadableStream<ChunkType>
+const chunkStream = new ReadableStream<ChunkType>({
+  async start(controller) {
+    await response.processDataStream({
+      onChunk: async chunk => {
+        controller.enqueue(chunk)
+      },
+    })
+    controller.close()
+  },
+})
+
+// Transform to AI SDK format
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
+      from: 'agent',
+    })) {
+      await writer.write(part)
+    }
+  },
+})
+
+for await (const part of uiMessageStream) {
+  console.log(part)
+}
+```