@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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/dist/docs/references/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',
+          },
+        },
+      }
+    },
+  }),
+})
+```