@mastra/libsql 0.0.0-workflow-timeout-issue-20260220185702 → 0.0.0-workflow-graph-crash-20260527191009

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +1085 -3
  2. package/LICENSE.md +15 -0
  3. package/dist/docs/SKILL.md +18 -19
  4. package/dist/docs/assets/SOURCE_MAP.json +1 -1
  5. package/dist/docs/references/docs-agent-builder-deploying.md +121 -0
  6. package/dist/docs/references/docs-agent-builder-overview.md +97 -0
  7. package/dist/docs/references/docs-agents-agent-approval.md +336 -202
  8. package/dist/docs/references/docs-agents-networks.md +107 -215
  9. package/dist/docs/references/docs-memory-memory-processors.md +86 -88
  10. package/dist/docs/references/docs-memory-message-history.md +71 -63
  11. package/dist/docs/references/docs-memory-multi-user-threads.md +206 -0
  12. package/dist/docs/references/docs-memory-overview.md +221 -24
  13. package/dist/docs/references/docs-memory-semantic-recall.md +162 -75
  14. package/dist/docs/references/docs-memory-storage.md +72 -73
  15. package/dist/docs/references/docs-memory-working-memory.md +62 -62
  16. package/dist/docs/references/docs-rag-retrieval.md +132 -135
  17. package/dist/docs/references/docs-workflows-snapshots.md +31 -31
  18. package/dist/docs/references/guides-agent-frameworks-ai-sdk.md +36 -36
  19. package/dist/docs/references/reference-core-getMemory.md +15 -16
  20. package/dist/docs/references/reference-core-listMemory.md +17 -18
  21. package/dist/docs/references/reference-core-mastra-class.md +37 -27
  22. package/dist/docs/references/reference-memory-memory-class.md +41 -43
  23. package/dist/docs/references/reference-storage-composite.md +65 -55
  24. package/dist/docs/references/reference-storage-dynamodb.md +36 -36
  25. package/dist/docs/references/reference-storage-libsql.md +27 -27
  26. package/dist/docs/references/reference-vectors-libsql.md +72 -72
  27. package/dist/index.cjs +7896 -3257
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.js +7888 -3259
  30. package/dist/index.js.map +1 -1
  31. package/dist/storage/db/index.d.ts +14 -1
  32. package/dist/storage/db/index.d.ts.map +1 -1
  33. package/dist/storage/db/utils.d.ts +16 -0
  34. package/dist/storage/db/utils.d.ts.map +1 -1
  35. package/dist/storage/domains/agents/index.d.ts.map +1 -1
  36. package/dist/storage/domains/background-tasks/index.d.ts +18 -0
  37. package/dist/storage/domains/background-tasks/index.d.ts.map +1 -0
  38. package/dist/storage/domains/blobs/index.d.ts +17 -0
  39. package/dist/storage/domains/blobs/index.d.ts.map +1 -0
  40. package/dist/storage/domains/channels/index.d.ts +20 -0
  41. package/dist/storage/domains/channels/index.d.ts.map +1 -0
  42. package/dist/storage/domains/datasets/index.d.ts +43 -0
  43. package/dist/storage/domains/datasets/index.d.ts.map +1 -0
  44. package/dist/storage/domains/experiments/index.d.ts +31 -0
  45. package/dist/storage/domains/experiments/index.d.ts.map +1 -0
  46. package/dist/storage/domains/favorites/index.d.ts +17 -0
  47. package/dist/storage/domains/favorites/index.d.ts.map +1 -0
  48. package/dist/storage/domains/mcp-clients/index.d.ts.map +1 -1
  49. package/dist/storage/domains/mcp-servers/index.d.ts +26 -0
  50. package/dist/storage/domains/mcp-servers/index.d.ts.map +1 -0
  51. package/dist/storage/domains/memory/index.d.ts +7 -3
  52. package/dist/storage/domains/memory/index.d.ts.map +1 -1
  53. package/dist/storage/domains/observability/index.d.ts +2 -1
  54. package/dist/storage/domains/observability/index.d.ts.map +1 -1
  55. package/dist/storage/domains/prompt-blocks/index.d.ts.map +1 -1
  56. package/dist/storage/domains/schedules/index.d.ts +19 -0
  57. package/dist/storage/domains/schedules/index.d.ts.map +1 -0
  58. package/dist/storage/domains/scorer-definitions/index.d.ts.map +1 -1
  59. package/dist/storage/domains/skills/index.d.ts +26 -0
  60. package/dist/storage/domains/skills/index.d.ts.map +1 -0
  61. package/dist/storage/domains/workflows/index.d.ts +1 -0
  62. package/dist/storage/domains/workflows/index.d.ts.map +1 -1
  63. package/dist/storage/domains/workspaces/index.d.ts +26 -0
  64. package/dist/storage/domains/workspaces/index.d.ts.map +1 -0
  65. package/dist/storage/index.d.ts +38 -1
  66. package/dist/storage/index.d.ts.map +1 -1
  67. package/dist/vector/index.d.ts +14 -1
  68. package/dist/vector/index.d.ts.map +1 -1
  69. package/package.json +12 -12
  70. package/dist/docs/references/docs-agents-agent-memory.md +0 -212
  71. package/dist/docs/references/docs-agents-network-approval.md +0 -275
  72. package/dist/docs/references/docs-observability-overview.md +0 -70
  73. package/dist/docs/references/docs-observability-tracing-exporters-default.md +0 -211
