@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/reference-core-getWorkflow.md

@@ -0,0 +1,42 @@
+# Mastra.getWorkflow()
+
+The `.getWorkflow()` method is used to retrieve a workflow by its registration key. This method provides full TypeScript type inference for workflow input and output schemas.
+
+## Usage example
+
+```typescript
+// Retrieve workflow by its registration key (recommended for type inference)
+const workflow = mastra.getWorkflow('testWorkflow')
+const run = await workflow.createRun()
+
+// TypeScript will properly infer the input schema type
+await run.startAsync({
+  inputData: {
+    /* properly typed */
+  },
+})
+```
+
+## Type inference
+
+For best TypeScript support, use `getWorkflow()` with the workflow's **registration key** (the key used when adding the workflow to Mastra). This provides full type inference for:
+
+- Input data schemas
+- Output data schemas
+- Step results
+
+If you need to retrieve a workflow by its `id` property instead of its registration key, you can use `getWorkflowById()`, but note that type inference will not be as precise.
+
+## Parameters
+
+**id:** (`TWorkflowId extends keyof TWorkflows`): The ID of the workflow to retrieve. Must be a valid workflow ID that exists in the Mastra configuration.
+
+**options:** (`{ serialized?: boolean }`): Optional configuration object. When \`serialized\` is true, returns only the workflow name instead of the full workflow instance.
+
+## Returns
+
+**workflow:** (`TWorkflows[TWorkflowId]`): The workflow instance with the specified ID. Throws an error if the workflow is not found.
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/dist/docs/references/reference-core-listAgents.md

@@ -0,0 +1,21 @@
+# Mastra.listAgents()
+
+The `.listAgents()` method is used to retrieve all agents that have been configured in the Mastra instance.
+
+## Usage example
+
+```typescript
+mastra.listAgents()
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+**agents:** (`TAgents`): A record of all configured agents, where keys are agent names and values are agent instances.
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)

package/dist/docs/references/reference-core-listGateways.md

