@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/reference/agents/getTools.md

@@ -0,0 +1,29 @@
+# Agent.getTools()
+
+The `.getTools()` method retrieves the tools configured for an agent, resolving them if they're a function. These tools extend the agent's capabilities, allowing it to perform specific actions or access external systems.
+
+## Usage example
+
+```typescript
+await agent.getTools()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing runtime context. (Default: `{}`)
+
+## Returns
+
+**tools:** (`TTools | Promise<TTools>`): The tools configured for the agent, either as a direct object or a promise that resolves to the tools.
+
+## Extended usage example
+
+```typescript
+await agent.getTools({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Runtime context for dependency injection and contextual information. (Default: `new RequestContext()`)

package/.docs/reference/agents/getVoice.md

@@ -0,0 +1,34 @@
+# Agent.getVoice()
+
+The `.getVoice()` method retrieves the voice provider configured for an agent, resolving it if it's a function. This method is used to access the agent's speech capabilities for text-to-speech and speech-to-text functionality.
+
+## Usage example
+
+```typescript
+await agent.getVoice()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+## Returns
+
+**voice:** (`Promise<MastraVoice>`): A promise that resolves to the voice provider configured for the agent, or a default voice provider if none was configured.
+
+## Extended usage example
+
+```typescript
+await agent.getVoice({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
+
+## Related
+
+- [Adding voice to agents](https://mastra.ai/docs/agents/adding-voice)
+- [Voice providers](https://mastra.ai/reference/voice/mastra-voice)

package/.docs/reference/agents/listAgents.md

@@ -0,0 +1,35 @@
+# Agent.listAgents()
+
+The `.listAgents()` method retrieves the subagents configured for an agent, resolving them if they're a function. These subagents enable the agent to access other agents and perform complex actions.
+
+## Usage example
+
+```typescript
+await agent.listAgents()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+## Returns
+
+**agents:** (`Promise<Record<string, Agent>>`): A promise that resolves to a record of agent names to their corresponding Agent instances.
+
+## Extended usage example
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+await agent.listAgents({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)

package/.docs/reference/agents/listScorers.md

@@ -0,0 +1,34 @@
+# Agent.listScorers()
+
+The `.listScorers()` method retrieves the scoring configuration configured for an agent, resolving it if it's a function. This method provides access to the scoring system used for evaluating agent responses and performance.
+
+## Usage example
+
+```typescript
+await agent.listScorers()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+## Returns
+
+**scorers:** (`MastraScorers | Promise<MastraScorers>`): The scoring configuration configured for the agent, either as a direct object or a promise that resolves to the scorers.
+
+## Extended usage example
+
+```typescript
+await agent.listScorers({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Request Context](https://mastra.ai/docs/server/request-context)

package/.docs/reference/agents/listTools.md

@@ -0,0 +1,34 @@
+# Agent.listTools()
+
+The `.listTools()` method retrieves the tools configured for an agent, resolving them if they're a function. These tools extend the agent's capabilities, allowing it to perform specific actions or access external systems.
+
+## Usage example
+
+```typescript
+await agent.listTools()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+## Returns
+
+**tools:** (`TTools | Promise<TTools>`): The tools configured for the agent, either as a direct object or a promise that resolves to the tools.
+
+## Extended usage example
+
+```typescript
+await agent.listTools({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
+
+## Related
+
+- [Using tools with agents](https://mastra.ai/docs/agents/using-tools)
+- [Creating tools](https://mastra.ai/docs/mcp/overview)

package/.docs/reference/agents/listWorkflows.md

@@ -0,0 +1,34 @@
+# Agent.listWorkflows()
+
+The `.listWorkflows()` method retrieves the workflows configured for an agent, resolving them if they're a function. These workflows enable the agent to execute complex, multi-step processes with defined execution paths.
+
+## Usage example
+
+```typescript
+await agent.listWorkflows()
+```
+
+## Parameters
+
+**options?:** (`{ requestContext?: RequestContext }`): Optional configuration object containing request context. (Default: `{}`)
+
+## Returns
+
+**workflows:** (`Promise<Record<string, Workflow>>`): A promise that resolves to a record of workflow names to their corresponding Workflow instances.
+
+## Extended usage example
+
+```typescript
+await agent.listWorkflows({
+  requestContext: new RequestContext(),
+})
+```
+
+### Options parameters
+
+**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information. (Default: `new RequestContext()`)
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)

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

@@ -0,0 +1,170 @@
+# 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.
+
+**abortSignal?:** (`AbortSignal`): Signal to abort the network execution. When aborted, the network stops routing, cancels any in-progress sub-agent, tool, or workflow execution, and skips saving partial results to memory.
+
+**onAbort?:** (`(event: { primitiveType: string; primitiveId: string; iteration: number }) => void | Promise<void>`): Callback fired when the network is aborted. Receives an event with the type and ID of the primitive that was executing when the abort occurred.
+
+**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.
+
+**onStepFinish?:** (`(event: any) => Promise<void> | void`): Callback fired after each LLM step within a sub-agent execution. Receives step details including finish reason and token usage.
+
+**onError?:** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback fired when an error occurs during sub-agent execution.
+
+## 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
+
+## Aborting a Network
+
+Use `abortSignal` to cancel a running network. When aborted, the network stops routing, cancels any in-progress sub-agent, tool, or workflow execution, and does not save partial results to memory.
+
+```typescript
+const controller = new AbortController()
+
+// Abort after 30 seconds
+setTimeout(() => controller.abort(), 30_000)
+
+const stream = await agent.network('Research this topic thoroughly', {
+  abortSignal: controller.signal,
+  onAbort: ({ primitiveType, primitiveId, iteration }) => {
+    console.log(`Aborted ${primitiveType} "${primitiveId}" at iteration ${iteration}`)
+  },
+})
+
+for await (const chunk of stream) {
+  if (
+    chunk.type === 'routing-agent-abort' ||
+    chunk.type === 'agent-execution-abort' ||
+    chunk.type === 'tool-execution-abort' ||
+    chunk.type === 'workflow-execution-abort'
+  ) {
+    console.log('Network was aborted')
+  }
+}
+```

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