@mastra/core 1.7.0 → 1.8.0

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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,21 @@
+# 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

@@ -0,0 +1,21 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,41 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,55 @@
+# 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

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,89 @@
+# 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

@@ -0,0 +1,22 @@
+# 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

@@ -0,0 +1,22 @@
+# 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)