@@ -108,15 +108,15 @@ When a workflow is resumed, Mastra retrieves the persisted snapshot with these s
108
108
  5. The suspended step is resumed, and execution continues
109
109
 
110
110
  ```typescript
111
- const storage = mastra.getStorage();
112
- const workflowStore = await storage?.getStore('workflows');
111
+ const storage = mastra.getStorage()
112
+ const workflowStore = await storage?.getStore('workflows')
113
113
 
114
114
  const snapshot = await workflowStore?.loadWorkflowSnapshot({
115
- runId: "<run-id>",
116
- workflowName: "<workflow-id>",
117
- });
115
+ runId: '<run-id>',
116
+ workflowName: '<workflow-id>',
117
+ })
118
118
 
119
- console.log(snapshot);
119
+ console.log(snapshot)
120
120
  ```
121
121
 
122
122
  ## Storage options for snapshots
@@ -124,17 +124,17 @@ console.log(snapshot);
124
124
  Snapshots are persisted using a `storage` instance configured on the `Mastra` class. This storage layer is shared across all workflows registered to that instance. Mastra supports multiple storage options for flexibility in different environments.
125
125
 
126
126
  ```typescript
127
- import { Mastra } from "@mastra/core";
128
- import { LibSQLStore } from "@mastra/libsql";
129
- import { approvalWorkflow } from "./workflows";
127
+ import { Mastra } from '@mastra/core'
128
+ import { LibSQLStore } from '@mastra/libsql'
129
+ import { approvalWorkflow } from './workflows'
130
130
 
131
131
  export const mastra = new Mastra({
132
132
  storage: new LibSQLStore({
133
133
  id: 'mastra-storage',
134
- url: ":memory:",
134
+ url: ':memory:',
135
135
  }),
136
136
  workflows: { approvalWorkflow },
137
- });
137
+ })
138
138
  ```
139
139
 
140
140
  - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
