@mastra/core 1.2.0 → 1.2.1-alpha.0

package/dist/docs/{configuration.mdx/01-reference.md → references/reference-configuration.md}

@@ -1,17 +1,8 @@
-# Configuration.mdx API Reference
-
-> API reference for configuration.mdx - 1 entries
-
-
----
-
-## Reference: Configuration
-
-> Reference documentation on Mastra
+# Configuration
 
 The following reference covers all supported options in Mastra. You initialize and configure Mastra by instantiating the [`Mastra` class](https://mastra.ai/reference/core/mastra-class).
 
-```ts title="src/mastra/index.ts"
+```ts
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -29,7 +20,7 @@ A record of agent instances keyed by their names. Agents are autonomous systems
 
 Visit the [Agents documentation](https://mastra.ai/docs/agents/overview) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { Agent } from "@mastra/core/agent";
 
@@ -53,7 +44,7 @@ Deployment provider for publishing applications to cloud platforms.
 
 Visit the [Deployment documentation](https://mastra.ai/docs/deployment/overview) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
@@ -71,10 +62,9 @@ export const mastra = new Mastra({
 
 Event handlers for the internal pub/sub system. Maps event topics to handler functions that are called when events are published to those topics.
 
-> **Note:**
-This is used internally by Mastra's workflow engine. Most users will not need to configure this option.
+> **Warning:** This is used internally by Mastra's workflow engine. Most users will not need to configure this option.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -94,7 +84,7 @@ Custom model router gateways for accessing LLM providers. Gateways handle provid
 
 Visit the [Custom Gateways documentation](https://mastra.ai/models/gateways/custom-gateways) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MyPrivateGateway } from "./gateways";
 
@@ -107,16 +97,14 @@ export const mastra = new Mastra({
 
 ### idGenerator
 
-**Type:** `() => string`  
+**Type:** `() => string`\
 **Default:** `crypto.randomUUID()`
 
 Custom ID generator function for creating unique identifiers.
 
-> **Note:**
-
-This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users will not need to configure this option.
+> **Warning:** This is used internally by Mastra for creating IDs for workflow runs, agent conversations, and other resources. Most users will not need to configure this option.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { nanoid } from "nanoid";
 
@@ -127,14 +115,14 @@ export const mastra = new Mastra({
 
 ### logger
 
-**Type:** `IMastraLogger | false`  
+**Type:** `IMastraLogger | false`\
 **Default:** `ConsoleLogger` with `INFO` level in development, `WARN` in production
 
 Logger implementation for application logging and debugging. Set to `false` to disable logging entirely.
 
 Visit the [Logging documentation](https://mastra.ai/docs/observability/logging) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { PinoLogger } from "@mastra/loggers";
 
@@ -151,7 +139,7 @@ MCP (Model Context Protocol) servers that expose Mastra tools, agents, workflows
 
 Visit the [MCP Overview](https://mastra.ai/docs/mcp/overview) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MCPServer } from "@mastra/mcp";
 
@@ -176,11 +164,9 @@ A registry of memory instances that can be referenced by agents. Memory gives ag
 
 Visit the [Memory documentation](https://mastra.ai/docs/memory/overview) to learn more.
 
-> **Note:**
+> **Note:** Most users configure memory directly on agents. This top-level configuration is for defining reusable memory instances that can be shared across multiple agents.
 
-Most users configure memory directly on agents. This top-level configuration is for defining reusable memory instances that can be shared across multiple agents.
-
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -208,7 +194,7 @@ Mastra provides observability features for AI applications. Monitor LLM operatio
 
 Visit the [Observability documentation](https://mastra.ai/docs/observability/overview) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 import { Observability, DefaultExporter } from "@mastra/observability";
@@ -237,11 +223,9 @@ Input/output processors for transforming agent inputs and outputs. Processors ru
 
 Visit the [Processors documentation](https://mastra.ai/docs/agents/processors) to learn more.
 
-> **Note:**
-
-Most users configure processors directly on agents. This top-level configuration is for defining reusable processor instances that can be shared across multiple agents.
+> **Note:** Most users configure processors directly on agents. This top-level configuration is for defining reusable processor instances that can be shared across multiple agents.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { ModerationProcessor } from "@mastra/core/processors";
 
@@ -257,15 +241,14 @@ export const mastra = new Mastra({
 
 ### pubsub
 
-**Type:** `PubSub`  
+**Type:** `PubSub`\
 **Default:** `EventEmitterPubSub`
 
 Pub/sub system for event-driven communication between components. Used internally by Mastra for workflow event processing and component communication.
 
-> **Note:**
-This is used internally by Mastra. Most users will not need to configure this option.
+> **Warning:** This is used internally by Mastra. Most users will not need to configure this option.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { CustomPubSub } from "./pubsub";
 
@@ -282,11 +265,9 @@ Scorers assess the quality of agent responses and workflow outputs. They provide
 
 Visit the [Scorers documentation](https://mastra.ai/docs/evals/overview) to learn more.
 
-> **Note:**
-
-Most users configure scorers directly on agents. This top-level configuration is for defining reusable scorer instances that can be shared across multiple agents.
+> **Note:** Most users configure scorers directly on agents. This top-level configuration is for defining reusable scorer instances that can be shared across multiple agents.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { createToxicityScorer } from "@mastra/evals/scorers/prebuilt";
 
@@ -305,7 +286,7 @@ Storage provider for persisting application data. Used by memory, workflows, tra
 
 Visit the [Storage documentation](https://mastra.ai/docs/memory/storage) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
@@ -325,10 +306,9 @@ Tools are reusable functions that agents can use to interact with external syste
 
 Visit the [Tools documentation](https://mastra.ai/docs/tools-mcp/overview) to learn more.
 
-> **Note:**
-Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.
+> **Note:** Most users configure tools directly on agents. This top-level configuration is for defining reusable tools that can be shared across multiple agents.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
@@ -359,10 +339,9 @@ Text-to-speech providers for voice synthesis capabilities. Register voice provid
 
 Visit the [Voice documentation](https://mastra.ai/docs/voice/overview) to learn more.
 
-> **Note:**
-Most users configure voice directly on agents. This top-level configuration is for defining reusable voice providers that can be shared across multiple agents.
+> **Note:** Most users configure voice directly on agents. This top-level configuration is for defining reusable voice providers that can be shared across multiple agents.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { OpenAIVoice } from "@mastra/voice-openai";
 
@@ -381,10 +360,9 @@ Vector stores for semantic search and embeddings. Used in RAG pipelines, similar
 
 Visit the [RAG documentation](https://mastra.ai/docs/rag/overview) to learn more.
 
-> **Note:**
-Most users create vector stores directly when building RAG pipelines. This top-level configuration is for defining reusable vector store instances that can be shared across your application.
+> **Note:** Most users create vector stores directly when building RAG pipelines. This top-level configuration is for defining reusable vector store instances that can be shared across your application.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { PineconeVector } from "@mastra/pinecone";
 
@@ -406,7 +384,7 @@ Workflows define step-based execution pipelines with type-safe inputs and output
 
 Visit the [Workflows documentation](https://mastra.ai/docs/workflows/overview) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { testWorkflow } from "./workflows/test-workflow";
 
@@ -424,7 +402,8 @@ export const mastra = new Mastra({
 A Mastra workspace gives agents a persistent environment for storing files and executing commands. Agents inherit the global workspace on the `Mastra` class unless they have their own workspace configured.
 
 See the [Workspace documentation](https://mastra.ai/docs/workspace/overview) for implementation details.
-```typescript title="src/mastra/index.ts"
+
+```typescript
 import { Mastra } from '@mastra/core';
 import { Workspace, LocalFilesystem } from '@mastra/core/workspace';
 
@@ -441,7 +420,7 @@ const mastra = new Mastra({
 
 ### bundler.externals
 
-**Type:** `boolean | string[]`  
+**Type:** `boolean | string[]`\
 **Default:** `true`
 
 When `mastra build` is run, Mastra bundles your project into the `.mastra/output` directory. This option controls which packages are excluded from the bundle (marked as "external") and installed separately through a package manager. This is useful when the internal Mastra bundler ([Rollup](https://rollupjs.org/configuration-options/#external)) has trouble bundling certain packages.
@@ -454,7 +433,7 @@ Here's an overview of what the different values mean:
 - `false`: No dependencies are marked as external; everything is bundled together
 - `string[]`: An array of package names to mark as external, the rest will be bundled together
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -466,12 +445,12 @@ export const mastra = new Mastra({
 
 ### bundler.sourcemap
 
-**Type:** `boolean`  
+**Type:** `boolean`\
 **Default:** `false`
 
 Enables source map generation for the bundled output.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -483,7 +462,7 @@ export const mastra = new Mastra({
 
 ### bundler.transpilePackages
 
-**Type:** `string[]`  
+**Type:** `string[]`\
 **Default:** `[]`
 
 List of packages whose source code should be transpiled through esbuild during the build process. Use this for dependencies that contain TypeScript or other code that needs compilation before bundling.
@@ -492,7 +471,7 @@ You only need this option if you're importing uncompiled source code directly. I
 
 Mastra automatically detects workspace packages in monorepo setups and adds them to this list, so you typically only need to specify external packages that require transpilation.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -512,7 +491,7 @@ Mastra automatically exposes registered agents and workflows via its server. For
 
 Visit the [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) documentation to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { registerApiRoute } from "@mastra/core/server";
 
@@ -538,7 +517,7 @@ Authentication configuration for the server. Mastra supports multiple authentica
 
 Visit the [Authentication documentation](https://mastra.ai/docs/server/auth) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import { MastraJwtAuth } from "@mastra/auth";
 
@@ -553,12 +532,12 @@ export const mastra = new Mastra({
 
 ### server.bodySizeLimit
 
-**Type:** `number`  
+**Type:** `number`\
 **Default:** `4_718_592` (4.5 MB)
 
 Maximum request body size in bytes. Increase this limit if your application needs to handle larger payloads.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -572,13 +551,13 @@ export const mastra = new Mastra({
 
 Build-time configuration for server features. These options control development tools like Swagger UI and request logging, which are enabled during local development but disabled in production by default.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `swaggerUI` | `boolean` | `false` | Enable Swagger UI at `/swagger-ui` for interactive API exploration (requires `openAPIDocs` to be `true`) |
-| `apiReqLogs` | `boolean` | `false` | Enable API request logging to the console |
-| `openAPIDocs` | `boolean` | `false` | Enable OpenAPI specification at `/openapi.json` |
+| Property      | Type      | Default | Description                                                                                              |
+| ------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `swaggerUI`   | `boolean` | `false` | Enable Swagger UI at `/swagger-ui` for interactive API exploration (requires `openAPIDocs` to be `true`) |
+| `apiReqLogs`  | `boolean` | `false` | Enable API request logging to the console                                                                |
+| `openAPIDocs` | `boolean` | `false` | Enable OpenAPI specification at `/openapi.json`                                                          |
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -594,20 +573,20 @@ export const mastra = new Mastra({
 
 ### server.cors
 
-**Type:** `CorsOptions | false`  
+**Type:** `CorsOptions | false`
 
 CORS (Cross-Origin Resource Sharing) configuration for the server. Set to `false` to disable CORS entirely.
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `origin` | `string \| string[]` | `'*'` | Origins for CORS requests |
-| `allowMethods` | `string[]` | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']` | HTTP methods |
-| `allowHeaders` | `string[]` | `['Content-Type', 'Authorization', 'x-mastra-client-type']` | Request headers |
-| `exposeHeaders` | `string[]` | `['Content-Length', 'X-Requested-With']` | Browser headers |
-| `credentials` | `boolean` | `false` | Credentials (cookies, authorization headers) |
-| `maxAge` | `number` | `3600` | Preflight request cache duration in seconds |
+| Property        | Type                 | Default                                                     | Description                                  |
+| --------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
+| `origin`        | `string \| string[]` | `'*'`                                                       | Origins for CORS requests                    |
+| `allowMethods`  | `string[]`           | `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']`      | HTTP methods                                 |
+| `allowHeaders`  | `string[]`           | `['Content-Type', 'Authorization', 'x-mastra-client-type']` | Request headers                              |
+| `exposeHeaders` | `string[]`           | `['Content-Length', 'X-Requested-With']`                    | Browser headers                              |
+| `credentials`   | `boolean`            | `false`                                                     | Credentials (cookies, authorization headers) |
+| `maxAge`        | `number`             | `3600`                                                      | Preflight request cache duration in seconds  |
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -624,12 +603,12 @@ export const mastra = new Mastra({
 
 ### server.host
 
-**Type:** `string`  
+**Type:** `string`\
 **Default:** `localhost`
 
 Host address the Mastra development server binds to.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -645,7 +624,7 @@ export const mastra = new Mastra({
 
 HTTPS configuration for running the development server with TLS. Mastra supports local HTTPS development through the `mastra dev --https` flag, which automatically creates and manages certificates. For custom certificate management, provide your own key and certificate files:
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import fs from "node:fs";
 
@@ -667,7 +646,7 @@ Custom middleware functions to intercept requests before or after route handlers
 
 Visit the [Middleware documentation](https://mastra.ai/docs/server/middleware) to learn more.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -694,7 +673,7 @@ export const mastra = new Mastra({
 
 Custom error handler called when an unhandled error occurs. Use this to customize error responses, log errors to external services like Sentry, or implement custom error formatting.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 import * as Sentry from "@sentry/node";
 
@@ -714,12 +693,12 @@ export const mastra = new Mastra({
 
 ### server.port
 
-**Type:** `number`  
+**Type:** `number`\
 **Default:** `4111` (or `PORT` environment variable if set)
 
 Port the Mastra development server binds to. If the `PORT` environment variable is set, it takes precedence over the default.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -731,14 +710,14 @@ export const mastra = new Mastra({
 
 ### server.studioBase
 
-**Type:** `string`  
+**Type:** `string`\
 **Default:** `/`
 
 Base path for hosting Mastra Studio. Use this to host the Studio on a sub-path of your existing application instead of the root.
 
 This is useful when integrating with existing applications, using authentication tools like Cloudflare Zero Trust that benefit from shared domains, or managing multiple services under a single domain.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
@@ -749,17 +728,18 @@ export const mastra = new Mastra({
 ```
 
 **Example URLs:**
+
 - Default: `http://localhost:4111/` (studio at root)
 - With `studioBase`: `http://localhost:4111/my-mastra-studio/` (studio at sub-path)
 
 ### server.timeout
 
-**Type:** `number`  
+**Type:** `number`\
 **Default:** `180000` (3 minutes)
 
 Request timeout in milliseconds. Requests that exceed this duration will be terminated.
 
-```typescript title="src/mastra/index.ts"
+```typescript
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({

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