@mastra/mcp-docs-server 1.0.0-beta.7 → 1.0.0-beta.9

package/.docs/raw/guides/getting-started/quickstart.mdx

@@ -53,6 +53,17 @@ yarn create mastra@beta
 bun create mastra@beta
 ```
 
+:::warning
+
+Due to a [known issue with Bun](https://github.com/oven-sh/bun/issues/25314) you'll need to run these steps after creating the project:
+
+- `bun add @mastra/server@beta`
+- Delete your `node_modules` folder
+- Delete your `bun.lock` file
+- Run `bun install` to reinstall your packages
+
+:::
+
 </TabItem>
 </Tabs>
 

package/.docs/raw/guides/migrations/upgrade-to-v1/tools.mdx

@@ -11,11 +11,11 @@ Tool execution signatures have been updated to use separate input and context pa
 
 ### `createTool` execute signature to `(inputData, context)` format
 
-All **`createTool`** execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
+All `createTool` execute functions now use a new signature with separate `inputData` and `context` parameters instead of a single destructured object. This change provides clearer separation between tool inputs and execution context.
 
 **Note:** This change only applies to `createTool`. If you're using `createStep` for workflows, the signature remains `async (inputData, context)` and does not need to be changed.
 
-To migrate, update **`createTool`** signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
+To migrate, update `createTool` signatures to use `inputData` as the first parameter (typed from `inputSchema`) and `context` as the second parameter.
 
 ```diff
   createTool({
@@ -35,7 +35,7 @@ To migrate, update **`createTool`** signatures to use `inputData` as the first p
 
 ### `createTool` context properties organization
 
-Context properties in **`createTool`** are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
+Context properties in `createTool` are now organized into namespaces. Agent-specific properties are under `context.agent`, workflow-specific properties are under `context.workflow`, and MCP-specific properties are under `context.mcp`. This change provides better organization and clearer API surface.
 
 For tools that are executed inside an agent, access agent-specific properties through `context.agent`.
 

package/.docs/raw/guides/migrations/upgrade-to-v1/workflows.mdx

@@ -177,6 +177,21 @@ To migrate, update any code that consumes branch outputs to handle optional valu
 
 If your code depends on non-optional types, add runtime checks or provide default values when accessing branch outputs.
 
+### `setState` is now async and the data passed is validated
+
+The `setState` function is now async. The data passed is now validated against the `stateSchema` defined in the step.
+The state data validation also uses the `validateInputs` flag to determine whether to validate the state data or not.
+Also, when calling `setState`, you can now pass only the state data being updated, instead of adding the previous state spread (`...state`).
+
+To migrate, update the `setState` function to be async.
+
+```diff
+- setState({ ...state, sharedCounter: state.sharedCounter + 1 });
++ await setState({ sharedCounter: state.sharedCounter + 1 });
++ // await setState({ ...state, sharedCounter: state.sharedCounter + 1 }); 
++ // this also works, as the previous state spread remains supported
+```
+
 ## Removed
 
 ### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods
@@ -197,6 +212,22 @@ npx @mastra/codemod@beta v1/workflow-stream-vnext .
 
 :::
 
+### `suspend` and `setState` are not available in step condition functions parameters
+
+The `suspend` and `setState` functions are not available in step condition functions parameters.
+
+To migrate, use the `suspend` function in the step execute function instead.
+
+```diff
+.dowhile(step, async ({ suspend, state, setState }) => {
+- setState({...state, updatedState: "updated state"})
+- await suspend({ reason: "Suspension reason" });
++ // Use the suspend/setState in the step execute function instead
+});
+```
+
+This is the same for `dountil` and `branch` condition functions parameters.
+
 ### Legacy workflows export
 
 The `./workflows/legacy` export path has been removed from `@mastra/core`. Legacy workflows are no longer supported.

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

@@ -0,0 +1,127 @@
+---
+title: "Reference: chatRoute() | AI SDK"
+description: API reference for chatRoute(), a function to create chat route handlers for streaming agent conversations in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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](/docs/v1/server-db/custom-api-routes).
+
+Use [`handleChatStream()`](/reference/v1/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 title="src/mastra/index.ts" copy
+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 title="src/mastra/index.ts" copy
+import { Mastra } from "@mastra/core";
+import { chatRoute } from "@mastra/ai-sdk";
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      chatRoute({
+        path: "/chat/:agentId",
+      }),
+    ],
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "path",
+      type: "string",
+      description: "The route path (e.g., `/chat` or `/chat/:agentId`). Include `:agentId` for dynamic agent routing.",
+      isOptional: false,
+      defaultValue: "'/chat/:agentId'",
+    },
+    {
+      name: "agent",
+      type: "string",
+      description: "The ID of the agent to use for this chat 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,
+    },
+    {
+      name: "sendStart",
+      type: "boolean",
+      description: "Whether to send start events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendFinish",
+      type: "boolean",
+      description: "Whether to send finish events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendReasoning",
+      type: "boolean",
+      description: "Whether to include reasoning steps in the stream.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "sendSources",
+      type: "boolean",
+      description: "Whether to include source citations in the stream.",
+      isOptional: true,
+      defaultValue: "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/raw/reference/ai-sdk/handle-chat-stream.mdx

@@ -0,0 +1,117 @@
+---
+title: "Reference: handleChatStream() | AI SDK"
+description: API reference for handleChatStream(), a framework-agnostic handler for streaming agent chat in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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](/docs/v1/server-db/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()`](/reference/v1/ai-sdk/chat-route) if you want to create a chat route inside a Mastra server.
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript title="app/api/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 params = await req.json();
+  const stream = await handleChatStream({
+    mastra,
+    agentId: 'weatherAgent',
+    params,
+  });
+  return createUIMessageStreamResponse({ stream });
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "The Mastra instance containing registered agents.",
+      isOptional: false,
+    },
+    {
+      name: "agentId",
+      type: "string",
+      description: "The ID of the agent to use for chat.",
+      isOptional: false,
+    },
+    {
+      name: "params",
+      type: "ChatStreamHandlerParams",
+      description: "Parameters for the chat stream, including messages and optional resume data.",
+      isOptional: false,
+    },
+    {
+      name: "params.messages",
+      type: "UIMessage[]",
+      description: "Array of messages in the conversation.",
+      isOptional: false,
+    },
+    {
+      name: "params.resumeData",
+      type: "Record<string, any>",
+      description: "Data for resuming a suspended agent execution. Requires `runId` to be set.",
+      isOptional: true,
+    },
+    {
+      name: "params.runId",
+      type: "string",
+      description: "The run ID. Required when `resumeData` is provided.",
+      isOptional: true,
+    },
+    {
+      name: "params.requestContext",
+      type: "RequestContext",
+      description: "Request context to pass to the agent execution.",
+      isOptional: true,
+    },
+    {
+      name: "defaultOptions",
+      type: "AgentExecutionOptions",
+      description: "Default options passed to agent execution. These are merged with params, with params taking precedence.",
+      isOptional: true,
+    },
+    {
+      name: "sendStart",
+      type: "boolean",
+      description: "Whether to send start events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendFinish",
+      type: "boolean",
+      description: "Whether to send finish events in the stream.",
+      isOptional: true,
+      defaultValue: "true",
+    },
+    {
+      name: "sendReasoning",
+      type: "boolean",
+      description: "Whether to include reasoning steps in the stream.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+    {
+      name: "sendSources",
+      type: "boolean",
+      description: "Whether to include source citations in the stream.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>

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

@@ -0,0 +1,64 @@
+---
+title: "Reference: handleNetworkStream() | AI SDK"
+description: API reference for handleNetworkStream(), a framework-agnostic handler for streaming network execution in AI SDK-compatible format.
+---
+
+import PropertiesTable from "@site/src/components/PropertiesTable";
+
+# 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](/docs/v1/server-db/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()`](/reference/v1/ai-sdk/network-route) if you want to create a network route inside a Mastra server.
+## Usage example
+
+Next.js App Router example:
+
+```typescript title="app/api/network/route.ts" copy
+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
+
+<PropertiesTable
+  content={[
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "The Mastra instance to use for agent lookup and execution.",
+      isOptional: false,
+    },
+    {
+      name: "agentId",
+      type: "string",
+      description: "The ID of the routing agent to execute as a network.",
+      isOptional: false,
+    },
+    {
+      name: "params",
+      type: "NetworkStreamHandlerParams",
+      description: "The request parameters containing messages and execution options. Includes `messages` (required) and any AgentExecutionOptions like `memory`, `maxSteps`, `runId`, etc.",
+      isOptional: false,
+    },
+    {
+      name: "defaultOptions",
+      type: "AgentExecutionOptions",
+      description: "Default options passed to agent execution. These are merged with params, with params taking precedence.",
+      isOptional: true,
+    },
+  ]}
+/>

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",
+          },
+        },
+      };
+    },
+  }),
+});
+```