@mastra/core 1.2.0 → 1.2.1-alpha.0

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

@@ -0,0 +1,51 @@
+# 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
+- **Sub-agents**: 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

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

@@ -0,0 +1,26 @@
+# Mastra.setLogger()
+
+The `.setLogger()` method is used to set the logger for all components (agents, workflows, etc.) in the Mastra instance. This method accepts a single object parameter with a logger property.
+
+## Usage example
+
+```typescript
+mastra.setLogger({ logger: new PinoLogger({ name: "testLogger" }) });
+```
+
+## Parameters
+
+**options:** (`{ logger: TLogger }`): An object containing the logger instance to set for all components.
+
+### Options
+
+**logger:** (`TLogger`): The logger instance to set for all components (agents, workflows, etc.).
+
+## Returns
+
+This method does not return a value.
+
+## Related
+
+- [Logging overview](https://mastra.ai/docs/observability/logging)
+- [Logger reference](https://mastra.ai/reference/logging/pino-logger)

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

@@ -0,0 +1,27 @@
+# Mastra.setStorage()
+
+The `.setStorage()` method is used to set the storage instance for the Mastra instance. This method accepts a single `MastraCompositeStore` parameter.
+
+## Usage example
+
+```typescript
+mastra.setStorage(
+  new LibSQLStore({
+    id: 'mastra-storage',
+    url: ":memory:",
+  }),
+);
+```
+
+## Parameters
+
+**storage:** (`MastraCompositeStore`): The storage instance to set for the Mastra instance.
+
+## Returns
+
+This method does not return a value.
+
+## Related
+
+- [Storage overview](https://mastra.ai/reference/storage/overview)
+- [Storage reference](https://mastra.ai/reference/storage/libsql)

package/dist/docs/references/reference-deployer-cloudflare.md

@@ -0,0 +1,56 @@
+# CloudflareDeployer
+
+The `CloudflareDeployer` class handles deployment of standalone Mastra applications to Cloudflare Workers. It manages configuration, deployment, and extends the base [Deployer](https://mastra.ai/reference/deployer) class with Cloudflare specific functionality.
+
+## Usage example
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: "hello-mastra",
+    routes: [
+      {
+        pattern: "example.com/*",
+        zone_name: "example.com",
+        custom_domain: true
+      }
+    ],
+    vars: {
+      NODE_ENV: "production",
+      API_KEY: "<api-key>"
+    },
+    d1_databases: [
+      {
+        binding: "DB",
+        database_name: "my-database",
+        database_id: "d1-database-id",
+        preview_database_id: "your-preview-database-id"
+      }
+    ],
+    kv_namespaces: [
+      {
+        binding: "CACHE",
+        id: "kv-namespace-id"
+      }
+    ]
+  })
+});
+```
+
+## Constructor options
+
+The `CloudflareDeployer` constructor accepts the same configuration options as `wrangler.json`. See the [Wrangler configuration documentation](https://developers.cloudflare.com/workers/wrangler/configuration/) for all available options.
+
+### Migrating from earlier versions
+
+The following fields are deprecated and should be replaced with their standard `wrangler.json` equivalents:
+
+| Deprecated        | Use instead                 |
+| ----------------- | --------------------------- |
+| `projectName`     | `name`                      |
+| `d1Databases`     | `d1_databases`              |
+| `kvNamespaces`    | `kv_namespaces`             |
+| `workerNamespace` | _(removed, no longer used)_ |

package/dist/docs/references/reference-deployer-netlify.md

@@ -0,0 +1,14 @@
+# NetlifyDeployer
+
+The `NetlifyDeployer` class handles deployment of standalone Mastra applications to Netlify. It manages configuration, deployment, and extends the base [Deployer](https://mastra.ai/reference/deployer) class with Netlify specific functionality.
+
+## Usage example
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { NetlifyDeployer } from "@mastra/deployer-netlify";
+
+export const mastra = new Mastra({
+  deployer: new NetlifyDeployer(),
+});
+```

package/dist/docs/references/reference-deployer-vercel.md

@@ -0,0 +1,39 @@
+# VercelDeployer
+
+The `VercelDeployer` class handles deployment of standalone Mastra applications to Vercel. It manages configuration, deployment, and extends the base [Deployer](https://mastra.ai/reference/deployer) class with Vercel specific functionality.
+
+## Usage example
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { VercelDeployer } from "@mastra/deployer-vercel";
+
+export const mastra = new Mastra({
+  deployer: new VercelDeployer(),
+});
+```
+
+## Constructor options
+
+The deployer supports a small set of high‑value overrides that are written to the Vercel Output API function config (`.vc-config.json`):
+
+- `maxDuration?: number` — Function execution timeout (in seconds)
+- `memory?: number` — Function memory (in MB)
+- `regions?: string[]` — Regions to deploy the function (e.g. `['sfo1','iad1']`)
+
+These options are merged into `.vercel/output/functions/index.func/.vc-config.json` while preserving default fields (`handler`, `launcherType`, `runtime`, `shouldAddHelpers`).
+
+### Example with overrides
+
+```typescript
+import { Mastra } from "@mastra/core";
+import { VercelDeployer } from "@mastra/deployer-vercel";
+
+export const mastra = new Mastra({
+  deployer: new VercelDeployer({
+    maxDuration: 600,
+    memory: 1536,
+    regions: ["sfo1", "iad1"],
+  }),
+});
+```