@@ -0,0 +1,40 @@
+# Mastra.listGateways()
+
+Returns a record of all registered gateways, indexed by their registration keys.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  gateways: {
+    myGateway: new MyCustomGateway(),
+    anotherGateway: new AnotherGateway(),
+  },
+})
+
+const gateways = mastra.listGateways()
+console.log(Object.keys(gateways)) // ['myGateway', 'anotherGateway']
+
+// Iterate over all gateways
+for (const [key, gateway] of Object.entries(gateways)) {
+  console.log(`${key}: ${gateway.name}`)
+}
+```
+
+## Parameters
+
+None.
+
+## Returns
+
+**gateways:** (`Record<string, MastraModelGateway>`): A record of gateway instances indexed by registration key
+
+## Related
+
+- [Mastra.getGateway()](https://mastra.ai/reference/core/getGateway) - Get gateway by registration key
+- [Mastra.getGatewayById()](https://mastra.ai/reference/core/getGatewayById) - Get gateway by ID
+- [Mastra.addGateway()](https://mastra.ai/reference/core/addGateway) - Add a gateway
+- [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway) - Gateway base class
+- [Custom Gateways Guide](https://mastra.ai/models/gateways/custom-gateways) - Creating custom gateways

package/dist/docs/references/reference-core-listLogs.md

@@ -0,0 +1,38 @@
+# Mastra.listLogs()
+
+The `.listLogs()` method is used to retrieve all logs for a specific transport ID. This method requires a configured logger that supports the `listLogs` operation.
+
+## Usage example
+
+```typescript
+mastra.listLogs('456')
+```
+
+## Parameters
+
+**transportId:** (`string`): The transport ID to retrieve logs from.
+
+**options:** (`object`): Optional parameters for filtering and pagination. See Options section below for details.
+
+### Options
+
+**fromDate:** (`Date`): Optional start date for filtering logs. e.g., new Date('2024-01-01').
+
+**toDate:** (`Date`): Optional end date for filtering logs. e.g., new Date('2024-01-31').
+
+**logLevel:** (`LogLevel`): Optional log level to filter by.
+
+**filters:** (`Record<string, any>`): Optional additional filters to apply to the log query.
+
+**page:** (`number`): Optional page number for pagination.
+
+**perPage:** (`number`): Optional number of logs per page for pagination.
+
+## Returns
+
+**logs:** (`Promise<any>`): A promise that resolves to the logs for the specified transport ID.
+
+## Related
+
+- [Logging overview](https://mastra.ai/docs/observability/logging)
+- [Logger reference](https://mastra.ai/reference/logging/pino-logger)

package/dist/docs/references/reference-core-listLogsByRunId.md

@@ -0,0 +1,36 @@
+# Mastra.listLogsByRunId()
+
+The `.listLogsByRunId()` method is used to retrieve logs for a specific run ID and transport ID. This method requires a configured logger that supports the `listLogsByRunId` operation.
+
+## Usage example
+
+```typescript
+mastra.listLogsByRunId({ runId: '123', transportId: '456' })
+```
+
+## Parameters
+
+**runId:** (`string`): The run ID to retrieve logs for.
+
+**transportId:** (`string`): The transport ID to retrieve logs from.
+
+**fromDate:** (`Date`): Optional start date for filtering logs. e.g., new Date('2024-01-01').
+
+**toDate:** (`Date`): Optional end date for filtering logs. e.g., new Date('2024-01-31').
+
+**logLevel:** (`LogLevel`): Optional log level to filter by.
+
+**filters:** (`Record<string, any>`): Optional additional filters to apply to the log query.
+
+**page:** (`number`): Optional page number for pagination.
+
+**perPage:** (`number`): Optional number of logs per page for pagination.
+
+## Returns
+
+**logs:** (`Promise<any>`): A promise that resolves to the logs for the specified run ID and transport ID.
+
+## Related
+
+- [Logging overview](https://mastra.ai/docs/observability/logging)
+- [Logger reference](https://mastra.ai/reference/logging/pino-logger)

package/dist/docs/references/reference-core-listMCPServers.md

@@ -0,0 +1,55 @@
+# Mastra.listMCPServers()
+
+The `.listMCPServers()` method is used to retrieve all MCP server instances that have been registered in the Mastra instance. The returned record uses registry keys (the keys from the `mcpServers` configuration) as keys.
+
+## Usage example
+
+```typescript
+// Register MCP servers
+const server1 = new MCPServer({
+  id: 'server-one',
+  name: 'Server One',
+  version: '1.0.0',
+  tools: {
+    /* ... */
+  },
+})
+
+const server2 = new MCPServer({
+  id: 'server-two',
+  name: 'Server Two',
+  version: '1.0.0',
+  tools: {
+    /* ... */
+  },
+})
+
+export const mastra = new Mastra({
+  mcpServers: {
+    firstServer: server1, // Registry key: 'firstServer'
+    secondServer: server2, // Registry key: 'secondServer'
+  },
+})
+
+// List all registered servers
+const servers = mastra.listMCPServers()
+// Returns: { firstServer: MCPServerBase, secondServer: MCPServerBase }
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+**servers:** (`Record<string, MCPServerBase> | undefined`): A record of all registered MCP server instances, where keys are the registry keys (from mcpServers configuration) and values are MCPServerBase instances, or undefined if no servers are registered.
+
+## Related Methods
+
+- [Mastra.getMCPServer()](https://mastra.ai/reference/core/getMCPServer) - Retrieve an MCP server by its registry key
+- [Mastra.getMCPServerById()](https://mastra.ai/reference/core/getMCPServerById) - Retrieve an MCP server by its intrinsic `id` property
+
+## See Also
+
+- [MCP overview](https://mastra.ai/docs/mcp/overview)
+- [MCP server reference](https://mastra.ai/reference/tools/mcp-server)

package/dist/docs/references/reference-core-listMemory.md

@@ -0,0 +1,56 @@
+# Mastra.listMemory()
+
+The `.listMemory()` method returns all memory instances registered with the Mastra instance.
+
+## Usage example
+
+```typescript
+const memoryInstances = mastra.listMemory()
+
+for (const [key, memory] of Object.entries(memoryInstances)) {
+  console.log(`Memory "${key}": ${memory.id}`)
+}
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**memory:** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
+
+## Example: Checking Registered Memory
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const conversationMemory = new Memory({
+  id: 'conversation-memory',
+  storage: new LibSQLStore({ id: 'conversation-store', url: ':memory:' }),
+})
+
+const analyticsMemory = new Memory({
+  id: 'analytics-memory',
+  storage: new LibSQLStore({ id: 'analytics-store', url: ':memory:' }),
+})
+
+const mastra = new Mastra({
+  memory: {
+    conversationMemory,
+    analyticsMemory,
+  },
+})
+
+// List all registered memory instances
+const allMemory = mastra.listMemory()
+console.log(Object.keys(allMemory)) // ["conversationMemory", "analyticsMemory"]
+```
+
+## Related
+
+- [Mastra.getMemory()](https://mastra.ai/reference/core/getMemory)
+- [Memory overview](https://mastra.ai/docs/memory/overview)
+- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

package/dist/docs/references/reference-core-listScorers.md

@@ -0,0 +1,29 @@
+# listScorers()
+
+The `listScorers()` method returns all scorers that have been registered with the Mastra instance. Scorers are used for evaluating AI outputs and can override default scorers during agent generation or workflow execution.
+
+## Usage Example
+
+```typescript
+import { mastra } from './mastra'
+
+// Get all registered scorers
+const allScorers = mastra.listScorers()
+
+// Access a specific scorer
+const myScorer = allScorers.relevancyScorer
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**scorers:** (`Record<string, MastraScorer> | undefined`): An object containing all registered scorers, where keys are scorer names and values are MastraScorer instances. Returns undefined if no scorers are registered.
+
+## Related
+
+- [getScorer()](https://mastra.ai/reference/core/getScorer) - Get a specific scorer by key
+- [getScorerById()](https://mastra.ai/reference/core/getScorerById) - Get a scorer by its id property
+- [Scorers Overview](https://mastra.ai/docs/evals/overview) - Learn about creating and using scorers

package/dist/docs/references/reference-core-listStoredAgents.md

@@ -0,0 +1,93 @@
+# Mastra.listStoredAgents()
+
+The `.listStoredAgents()` method retrieves a paginated list of agent configurations from storage. By default, it returns executable `Agent` instances, but can also return raw storage data.
+
+## Usage example
+
+```typescript
+// Get Agent instances from storage
+const { agents, total, hasMore } = await mastra.listStoredAgents()
+
+for (const agent of agents) {
+  console.log(agent.id, agent.name)
+  // Each agent is ready to use
+  // const response = await agent.generate("Hello");
+}
+```
+
+```typescript
+// Get paginated results with raw storage data
+const result = await mastra.listStoredAgents({
+  page: 0,
+  perPage: 10,
+  raw: true,
+})
+
+console.log(`Showing ${result.agents.length} of ${result.total} agents`)
+console.log(`Has more: ${result.hasMore}`)
+
+for (const config of result.agents) {
+  console.log(config.id, config.name, config.createdAt)
+}
+```
+
+## Parameters
+
+**args?:** (`object`): Optional configuration object for pagination and output format.
+
+### Args Options
+
+**page?:** (`number`): Zero-indexed page number for pagination. (Default: `0`)
+
+**perPage?:** (`number | false`): Number of items per page. Set to \`false\` to fetch all records without pagination. (Default: `100`)
+
+**raw?:** (`boolean`): When \`true\`, returns raw \`StorageAgentType\` objects instead of \`Agent\` instances. (Default: `false`)
+
+## Returns
+
+**agents:** (`Agent[] | StorageAgentType[]`): Array of \`Agent\` instances by default, or \`StorageAgentType\` objects when \`raw: true\`.
+
+**total:** (`number`): Total number of stored agents across all pages.
+
+**page:** (`number`): Current page number (zero-indexed).
+
+**perPage:** (`number | false`): Number of items per page, or \`false\` if fetching all.
+
+**hasMore:** (`boolean`): Whether there are more pages available.
+
+## Primitive Resolution
+
+When creating `Agent` instances (default behavior), each stored agent's configuration is resolved against registered primitives:
+
+- **Tools**: Resolved from `tools` registered in Mastra config
+- **Workflows**: Resolved from `workflows` registered in Mastra config
+- **Subagents**: Resolved from `agents` registered in Mastra config
+- **Memory**: Resolved from `memory` registered in Mastra config
+- **Scorers**: Resolved from `scorers` registered in Mastra config
+
+If a referenced primitive is not found, a warning is logged but the agent is still created.
+
+## Example: Iterating Through All Stored Agents
+
+```typescript
+async function getAllStoredAgents(mastra: Mastra) {
+  const allAgents: Agent[] = []
+  let page = 0
+  let hasMore = true
+
+  while (hasMore) {
+    const result = await mastra.listStoredAgents({ page, perPage: 50 })
+    allAgents.push(...result.agents)
+    hasMore = result.hasMore
+    page++
+  }
+
+  return allAgents
+}
+```
+
+## Related
+
+- [Mastra.getStoredAgentById()](https://mastra.ai/reference/core/getStoredAgentById)
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Agents overview](https://mastra.ai/docs/agents/overview)

package/dist/docs/references/reference-core-listVectors.md

@@ -0,0 +1,22 @@
+# Mastra.listVectors()
+
+The `.listVectors()` method is used to retrieve all vector stores that have been configured in the Mastra instance.
+
+## Usage example
+
+```typescript
+mastra.listVectors()
+```
+
+## Parameters
+
+This method does not accept any parameters.
+
+## Returns
+
+**vectors:** (`TVectors`): A record of all configured vector stores, where keys are vector store names and values are vector store instances.
+
+## Related
+
+- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
+- [RAG overview](https://mastra.ai/docs/rag/overview)

package/dist/docs/references/reference-core-listWorkflows.md

@@ -0,0 +1,21 @@
+# Mastra.listWorkflows()
+
+The `.listWorkflows()` method is used to retrieve all workflows that have been configured in the Mastra instance. The method accepts an optional options object.
+
+## Usage example
+
+```typescript
+mastra.listWorkflows()
+```
+
+## Parameters
+
+**options:** (`{ serialized?: boolean }`): Optional configuration object. When \`serialized\` is true, returns simplified workflow objects with only the name property instead of full workflow instances.
+
+## Returns
+
+**workflows:** (`Record<string, Workflow>`): A record of all configured workflows, where keys are workflow IDs and values are workflow instances (or simplified objects if serialized is true).
+
+## Related
+
+- [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/dist/docs/references/reference-core-mastra-class.md

@@ -0,0 +1,66 @@
+# Mastra Class
+
+The `Mastra` class is the central orchestrator in any Mastra application, managing agents, workflows, storage, logging, observability, and more. Typically, you create a single instance of `Mastra` to coordinate your application.
+
+Think of `Mastra` as a top-level registry where you register agents, workflows, tools, and other components that need to be accessible throughout your application.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PinoLogger } from '@mastra/loggers'
+import { LibSQLStore } from '@mastra/libsql'
+import { weatherWorkflow } from './workflows/weather-workflow'
+import { weatherAgent } from './agents/weather-agent'
+
+export const mastra = new Mastra({
+  workflows: { weatherWorkflow },
+  agents: { weatherAgent },
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: ':memory:',
+  }),
+  logger: new PinoLogger({
+    name: 'Mastra',
+    level: 'info',
+  }),
+})
+```
+
+## Constructor parameters
+
+Visit the [Configuration reference](https://mastra.ai/reference/configuration) for detailed documentation on all available configuration options.
+
+**agents?:** (`Record<string, Agent>`): Agent instances to register, keyed by name (Default: `{}`)
+
+**tools?:** (`Record<string, ToolApi>`): Custom tools to register. Structured as a key-value pair, with keys being the tool name and values being the tool function. (Default: `{}`)
+
+**storage?:** (`MastraCompositeStore`): Storage engine instance for persisting data
+
+**vectors?:** (`Record<string, MastraVector>`): Vector store instance, used for semantic search and vector-based tools (eg Pinecone, PgVector or Qdrant)
+
+**logger?:** (`Logger`): Logger instance created with new PinoLogger() (Default: `Console logger with INFO level`)
+
+**idGenerator?:** (`() => string`): Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers.
+
+**workflows?:** (`Record<string, Workflow>`): Workflows to register. Structured as a key-value pair, with keys being the workflow name and values being the workflow instance. (Default: `{}`)
+
+**tts?:** (`Record<string, MastraVoice>`): Text-to-speech providers for voice synthesis
+
+**observability?:** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
+
+**deployer?:** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
+
+**server?:** (`ServerConfig`): Server configuration including port, host, timeout, API routes, middleware, CORS settings, and build options for Swagger UI, API request logging, and OpenAPI docs.
+
+**mcpServers?:** (`Record<string, MCPServerBase>`): An object where keys are registry keys (used for getMCPServer()) and values are instances of MCPServer or classes extending MCPServerBase. Each MCPServer must have an id property. Servers can be retrieved by registry key using getMCPServer() or by their intrinsic id using getMCPServerById().
+
+**bundler?:** (`BundlerConfig`): Configuration for the asset bundler with options for externals, sourcemap, and transpilePackages.
+
+**scorers?:** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs (Default: `{}`)
+
+**processors?:** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
+
+**gateways?:** (`Record<string, MastraModelGateway>`): Custom model gateways to register for accessing AI models through alternative providers or private deployments. Structured as a key-value pair, with keys being the registry key (used for getGateway()) and values being gateway instances. (Default: `{}`)
+
+**memory?:** (`Record<string, MastraMemory>`): Memory instances to register. These can be referenced by stored agents and resolved at runtime. Structured as a key-value pair, with keys being the registry key and values being memory instances. (Default: `{}`)

package/dist/docs/references/reference-core-mastra-model-gateway.md

@@ -0,0 +1,153 @@
+# MastraModelGateway
+
+Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
+
+## Class Overview
+
+```typescript
+import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm'
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5'
+import type { LanguageModelV2 } from '@ai-sdk/provider-v5'
+
+class MyCustomGateway extends MastraModelGateway {
+  readonly id = 'custom'
+  readonly name = 'My Custom Gateway'
+
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['model-1', 'model-2'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: this.id,
+      },
+    }
+  }
+
+  buildUrl(modelId: string, envVars?: Record<string, string>): string {
+    return 'https://api.my-provider.com/v1'
+  }
+
+  async getApiKey(modelId: string): Promise<string> {
+    const apiKey = process.env.MY_API_KEY
+    if (!apiKey) throw new Error('MY_API_KEY not set')
+    return apiKey
+  }
+
+  async resolveLanguageModel({
+    modelId,
+    providerId,
+    apiKey,
+  }: {
+    modelId: string
+    providerId: string
+    apiKey: string
+  }): Promise<LanguageModelV2> {
+    const baseURL = this.buildUrl(`${providerId}/${modelId}`)
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL,
+    }).chatModel(modelId)
+  }
+}
+```
+
+## Required Properties
+
+**id:** (`string`): Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn't use a prefix.
+
+**name:** (`string`): Human-readable name for the gateway.
+
+## Required Methods
+
+### fetchProviders()
+
+Fetches provider configurations from the gateway.
+
+**Returns:** `Promise<Record<string, ProviderConfig>>`
+
+**ProviderConfig Structure:**
+
+**name:** (`string`): Display name of the provider
+
+**models:** (`string[]`): Array of available model IDs
+
+**apiKeyEnvVar:** (`string | string[]`): Environment variable(s) for API key
+
+**gateway:** (`string`): Gateway identifier
+
+**url?:** (`string`): Optional base API URL
+
+**apiKeyHeader?:** (`string`): Optional custom auth header name
+
+**docUrl?:** (`string`): Optional documentation URL
+
+### buildUrl()
+
+Builds the API URL for a specific model/provider combination.
+
+**Parameters:**
+
+**modelId:** (`string`): Full model ID (e.g., "custom/my-provider/model-1")
+
+**envVars?:** (`Record<string, string>`): Optional environment variables
+
+**Returns:** `string | undefined | Promise<string | undefined>`
+
+### getApiKey()
+
+Retrieves the API key for authentication.
+
+**Parameters:**
+
+**modelId:** (`string`): Full model ID
+
+**Returns:** `Promise<string>`
+
+### resolveLanguageModel()
+
+Creates a language model instance.
+
+**Parameters:**
+
+**modelId:** (`string`): The model ID
+
+**providerId:** (`string`): The provider ID
+
+**apiKey:** (`string`): The API key for authentication
+
+**Returns:** `Promise<LanguageModelV2> | LanguageModelV2`
+
+## Instance Methods
+
+### getId()
+
+Returns the gateway's unique identifier.
+
+**Returns:** `string` - The gateway's `id` property
+
+## Model ID Format
+
+For true gateways, the gateway ID is used as a prefix and models are accessed using this format:
+
+```text
+[gateway-id]/[provider]/[model]
+```
+
+Examples:
+
+- Gateway with `id = 'custom'`: `'custom/my-provider/model-1'`
+
+## Built-in Implementations
+
+- **NetlifyGateway** - Netlify AI Gateway integration
+- **ModelsDevGateway** - Registry of OpenAI-compatible providers
+
+## Related
+
+- [Custom Gateways Guide](https://mastra.ai/models/gateways/custom-gateways) - Complete guide to creating custom gateways
+- [Mastra.addGateway()](https://mastra.ai/reference/core/addGateway) - Add a gateway to Mastra
+- [Mastra.getGateway()](https://mastra.ai/reference/core/getGateway) - Get gateway by registration key
+- [Mastra.getGatewayById()](https://mastra.ai/reference/core/getGatewayById) - Get gateway by ID
+- [Mastra.listGateways()](https://mastra.ai/reference/core/listGateways) - List all gateways