@mastra/core 1.6.0 → 1.7.0-alpha.0

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

@@ -1,42 +0,0 @@
-# Mastra.addGateway()
-
-Dynamically adds a gateway to the Mastra instance. Can be used during or after initialization.
-
-## Usage example
-
-```typescript
-import { Mastra } from '@mastra/core';
-
-const mastra = new Mastra();
-
-// Add with explicit key
-mastra.addGateway(new MyCustomGateway(), 'myGateway');
-
-// Add using gateway's ID as the key
-mastra.addGateway(new MyCustomGateway());
-// Stored with key 'my-custom-gateway' (the gateway's id)
-```
-
-## Parameters
-
-**gateway:** (`MastraModelGateway`): The gateway instance to add
-
-**key?:** (`string`): Optional registration key. If not provided, uses gateway.getId()
-
-## Returns
-
-Void. The gateway is added to the internal registry.
-
-## Behavior
-
-- If a gateway with the same key already exists, the addition is skipped
-- In development mode (`MASTRA_DEV=true`), automatically triggers type generation for custom gateways
-- The gateway becomes available immediately for model resolution
-
-## 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.listGateways()](https://mastra.ai/reference/core/listGateways) - List all gateways
-- [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-getAgent.md

@@ -1,21 +0,0 @@
-# Mastra.getAgent()
-
-The `.getAgent()` method is used to retrieve an agent. The method accepts a single `string` parameter for the agent's name.
-
-## Usage example
-
-```typescript
-mastra.getAgent("testAgent");
-```
-
-## Parameters
-
-**name:** (`TAgentName extends keyof TAgents`): The name of the agent to retrieve. Must be a valid agent name that exists in the Mastra configuration.
-
-## Returns
-
-**agent:** (`TAgents[TAgentName]`): The agent instance with the specified name. Throws an error if the agent is not found.
-
-## Related
-
-- [Agents overview](https://mastra.ai/docs/agents/overview)

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

@@ -1,21 +0,0 @@
-# Mastra.getAgentById()
-
-The `.getAgentById()` method is used to retrieve an agent by its ID. The method accepts a single `string` parameter for the agent's ID.
-
-## Usage example
-
-```typescript
-mastra.getAgentById("test-agent-123");
-```
-
-## Parameters
-
-**id:** (`string`): The ID of the agent to retrieve. The method will first search for an agent with this ID, and if not found, will attempt to use it as a name to call getAgent().
-
-## Returns
-
-**agent:** (`Agent`): The agent instance with the specified ID. Throws an error if the agent is not found.
-
-## Related
-
-- [Agents overview](https://mastra.ai/docs/agents/overview)

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

@@ -1,22 +0,0 @@
-# Mastra.getDeployer()
-
-The `.getDeployer()` method is used to retrieve the deployer instance that has been configured in the Mastra instance.
-
-## Usage example
-
-```typescript
-mastra.getDeployer();
-```
-
-## Parameters
-
-This method does not accept any parameters.
-
-## Returns
-
-**deployer:** (`MastraDeployer | undefined`): The configured deployer instance, or undefined if no deployer has been configured.
-
-## Related
-
-- [Deployment overview](https://mastra.ai/docs/deployment/overview)
-- [Deployer reference](https://mastra.ai/reference/deployer)

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

@@ -1,38 +0,0 @@
-# Mastra.getGateway()
-
-Retrieves a gateway by its registration key (the key used when adding the gateway to Mastra).
-
-## Usage example
-
-```typescript
-import { Mastra } from '@mastra/core';
-
-const mastra = new Mastra({
-  gateways: {
-    myGateway: new MyCustomGateway(),
-  },
-});
-
-const gateway = mastra.getGateway('myGateway');
-console.log(gateway.name); // 'My Custom Gateway'
-```
-
-## Parameters
-
-**key:** (`string`): The registration key of the gateway
-
-## Returns
-
-**gateway:** (`MastraModelGateway`): The gateway instance
-
-## Throws
-
-Throws an error if no gateway is found with the specified key.
-
-## Related
-
-- [Mastra.getGatewayById()](https://mastra.ai/reference/core/getGatewayById) - Get gateway by ID
-- [Mastra.listGateways()](https://mastra.ai/reference/core/listGateways) - List all gateways
-- [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-getGatewayById.md

@@ -1,41 +0,0 @@
-# Mastra.getGatewayById()
-
-Retrieves a gateway by its unique ID (the `id` property of the gateway instance). This is useful when you need to find a gateway by its intrinsic identifier rather than its registration key.
-
-## Usage example
-
-```typescript
-import { Mastra } from '@mastra/core';
-
-const mastra = new Mastra({
-  gateways: {
-    customKey: new MyCustomGateway(), // id = 'my-custom-gateway'
-  },
-});
-
-// Retrieve by ID (not registration key)
-const gateway = mastra.getGatewayById('my-custom-gateway');
-console.log(gateway.name); // 'My Custom Gateway'
-```
-
-## Use Cases
-
-- Gateway versioning: Different versions with unique IDs (`'gateway-v1'`, `'gateway-v2'`)
-- Finding gateways when registration keys are unknown
-- Identifying gateways across different Mastra instances
-
-## Parameters
-
-**id:** (`string`): The unique ID of the gateway (gateway.id property)
-
-## Returns
-
-**gateway:** (`MastraModelGateway | undefined`): The gateway instance, or undefined if not found
-
-## Related
-
-- [Mastra.getGateway()](https://mastra.ai/reference/core/getGateway) - Get gateway by registration key
-- [Mastra.listGateways()](https://mastra.ai/reference/core/listGateways) - List all gateways
-- [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-getLogger.md

@@ -1,22 +0,0 @@
-# Mastra.getLogger()
-
-The `.getLogger()` method is used to retrieve the logger instance that has been configured in the Mastra instance.
-
-## Usage example
-
-```typescript
-mastra.getLogger();
-```
-
-## Parameters
-
-This method does not accept any parameters.
-
-## Returns
-
-**logger:** (`TLogger`): The configured logger instance used for logging across all components (agents, workflows, etc.).
-
-## Related
-
-- [Logging overview](https://mastra.ai/docs/observability/logging)
-- [Logger reference](https://mastra.ai/reference/logging/pino-logger)

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

@@ -1,45 +0,0 @@
-# Mastra.getMCPServer()
-
-The `.getMCPServer()` method retrieves an MCP server instance by its registry key (the key used when registering the server in the `mcpServers` configuration). For retrieving by the server's intrinsic `id` property, use `.getMCPServerById()` instead.
-
-## Usage example
-
-```typescript
-// Register an MCP server with a registry key
-const myServer = new MCPServer({
-  id: 'my-mcp-server',
-  name: 'My Server',
-  version: '1.0.0',
-  tools: { /* ... */ },
-});
-
-export const mastra = new Mastra({
-  mcpServers: {
-    customKey: myServer,  // 'customKey' is the registry key
-  },
-});
-
-// Retrieve by registry key
-const server = mastra.getMCPServer('customKey');
-
-// Alternatively, retrieve by intrinsic ID
-const serverById = mastra.getMCPServerById('my-mcp-server');
-```
-
-## Parameters
-
-**registryKey:** (`string`): The registry key used when registering the MCP server in the mcpServers configuration object. This is the key in the key-value pair, not the server's intrinsic id property.
-
-## Returns
-
-**server:** (`MCPServerBase | undefined`): The MCP server instance with the specified registry key, or undefined if not found.
-
-## Related Methods
-
-- [Mastra.getMCPServerById()](https://mastra.ai/reference/core/getMCPServerById) - Retrieve an MCP server by its intrinsic `id` property
-- [Mastra.listMCPServers()](https://mastra.ai/reference/core/listMCPServers) - List all registered MCP servers
-
-## 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-getMCPServerById.md

@@ -1,53 +0,0 @@
-# Mastra.getMCPServerById()
-
-The `.getMCPServerById()` method retrieves an MCP server instance by its intrinsic `id` property. For retrieving by registry key (the key used in configuration), use `.getMCPServer()` instead.
-
-## Usage example
-
-```typescript
-// Register an MCP server with a registry key
-const myServer = new MCPServer({
-  id: 'my-mcp-server',
-  name: 'My Server',
-  version: '1.0.0',
-  tools: { /* ... */ },
-});
-
-export const mastra = new Mastra({
-  mcpServers: {
-    customKey: myServer,  // 'customKey' is the registry key
-  },
-});
-
-// Retrieve by intrinsic ID
-const server = mastra.getMCPServerById('my-mcp-server');
-
-// Alternatively, retrieve by registry key
-const serverByKey = mastra.getMCPServer('customKey');
-```
-
-## Parameters
-
-**serverId:** (`string`): The intrinsic id property of the MCP server (set when the server was instantiated).
-
-**version?:** (`string`): Optional. If provided, returns the server only if its version matches.
-
-## Returns
-
-**server:** (`MCPServerBase | undefined`): The MCP server instance with the specified id (and version, if provided), or undefined if not found.
-
-## Notes
-
-- The server's `id` is slugified during construction, so `'myMcpServer'` becomes `'my-mcp-server'`
-- If multiple servers have the same `id` but different versions, you must provide the `version` parameter to disambiguate
-- If no `version` is provided and multiple versions exist, the method returns the first match
-
-## Related Methods
-
-- [Mastra.getMCPServer()](https://mastra.ai/reference/core/getMCPServer) - Retrieve an MCP server by its registry key
-- [Mastra.listMCPServers()](https://mastra.ai/reference/core/listMCPServers) - List all registered MCP servers
-
-## 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-getMemory.md

@@ -1,50 +0,0 @@
-# Mastra.getMemory()
-
-The `.getMemory()` method retrieves a memory instance from the Mastra registry by its key. Memory instances are registered in the Mastra constructor and can be referenced by stored agents.
-
-## Usage example
-
-```typescript
-const memory = mastra.getMemory("conversationMemory");
-
-// Use the memory instance
-const thread = await memory.createThread({
-  resourceId: "user-123",
-  title: "New Conversation",
-});
-```
-
-## Parameters
-
-**key:** (`TMemoryKey extends keyof TMemory`): The registry key of the memory instance to retrieve. Must match a key used when registering memory in the Mastra constructor.
-
-## Returns
-
-**memory:** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
-
-## Example: Registering and Retrieving Memory
-
-```typescript
-import { Mastra } from "@mastra/core";
-import { Memory } from "@mastra/memory";
-import { LibSQLStore } from "@mastra/libsql";
-
-const conversationMemory = new Memory({
-  storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
-});
-
-const mastra = new Mastra({
-  memory: {
-    conversationMemory,
-  },
-});
-
-// Later, retrieve the memory instance
-const memory = mastra.getMemory("conversationMemory");
-```
-
-## Related
-
-- [Mastra.listMemory()](https://mastra.ai/reference/core/listMemory)
-- [Memory overview](https://mastra.ai/docs/memory/overview)
-- [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

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

@@ -1,54 +0,0 @@
-# getScorer()
-
-The `getScorer()` method retrieves a specific scorer that was registered with the Mastra instance using its registration key. This method provides type-safe access to scorers and throws an error if the requested scorer is not found.
-
-## Usage Example
-
-```typescript
-import { mastra } from "./mastra";
-
-// Get a specific scorer by key
-const relevancyScorer = mastra.getScorer("relevancyScorer");
-
-const weatherAgent = mastra.getAgent("weatherAgent");
-
-// Use the scorer to evaluate an AI output
-await weatherAgent.generate("What is the weather in Rome", {
-  scorers: {
-    answerRelevancy: {
-      scorer: relevancyScorer,
-    },
-  },
-});
-```
-
-## Parameters
-
-**key:** (`string`): The registration key of the scorer to retrieve. This should match a key used when registering scorers in the Mastra constructor.
-
-## Returns
-
-**scorer:** (`MastraScorer`): The MastraScorer instance associated with the provided key.
-
-## Error Handling
-
-This method throws a `MastraError` if:
-
-- The scorer with the specified key is not found
-- No scorers are registered with the Mastra instance
-
-```typescript
-try {
-  const scorer = mastra.getScorer("nonExistentScorer");
-} catch (error) {
-  if (error.id === "MASTRA_GET_SCORER_NOT_FOUND") {
-    console.log("Scorer not found, using default evaluation");
-  }
-}
-```
-
-## Related
-
-- [listScorers()](https://mastra.ai/reference/core/listScorers) - Get all registered scorers
-- [getScorerById()](https://mastra.ai/reference/core/getScorerById) - Get a scorer by its id property
-- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) - Learn how to create custom scorers

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

@@ -1,54 +0,0 @@
-# getScorerById()
-
-The `getScorerById()` method retrieves a scorer by searching for its `id` property (or `name` property as a fallback) rather than the registration key. This is useful when you know the scorer's id but not necessarily how it was registered in the Mastra instance.
-
-## Usage Example
-
-```typescript
-import { mastra } from "./mastra";
-
-// Get a scorer by its id property
-const relevancyScorer = mastra.getScorerById("answer-relevancy-scorer");
-
-const weatherAgent = mastra.getAgent("weatherAgent");
-
-// Use the scorer to evaluate an AI output
-await weatherAgent.generate("What is the weather in Rome", {
-  scorers: {
-    answerRelevancy: {
-      scorer: relevancyScorer,
-    },
-  },
-});
-```
-
-## Parameters
-
-**id:** (`string`): The id property of the scorer to retrieve. This should match the 'id' field specified when creating the scorer with createScorer(). The method will also search by 'name' property as a fallback.
-
-## Returns
-
-**scorer:** (`MastraScorer`): The MastraScorer instance that has the matching id (or name) property.
-
-## Error Handling
-
-This method throws a `MastraError` if:
-
-- No scorer with the specified id is found
-- No scorers are registered with the Mastra instance
-
-```typescript
-try {
-  const scorer = mastra.getScorerById("non-existent-scorer");
-} catch (error) {
-  if (error.id === "MASTRA_GET_SCORER_BY_ID_NOT_FOUND") {
-    console.log("Scorer with that id not found");
-  }
-}
-```
-
-## Related
-
-- [getScorer()](https://mastra.ai/reference/core/getScorer) - Get a scorer by its registration key
-- [listScorers()](https://mastra.ai/reference/core/listScorers) - Get all registered scorers
-- [createScorer()](https://mastra.ai/reference/evals/create-scorer) - Learn how to create scorers with ids

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

@@ -1,22 +0,0 @@
-# Mastra.getServer()
-
-The `.getServer()` method is used to retrieve the server configuration that has been configured in the Mastra instance.
-
-## Usage example
-
-```typescript
-mastra.getServer();
-```
-
-## Parameters
-
-This method does not accept any parameters.
-
-## Returns
-
-**server:** (`ServerConfig | undefined`): The configured server configuration including port, host, studioBase, timeout, API routes, middleware, CORS settings, and build options, or undefined if no server has been configured.
-
-## Related
-
-- [Server deployment](https://mastra.ai/docs/deployment/mastra-server)
-- [Server configuration](https://mastra.ai/docs/server/custom-api-routes)

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

@@ -1,22 +0,0 @@
-# Mastra.getStorage()
-
-The `.getStorage()` method is used to retrieve the storage instance that has been configured in the Mastra instance.
-
-## Usage example
-
-```typescript
-mastra.getStorage();
-```
-
-## Parameters
-
-This method does not accept any parameters.
-
-## Returns
-
-**storage:** (`MastraCompositeStore | undefined`): The configured storage instance, or undefined if no storage has been configured.
-
-## Related
-
-- [Storage overview](https://mastra.ai/reference/storage/overview)
-- [Storage reference](https://mastra.ai/reference/storage/libsql)

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

@@ -1,89 +0,0 @@
-# Mastra.getStoredAgentById()
-
-The `.getStoredAgentById()` method retrieves an agent configuration from storage by its ID and creates an executable `Agent` instance. Stored agents allow you to persist agent configurations in a database and dynamically load them at runtime.
-
-## Usage example
-
-```typescript
-// Get an Agent instance from storage
-const agent = await mastra.getStoredAgentById("my-stored-agent");
-
-if (agent) {
-  const response = await agent.generate("Hello");
-  console.log(response.text);
-}
-```
-
-```typescript
-// Get the raw storage data instead of an Agent instance
-const storedConfig = await mastra.getStoredAgentById("my-stored-agent", { raw: true });
-
-if (storedConfig) {
-  console.log(storedConfig.instructions);
-  console.log(storedConfig.createdAt);
-}
-```
-
-## Parameters
-
-**id:** (`string`): The unique identifier of the stored agent to retrieve.
-
-**options?:** (`{ raw?: boolean }`): Optional configuration object.
-
-### Options
-
-**raw?:** (`boolean`): When \`true\`, returns the raw \`StorageAgentType\` object from storage instead of creating an \`Agent\` instance. Useful for inspecting stored configuration or metadata. (Default: `false`)
-
-## Returns
-
-**result:** (`Agent | StorageAgentType | null`): Returns an \`Agent\` instance by default, or \`StorageAgentType\` when \`raw: true\`. Returns \`null\` if no agent with the given ID exists.
-
-## Primitive Resolution
-
-When creating an `Agent` instance from stored configuration, the method resolves references to 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, including sampling configuration
-
-If a referenced primitive is not found in the registry, a warning is logged but the agent is still created.
-
-## StorageAgentType
-
-When using `raw: true`, the returned object has the following structure:
-
-**id:** (`string`): Unique identifier for the agent.
-
-**name:** (`string`): Display name of the agent.
-
-**description?:** (`string`): Optional description of the agent.
-
-**instructions:** (`string`): System instructions for the agent.
-
-**model:** (`Record<string, unknown>`): Model configuration with provider and name.
-
-**tools?:** (`Record<string, unknown>`): Tool references to resolve from registry.
-
-**workflows?:** (`Record<string, unknown>`): Workflow references to resolve from registry.
-
-**agents?:** (`Record<string, unknown>`): Subagent references to resolve from registry.
-
-**memory?:** (`Record<string, unknown>`): Memory reference to resolve from registry.
-
-**scorers?:** (`Record<string, unknown>`): Scorer references with optional sampling config.
-
-**defaultOptions?:** (`Record<string, unknown>`): Default options passed to agent execution.
-
-**metadata?:** (`Record<string, unknown>`): Custom metadata stored with the agent.
-
-**createdAt:** (`Date`): Timestamp when the agent was created.
-
-**updatedAt:** (`Date`): Timestamp when the agent was last updated.
-
-## Related
-
-- [Mastra.listStoredAgents()](https://mastra.ai/reference/core/listStoredAgents)
-- [Storage overview](https://mastra.ai/reference/storage/overview)
-- [Agents overview](https://mastra.ai/docs/agents/overview)

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

@@ -1,22 +0,0 @@
-# Mastra.getTelemetry()
-
-The `.getTelemetry()` method is used to retrieve the telemetry instance that has been configured in the Mastra instance.
-
-## Usage example
-
-```typescript
-mastra.getTelemetry();
-```
-
-## Parameters
-
-This method does not accept any parameters.
-
-## Returns
-
-**telemetry:** (`Telemetry | undefined`): The configured telemetry instance used for tracing and observability across all components, or undefined if no telemetry has been configured.
-
-## Related
-
-- [Tracing](https://mastra.ai/docs/observability/tracing/overview)
-- [Observability Configuration](https://mastra.ai/reference/observability/tracing/configuration)

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

@@ -1,22 +0,0 @@
-# Mastra.getVector()
-
-The `.getVector()` method is used to retrieve a vector store by its name. The method accepts a single `string` parameter for the vector store's name.
-
-## Usage example
-
-```typescript
-mastra.getVector("testVectorStore");
-```
-
-## Parameters
-
-**name:** (`TVectorName extends keyof TVectors`): The name of the vector store to retrieve. Must be a valid vector store name that exists in the Mastra configuration.
-
-## Returns
-
-**vector:** (`TVectors[TVectorName]`): The vector store instance with the specified name. Throws an error if the vector store is not found.
-
-## Related
-
-- [Vector stores overview](https://mastra.ai/docs/rag/vector-databases)
-- [RAG overview](https://mastra.ai/docs/rag/overview)