@@ -150,7 +150,7 @@ export const mastra = new Mastra({
150
150
  1. **Ensure Serializability**: Any data that needs to be included in the snapshot must be serializable (convertible to JSON).
151
151
  2. **Minimize Snapshot Size**: Avoid storing large data objects directly in the workflow context. Instead, store references to them (like IDs) and retrieve the data when needed.
152
152
  3. **Handle Resume Context Carefully**: When resuming a workflow, carefully consider what context to provide. This will be merged with the existing snapshot data.
153
- 4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they are properly resumed.
153
+ 4. **Set Up Proper Monitoring**: Implement monitoring for suspended workflows, especially long-running ones, to ensure they're properly resumed.
154
154
  5. **Consider Storage Scaling**: For applications with many suspended workflows, ensure your storage solution is appropriately scaled.
155
155
 
156
156
  ## Custom snapshot metadata
@@ -158,12 +158,12 @@ export const mastra = new Mastra({
158
158
  You can attach custom metadata when suspending a workflow by defining a `suspendSchema`. This metadata is stored in the snapshot and made available when the workflow is resumed.
159
159
 
160
160
  ```typescript
161
- import { createWorkflow, createStep } from "@mastra/core/workflows";
162
- import { z } from "zod";
161
+ import { createWorkflow, createStep } from '@mastra/core/workflows'
162
+ import { z } from 'zod'
163
163
 
164
164
  const approvalStep = createStep({
165
- id: "approval-step",
166
- description: "Accepts a value, waits for confirmation",
165
+ id: 'approval-step',
166
+ description: 'Accepts a value, waits for confirmation',
167
167
  inputSchema: z.object({
168
168
  value: z.number(),
169
169
  user: z.string(),
@@ -183,23 +183,23 @@ const approvalStep = createStep({
183
183
  approved: z.boolean(),
184
184
  }),
185
185
  execute: async ({ inputData, resumeData, suspend }) => {
186
- const { value, user, requiredApprovers } = inputData;
187
- const { confirm } = resumeData ?? {};
186
+ const { value, user, requiredApprovers } = inputData
187
+ const { confirm } = resumeData ?? {}
188
188
 
189
189
  if (!confirm) {
190
190
  return await suspend({
191
- message: "Workflow suspended",
191
+ message: 'Workflow suspended',
192
192
  requestedBy: user,
193
193
  approvers: [...requiredApprovers],
194
- });
194
+ })
195
195
  }
196
196
 
197
197
  return {
198
198
  value,
199
199
  approved: confirm,
200
- };
200
+ }
201
201
  },
202
- });
202
+ })
203
203
  ```
204
204
 
205
205
  ### Providing resume data
@@ -207,26 +207,26 @@ const approvalStep = createStep({
207
207
  Use `resumeData` to pass structured input when resuming a suspended step. It must match the step’s `resumeSchema`.
208
208
 
209
209
  ```typescript
210
- const workflow = mastra.getWorkflow("approvalWorkflow");
210
+ const workflow = mastra.getWorkflow('approvalWorkflow')
211
211
 
212
- const run = await workflow.createRun();
212
+ const run = await workflow.createRun()
213
213
 
214
214
  const result = await run.start({
215
215
  inputData: {
216
216
  value: 100,
217
- user: "Michael",
218
- requiredApprovers: ["manager", "finance"],
217
+ user: 'Michael',
218
+ requiredApprovers: ['manager', 'finance'],
219
219
  },
220
- });
220
+ })
221
221
 
222
- if (result.status === "suspended") {
222
+ if (result.status === 'suspended') {
223
223
  const resumedResult = await run.resume({
224
- step: "approval-step",
224
+ step: 'approval-step',
225
225
  resumeData: {
226
226
  confirm: true,
227
- approver: "manager",
227
+ approver: 'manager',
228
228
  },
229
- });
229
+ })
230
230
  }
231
231
  ```
232
232
 
@@ -39,32 +39,32 @@ bun add @mastra/ai-sdk@latest
39
39
  Processors let you transform messages before they're sent to the model (`processInput`) and after responses are received (`processOutputResult`). This example creates a logging processor that logs message counts at each stage, then wraps an OpenAI model with it.
40
40
 
41
41
  ```typescript
42
- import { openai } from '@ai-sdk/openai';
43
- import { generateText } from 'ai';
44
- import { withMastra } from '@mastra/ai-sdk';
45
- import type { Processor } from '@mastra/core/processors';
42
+ import { openai } from '@ai-sdk/openai'
43
+ import { generateText } from 'ai'
44
+ import { withMastra } from '@mastra/ai-sdk'
45
+ import type { Processor } from '@mastra/core/processors'
46
46
 
47
47
  const loggingProcessor: Processor<'logger'> = {
48
48
  id: 'logger',
49
49
  async processInput({ messages }) {
50
- console.log('Input:', messages.length, 'messages');
51
- return messages;
50
+ console.log('Input:', messages.length, 'messages')
51
+ return messages
52
52
  },
53
53
  async processOutputResult({ messages }) {
54
- console.log('Output:', messages.length, 'messages');
55
- return messages;
54
+ console.log('Output:', messages.length, 'messages')
55
+ return messages
56
56
  },
57
- };
57
+ }
58
58
 
59
- const model = withMastra(openai('gpt-4o'), {
59
+ const model = withMastra(openai('gpt-5.4'), {
60
60
  inputProcessors: [loggingProcessor],
61
61
  outputProcessors: [loggingProcessor],
62
- });
62
+ })
63
63
 
64
64
  const { text } = await generateText({
65
65
  model,
66
66
  prompt: 'What is 2 + 2?',
67
- });
67
+ })
68
68
  ```
69
69
 
70
70
  ### With Memory
@@ -72,32 +72,32 @@ const { text } = await generateText({
72
72
  Memory automatically loads previous messages from storage before the LLM call and saves new messages after. This example configures a libSQL storage backend to persist conversation history, loading the last 10 messages for context.
73
73
 
74
74
  ```typescript
75
- import { openai } from '@ai-sdk/openai';
76
- import { generateText } from 'ai';
77
- import { withMastra } from '@mastra/ai-sdk';
78
- import { LibSQLStore } from '@mastra/libsql';
75
+ import { openai } from '@ai-sdk/openai'
76
+ import { generateText } from 'ai'
77
+ import { withMastra } from '@mastra/ai-sdk'
78
+ import { LibSQLStore } from '@mastra/libsql'
79
79
 
80
80
  const storage = new LibSQLStore({
81
81
  id: 'my-app',
82
82
  url: 'file:./data.db',
83
- });
84
- await storage.init();
83
+ })
84
+ await storage.init()
85
85
 
86
- const memoryStorage = await storage.getStore('memory');
86
+ const memoryStorage = await storage.getStore('memory')
87
87
 
88
- const model = withMastra(openai('gpt-4o'), {
88
+ const model = withMastra(openai('gpt-5.4'), {
89
89
  memory: {
90
90
  storage: memoryStorage!,
91
91
  threadId: 'user-thread-123',
92
92
  resourceId: 'user-123',
93
93
  lastMessages: 10,
94
94
  },
95
- });
95
+ })
96
96
 
97
97
  const { text } = await generateText({
98
98
  model,
99
99
  prompt: 'What did we talk about earlier?',
100
- });
100
+ })
101
101
  ```
102
102
 
103
103
  ### With Processors & Memory
@@ -105,17 +105,17 @@ const { text } = await generateText({
105
105
  You can combine processors and memory together. Input processors run after memory loads historical messages, and output processors run before memory saves the response.
106
106
 
107
107
  ```typescript
108
- import { openai } from '@ai-sdk/openai';
109
- import { generateText } from 'ai';
110
- import { withMastra } from '@mastra/ai-sdk';
111
- import { LibSQLStore } from '@mastra/libsql';
108
+ import { openai } from '@ai-sdk/openai'
109
+ import { generateText } from 'ai'
110
+ import { withMastra } from '@mastra/ai-sdk'
111
+ import { LibSQLStore } from '@mastra/libsql'
112
112
 
113
- const storage = new LibSQLStore({ id: 'my-app', url: 'file:./data.db' });
114
- await storage.init();
113
+ const storage = new LibSQLStore({ id: 'my-app', url: 'file:./data.db' })
114
+ await storage.init()
115
115
 
116
- const memoryStorage = await storage.getStore('memory');
116
+ const memoryStorage = await storage.getStore('memory')
117
117
 
118
- const model = withMastra(openai('gpt-4o'), {
118
+ const model = withMastra(openai('gpt-5.4'), {
119
119
  inputProcessors: [myGuardProcessor],
120
120
  outputProcessors: [myLoggingProcessor],
121
121
  memory: {
@@ -124,17 +124,17 @@ const model = withMastra(openai('gpt-4o'), {
124
124
  resourceId: 'user-123',
125
125
  lastMessages: 10,
126
126
  },
127
- });
127
+ })
128
128
 
129
129
  const { text } = await generateText({
130
130
  model,
131
131
  prompt: 'Hello!',
132
- });
132
+ })
133
133
  ```
134
134
 
135
135
  ## Related
136
136
 
137
- - [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra) - API reference for `withMastra()`
138
- - [Processors](https://mastra.ai/docs/agents/processors) - Learn about input and output processors
139
- - [Memory](https://mastra.ai/docs/memory/overview) - Overview of Mastra's memory system
140
- - [AI SDK UI](https://mastra.ai/guides/build-your-ui/ai-sdk-ui) - Using AI SDK UI hooks with Mastra agents, workflows, and networks
137
+ - [`withMastra()`](https://mastra.ai/reference/ai-sdk/with-mastra): API reference for `withMastra()`
138
+ - [Processors](https://mastra.ai/docs/agents/processors): Learn about input and output processors
139
+ - [Memory](https://mastra.ai/docs/memory/overview): Overview of Mastra's memory system
140
+ - [AI SDK UI](https://mastra.ai/guides/build-your-ui/ai-sdk-ui): Using AI SDK UI hooks with Mastra agents, workflows, and networks
@@ -5,46 +5,45 @@ The `.getMemory()` method retrieves a memory instance from the Mastra registry b
5
5
  ## Usage example
6
6
 
7
7
  ```typescript
8
- const memory = mastra.getMemory("conversationMemory");
8
+ const memory = mastra.getMemory('conversationMemory')
9
9
 
10
10
  // Use the memory instance
11
11
  const thread = await memory.createThread({
12
- resourceId: "user-123",
13
- title: "New Conversation",
14
- });
12
+ resourceId: 'user-123',
13
+ title: 'New Conversation',
14
+ })
15
15
  ```
16
16
 
17
17
  ## Parameters
18
18
 
19
- **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.
19
+ **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.
20
20
 
21
21
  ## Returns
22
22
 
23
- **memory:** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
23
+ **memory** (`TMemory[TMemoryKey]`): The memory instance with the specified key. Throws an error if the memory is not found.
24
24
 
25
- ## Example: Registering and Retrieving Memory
25
+ ## Example: Registering and retrieving memory
26
26
 
27
27
  ```typescript
28
- import { Mastra } from "@mastra/core";
29
- import { Memory } from "@mastra/memory";
30
- import { LibSQLStore } from "@mastra/libsql";
28
+ import { Mastra } from '@mastra/core'
29
+ import { Memory } from '@mastra/memory'
30
+ import { LibSQLStore } from '@mastra/libsql'
31
31
 
32
32
  const conversationMemory = new Memory({
33
- storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
34
- });
33
+ storage: new LibSQLStore({ id: 'conversation-store', url: ':memory:' }),
34
+ })
35
35
 
36
36
  const mastra = new Mastra({
37
37
  memory: {
38
38
  conversationMemory,
39
39
  },
40
- });
40
+ })
41
41
 
42
42
  // Later, retrieve the memory instance
43
- const memory = mastra.getMemory("conversationMemory");
43
+ const memory = mastra.getMemory('conversationMemory')
44
44
  ```
45
45
 
46
46
  ## Related
47
47
 
48
48
  - [Mastra.listMemory()](https://mastra.ai/reference/core/listMemory)
49
- - [Memory overview](https://mastra.ai/docs/memory/overview)
50
- - [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
49
+ - [Memory overview](https://mastra.ai/docs/memory/overview)
@@ -5,10 +5,10 @@ The `.listMemory()` method returns all memory instances registered with the Mast
5
5
  ## Usage example
6
6
 
7
7
  ```typescript
8
- const memoryInstances = mastra.listMemory();
8
+ const memoryInstances = mastra.listMemory()
9
9
 
10
10
  for (const [key, memory] of Object.entries(memoryInstances)) {
11
- console.log(`Memory "${key}": ${memory.id}`);
11
+ console.log(`Memory "${key}": ${memory.id}`)
12
12
  }
13
13
  ```
14
14
 
@@ -18,39 +18,38 @@ This method takes no parameters.
18
18
 
19
19
  ## Returns
20
20
 
21
- **memory:** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
21
+ **memory** (`Record<string, MastraMemory>`): An object containing all registered memory instances, keyed by their registry keys.
22
22
 
23
- ## Example: Checking Registered Memory
23
+ ## Example: Checking registered memory
24
24
 
25
25
  ```typescript
26
- import { Mastra } from "@mastra/core";
27
- import { Memory } from "@mastra/memory";
28
- import { LibSQLStore } from "@mastra/libsql";
26
+ import { Mastra } from '@mastra/core'
27
+ import { Memory } from '@mastra/memory'
28
+ import { LibSQLStore } from '@mastra/libsql'
29
29
 
30
30
  const conversationMemory = new Memory({
31
- id: "conversation-memory",
32
- storage: new LibSQLStore({ id: 'conversation-store', url: ":memory:" }),
33
- });
31
+ id: 'conversation-memory',
32
+ storage: new LibSQLStore({ id: 'conversation-store', url: ':memory:' }),
33
+ })
34
34
 
35
35
  const analyticsMemory = new Memory({
36
- id: "analytics-memory",
37
- storage: new LibSQLStore({ id: 'analytics-store', url: ":memory:" }),
38
- });
36
+ id: 'analytics-memory',
37
+ storage: new LibSQLStore({ id: 'analytics-store', url: ':memory:' }),
38
+ })
39
39
 
40
40
  const mastra = new Mastra({
41
41
  memory: {
42
42
  conversationMemory,
43
43
  analyticsMemory,
44
44
  },
45
- });
45
+ })
46
46
 
47
47
  // List all registered memory instances
48
- const allMemory = mastra.listMemory();
49
- console.log(Object.keys(allMemory)); // ["conversationMemory", "analyticsMemory"]
48
+ const allMemory = mastra.listMemory()
49
+ console.log(Object.keys(allMemory)) // ["conversationMemory", "analyticsMemory"]
50
50
  ```
51
51
 
52
52
  ## Related
53
53
 
54
54
  - [Mastra.getMemory()](https://mastra.ai/reference/core/getMemory)
55
- - [Memory overview](https://mastra.ai/docs/memory/overview)
56
- - [Agent Memory](https://mastra.ai/docs/agents/agent-memory)
55
+ - [Memory overview](https://mastra.ai/docs/memory/overview)
@@ -1,4 +1,4 @@
1
- # Mastra Class
1
+ # Mastra class
2
2
 
3
3
  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.
4
4
 
@@ -7,60 +7,70 @@ Think of `Mastra` as a top-level registry where you register agents, workflows,
7
7
  ## Usage example
8
8
 
9
9
  ```typescript
10
- import { Mastra } from "@mastra/core";
11
- import { PinoLogger } from "@mastra/loggers";
12
- import { LibSQLStore } from "@mastra/libsql";
13
- import { weatherWorkflow } from "./workflows/weather-workflow";
14
- import { weatherAgent } from "./agents/weather-agent";
10
+ import { Mastra } from '@mastra/core'
11
+ import { PinoLogger } from '@mastra/loggers'
12
+ import { LibSQLStore } from '@mastra/libsql'
13
+ import { weatherWorkflow } from './workflows/weather-workflow'
14
+ import { weatherAgent } from './agents/weather-agent'
15
15
 
16
16
  export const mastra = new Mastra({
17
17
  workflows: { weatherWorkflow },
18
18
  agents: { weatherAgent },
19
19
  storage: new LibSQLStore({
20
20
  id: 'mastra-storage',
21
- url: ":memory:",
21
+ url: ':memory:',
22
22
  }),
23
23
  logger: new PinoLogger({
24
- name: "Mastra",
25
- level: "info",
24
+ name: 'Mastra',
25
+ level: 'info',
26
26
  }),
27
- });
27
+ })
28
28
  ```
29
29
 
30
30
  ## Constructor parameters
31
31
 
32
32
  Visit the [Configuration reference](https://mastra.ai/reference/configuration) for detailed documentation on all available configuration options.
33
33
 
34
- **agents?:** (`Record<string, Agent>`): Agent instances to register, keyed by name (Default: `{}`)
34
+ **agents** (`Record<string, Agent>`): Agent instances to register, keyed by name (Default: `{}`)
35
35
 
36
- **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: `{}`)
36
+ **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: `{}`)
37
37
 
38
- **storage?:** (`MastraCompositeStore`): Storage engine instance for persisting data
38
+ **storage** (`MastraCompositeStore`): Storage engine instance for persisting data
39
39
 
40
- **vectors?:** (`Record<string, MastraVector>`): Vector store instance, used for semantic search and vector-based tools (eg Pinecone, PgVector or Qdrant)
40
+ **vectors** (`Record<string, MastraVector>`): Vector store instance, used for semantic search and vector-based tools (eg Pinecone, PgVector or Qdrant)
41
41
 
42
- **logger?:** (`Logger`): Logger instance created with new PinoLogger() (Default: `Console logger with INFO level`)
42
+ **logger** (`Logger`): Logger instance created with new PinoLogger() (Default: `Console logger with INFO level`)
43
43
 
44
- **idGenerator?:** (`() => string`): Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers.
44
+ **idGenerator** (`(context?: IdGeneratorContext) => string`): Custom ID generator function. Used by agents, workflows, memory, and other components to generate unique identifiers. Receives optional context such as idType, source, entityId, and threadId to support context-aware ID formats.
45
45
 
46
- **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: `{}`)
46
+ **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: `{}`)
47
47
 
48
- **tts?:** (`Record<string, MastraVoice>`): Text-to-speech providers for voice synthesis
48
+ **tts** (`Record<string, MastraVoice>`): Text-to-speech providers for voice synthesis
49
49
 
50
- **observability?:** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
50
+ **observability** (`ObservabilityEntrypoint`): Observability configuration for tracing and monitoring
51
51
 
52
- **deployer?:** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
52
+ **environment** (`string`): Deployment environment name (e.g. \`production\`, \`staging\`, \`development\`). When set, automatically attached to all observability signals so they can be filtered by environment without passing \`tracingOptions.metadata.environment\` on each call. Falls back to \`process.env.NODE\_ENV\` when unset; left undefined if neither is set. Per-call \`tracingOptions.metadata.environment\` always takes precedence.
53
53
 
54
- **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.
54
+ **deployer** (`MastraDeployer`): An instance of a MastraDeployer for managing deployments.
55
55
 
56
- **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().
56
+ **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.
57
57
 
58
- **bundler?:** (`BundlerConfig`): Configuration for the asset bundler with options for externals, sourcemap, and transpilePackages.
58
+ **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().
59
59
 
60
- **scorers?:** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs (Default: `{}`)
60
+ **bundler** (`BundlerConfig`): Configuration for the asset bundler with options for externals, sourcemap, transpilePackages, and dynamicPackages. (Default: `{ externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }`)
61
61
 
62
- **processors?:** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
62
+ **scorers** (`Record<string, Scorer>`): Scorers for evaluating agent responses and workflow outputs (Default: `{}`)
63
63
 
64
- **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: `{}`)
64
+ **processors** (`Record<string, Processor>`): Input/output processors for transforming agent inputs and outputs (Default: `{}`)
65
65
 
66
- **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: `{}`)
66
+ **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: `{}`)
67
+
68
+ **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: `{}`)
69
+
70
+ **versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning) for details.
71
+
72
+ **versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors. Each selector can target a specific version by ID or by publication status.
73
+
74
+ **versions.agents.versionId** (`string`): The ID of a specific version to use.
75
+
76
+ **versions.agents.status** (`'draft' | 'published'`): Select the latest version with this publication status.