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

package/.docs/raw/reference/ai-sdk/handle-workflow-stream.mdx

@@ -0,0 +1,116 @@
+---
+title: "Reference: handleWorkflowStream() | AI SDK"
+description: API reference for handleWorkflowStream(), a framework-agnostic handler for streaming workflow execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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](/docs/v1/server-db/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()`](/reference/v1/ai-sdk/workflow-route) if you want to create a workflow route inside a Mastra server.
+
+:::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 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.
+
+:::
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript title="app/api/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 params = await req.json();
+  const stream = await handleWorkflowStream({
+    mastra,
+    workflowId: 'weatherWorkflow',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "The Mastra instance containing registered workflows.",
+      isOptional: false,
+    },
+    {
+      name: "workflowId",
+      type: "string",
+      description: "The ID of the workflow to execute.",
+      isOptional: false,
+    },
+    {
+      name: "params",
+      type: "WorkflowStreamHandlerParams",
+      description: "Parameters for the workflow stream.",
+      isOptional: false,
+    },
+    {
+      name: "params.runId",
+      type: "string",
+      description: "Optional run ID for the workflow execution.",
+      isOptional: true,
+    },
+    {
+      name: "params.resourceId",
+      type: "string",
+      description: "Optional resource ID for the workflow run.",
+      isOptional: true,
+    },
+    {
+      name: "params.inputData",
+      type: "Record<string, any>",
+      description: "Input data for starting a new workflow execution.",
+      isOptional: true,
+    },
+    {
+      name: "params.resumeData",
+      type: "Record<string, any>",
+      description: "Data for resuming a suspended workflow execution.",
+      isOptional: true,
+    },
+    {
+      name: "params.requestContext",
+      type: "RequestContext",
+      description: "Request context to pass to the workflow execution.",
+      isOptional: true,
+    },
+    {
+      name: "params.tracingOptions",
+      type: "TracingOptions",
+      description: "Options for tracing and observability.",
+      isOptional: true,
+    },
+    {
+      name: "params.step",
+      type: "string",
+      description: "Specific step to target in the workflow.",
+      isOptional: true,
+    },
+    {
+      name: "includeTextStreamParts",
+      type: "boolean",
+      description: "Whether to include text stream parts in the output.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+  ]}
+/>

package/.docs/raw/reference/ai-sdk/network-route.mdx

@@ -0,0 +1,99 @@
+---
+title: "Reference: networkRoute() | AI SDK"
+description: API reference for networkRoute(), a function to create network route handlers for streaming network execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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](/docs/v1/server-db/custom-api-routes).
+
+Use [`handleNetworkStream()`](/reference/v1/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 title="src/mastra/index.ts" copy
+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 title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { networkRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      networkRoute({
+        path: "/network/:agentId",
+      }),
+    ],
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "path",
+      type: "string",
+      description: "The route path (e.g., `/network` or `/network/:agentId`). Include `:agentId` for dynamic agent routing.",
+      isOptional: false,
+      defaultValue: "'/network/:agentId'",
+    },
+    {
+      name: "agent",
+      type: "string",
+      description: "The ID of the routing agent to use for this network route. Required if the path doesn't include `:agentId`.",
+      isOptional: true,
+    },
+    {
+      name: "defaultOptions",
+      type: "AgentExecutionOptions",
+      description: "Default options passed to agent execution. These can include instructions, memory configuration, maxSteps, and other execution settings.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## 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/raw/reference/ai-sdk/to-ai-sdk-stream.mdx

@@ -0,0 +1,289 @@
+---
+title: "Reference: toAISdkStream() | AI SDK"
+description: API reference for toAISdkStream(), a function to convert Mastra streams to AI SDK-compatible streams.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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()`](/reference/v1/ai-sdk/chat-route) or [`workflowRoute()`](/reference/v1/ai-sdk/workflow-route).
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript title="app/api/chat/route.ts" copy
+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:
+
+<PropertiesTable
+  content={[
+    {
+      name: "from",
+      type: "'agent' | 'network' | 'workflow'",
+      description: "The type of Mastra stream being converted.",
+      isOptional: false,
+      defaultValue: "'agent'",
+    },
+    {
+      name: "lastMessageId",
+      type: "string",
+      description: "(Agent only) The ID of the last message in the conversation.",
+      isOptional: true,
+    },
+    {
+      name: "sendStart",
+      type: "boolean",
+      description: "(Agent only) Whether to send start events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendFinish",
+      type: "boolean",
+      description: "(Agent only) Whether to send finish events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendReasoning",
+      type: "boolean",
+      description: "(Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream reasoning content from models that support extended thinking.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "sendSources",
+      type: "boolean",
+      description: "(Agent only) Whether to include source citations in the output.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "includeTextStreamParts",
+      type: "boolean",
+      description: "(Workflow only) Whether to include text stream parts in the output.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "messageMetadata",
+      type: "(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined",
+      description: "(Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.",
+      isOptional: true,
+    },
+    {
+      name: "onError",
+      type: "(error: unknown) => string",
+      description: "(Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Examples
+
+### Converting a workflow stream
+
+```typescript title="app/api/workflow/route.ts" copy {13}
+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 title="app/api/network/route.ts" copy {12}
+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 title="app/api/reasoning/route.ts" copy {8-12,17-20}
+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 title="app/api/chat-with-metadata/route.ts" copy {13-19}
+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 title="client-stream-to-ai-sdk.ts" copy {14-23,25-35}
+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);
+}
+```

package/.docs/raw/reference/ai-sdk/workflow-route.mdx

@@ -0,0 +1,110 @@
+---
+title: "Reference: workflowRoute() | AI SDK"
+description: API reference for workflowRoute(), a function to create workflow route handlers for streaming workflow execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# workflowRoute()
+
+Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](/docs/v1/server-db/custom-api-routes).
+
+Use [`handleWorkflowStream()`](/reference/v1/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.
+
+:::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 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.
+
+:::
+
+## Usage example
+
+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";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow",
+        workflow: "weatherWorkflow",
+      }),
+    ],
+  },
+});
+```
+
+You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
+
+```typescript title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { workflowRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: "/workflow/:workflowId",
+      }),
+    ],
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "path",
+      type: "string",
+      description: "The route path (e.g., `/workflow` or `/workflow/:workflowId`). Include `:workflowId` for dynamic workflow routing.",
+      isOptional: true,
+      defaultValue: "'/api/workflows/:workflowId/stream'",
+    },
+    {
+      name: "workflow",
+      type: "string",
+      description: "Fixed workflow ID when not using dynamic routing.",
+      isOptional: true,
+      defaultValue: "undefined",
+    },
+    {
+      name: "includeTextStreamParts",
+      type: "boolean",
+      description: "Whether to include text stream parts in the output.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+  ]}
+/>
+
+## 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 workflow route, for example to pass additional configuration to the workflow:
+
+```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
+          }
+        },
+      };
+    },
+  }),
+});
+```

package/.docs/raw/reference/observability/tracing/bridges/otel.mdx

@@ -143,6 +143,33 @@ The OtelBridge requires an active OpenTelemetry SDK to function. The bridge read
 
 See the [OtelBridge Guide](/docs/v1/observability/tracing/bridges/otel#configuration) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 
+## Tags Support
+
+The OtelBridge supports trace tagging for categorization and filtering. Tags are only applied to root spans and are included as the `mastra.tags` attribute on native OTEL spans.
+
+### Usage
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute:
+
+```json
+{
+  "mastra.tags": "[\"production\",\"experiment-v2\",\"user-request\"]"
+}
+```
+
+This format ensures compatibility with all OTEL-compatible backends and collectors.
+
 ## Related
 
 - [OtelBridge Guide](/docs/v1/observability/tracing/bridges/otel) - Setup guide with examples

package/.docs/raw/reference/observability/tracing/exporters/arize.mdx

@@ -161,6 +161,31 @@ const exporter = new ArizeExporter({
 
 The ArizeExporter implements [OpenInference Semantic Conventions](https://github.com/Arize-ai/openinference/tree/main/spec) for generative AI applications, providing standardized trace structure across different observability platforms.
 
+## Tags Support
+
+The ArizeExporter supports trace tagging for categorization and filtering. Tags are only applied to root spans and are mapped to the native OpenInference `tag.tags` semantic convention.
+
+### Usage
+
+```typescript
+const result = await agent.generate({
+  messages: [{ role: "user", content: "Hello" }],
+  tracingOptions: {
+    tags: ["production", "experiment-v2", "user-request"],
+  },
+});
+```
+
+### How Tags Are Stored
+
+Tags are stored using the OpenInference `tag.tags` attribute:
+
+```json
+{
+  "tag.tags": ["production", "experiment-v2", "user-request"]
+}
+```
+
 ## Related
 
 - [ArizeExporter Documentation](/docs/v1/observability/tracing/exporters/arize)