@mastra/client-js 0.0.0-error-handler-fix-20251020202607 → 0.0.0-esbuild-bundle-worker-20260807182016

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 (127) hide show
  1. package/CHANGELOG.md +9405 -3
  2. package/LICENSE.md +15 -0
  3. package/README.md +11 -13
  4. package/dist/_types/@ai-sdk_provider/dist/index.d.ts +1587 -0
  5. package/dist/_types/@ai-sdk_provider-utils/dist/index.d.ts +379 -0
  6. package/dist/_types/@ai-sdk_ui-utils/dist/index.d.ts +820 -0
  7. package/dist/agent-learning.d.ts +182 -0
  8. package/dist/agent-learning.d.ts.map +1 -0
  9. package/dist/client.d.ts +767 -80
  10. package/dist/client.d.ts.map +1 -1
  11. package/dist/docs/SKILL.md +52 -0
  12. package/dist/docs/assets/SOURCE_MAP.json +6 -0
  13. package/dist/docs/references/docs-agents-a2a.md +340 -0
  14. package/dist/docs/references/docs-editor-overview.md +349 -0
  15. package/dist/docs/references/docs-long-running-agents-schedules.md +201 -0
  16. package/dist/docs/references/docs-long-running-agents-signals.md +426 -0
  17. package/dist/docs/references/docs-server-auth-auth0.md +262 -0
  18. package/dist/docs/references/docs-server-auth-clerk.md +154 -0
  19. package/dist/docs/references/docs-server-auth-firebase.md +294 -0
  20. package/dist/docs/references/docs-server-auth-jwt.md +116 -0
  21. package/dist/docs/references/docs-server-auth-supabase.md +139 -0
  22. package/dist/docs/references/docs-server-auth-workos.md +271 -0
  23. package/dist/docs/references/docs-server-mastra-client.md +323 -0
  24. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +97 -0
  25. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +282 -0
  26. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v4-messages.md +81 -0
  27. package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v5-messages.md +78 -0
  28. package/dist/docs/references/reference-client-js-agents.md +959 -0
  29. package/dist/docs/references/reference-client-js-conversations.md +137 -0
  30. package/dist/docs/references/reference-client-js-error-handling.md +18 -0
  31. package/dist/docs/references/reference-client-js-logs.md +26 -0
  32. package/dist/docs/references/reference-client-js-mastra-client.md +96 -0
  33. package/dist/docs/references/reference-client-js-memory.md +237 -0
  34. package/dist/docs/references/reference-client-js-observability.md +183 -0
  35. package/dist/docs/references/reference-client-js-responses.md +219 -0
  36. package/dist/docs/references/reference-client-js-telemetry.md +22 -0
  37. package/dist/docs/references/reference-client-js-tools.md +46 -0
  38. package/dist/docs/references/reference-client-js-vectors.md +81 -0
  39. package/dist/docs/references/reference-client-js-workflows.md +393 -0
  40. package/dist/docs/references/reference-editor-versioning.md +130 -0
  41. package/dist/index.cjs +7638 -3257
  42. package/dist/index.cjs.map +1 -1
  43. package/dist/index.d.ts +9 -0
  44. package/dist/index.d.ts.map +1 -1
  45. package/dist/index.js +7606 -3252
  46. package/dist/index.js.map +1 -1
  47. package/dist/observability/collector.d.ts +45 -0
  48. package/dist/observability/collector.d.ts.map +1 -0
  49. package/dist/observability/index.d.ts +14 -0
  50. package/dist/observability/index.d.ts.map +1 -0
  51. package/dist/observability/types.d.ts +27 -0
  52. package/dist/observability/types.d.ts.map +1 -0
  53. package/dist/resources/a2a.d.ts +80 -11
  54. package/dist/resources/a2a.d.ts.map +1 -1
  55. package/dist/resources/agent-builder.d.ts +57 -72
  56. package/dist/resources/agent-builder.d.ts.map +1 -1
  57. package/dist/resources/agent-controller.d.ts +589 -0
  58. package/dist/resources/agent-controller.d.ts.map +1 -0
  59. package/dist/resources/agent.d.ts +368 -59
  60. package/dist/resources/agent.d.ts.map +1 -1
  61. package/dist/resources/base.d.ts +2 -1
  62. package/dist/resources/base.d.ts.map +1 -1
  63. package/dist/resources/channels.d.ts +63 -0
  64. package/dist/resources/channels.d.ts.map +1 -0
  65. package/dist/resources/conversations.d.ts +15 -0
  66. package/dist/resources/conversations.d.ts.map +1 -0
  67. package/dist/resources/index.d.ts +14 -0
  68. package/dist/resources/index.d.ts.map +1 -1
  69. package/dist/resources/mcp-tool.d.ts +5 -5
  70. package/dist/resources/mcp-tool.d.ts.map +1 -1
  71. package/dist/resources/memory-thread.d.ts +51 -16
  72. package/dist/resources/memory-thread.d.ts.map +1 -1
  73. package/dist/resources/observability.d.ts +222 -19
  74. package/dist/resources/observability.d.ts.map +1 -1
  75. package/dist/resources/processor-provider.d.ts +15 -0
  76. package/dist/resources/processor-provider.d.ts.map +1 -0
  77. package/dist/resources/processor.d.ts +20 -0
  78. package/dist/resources/processor.d.ts.map +1 -0
  79. package/dist/resources/responses.d.ts +22 -0
  80. package/dist/resources/responses.d.ts.map +1 -0
  81. package/dist/resources/run.d.ts +256 -0
  82. package/dist/resources/run.d.ts.map +1 -0
  83. package/dist/resources/stored-agent.d.ts +112 -0
  84. package/dist/resources/stored-agent.d.ts.map +1 -0
  85. package/dist/resources/stored-mcp-client.d.ts +30 -0
  86. package/dist/resources/stored-mcp-client.d.ts.map +1 -0
  87. package/dist/resources/stored-prompt-block.d.ts +83 -0
  88. package/dist/resources/stored-prompt-block.d.ts.map +1 -0
  89. package/dist/resources/stored-scorer.d.ts +83 -0
  90. package/dist/resources/stored-scorer.d.ts.map +1 -0
  91. package/dist/resources/stored-skill.d.ts +40 -0
  92. package/dist/resources/stored-skill.d.ts.map +1 -0
  93. package/dist/resources/stored-workflow.d.ts +18 -0
  94. package/dist/resources/stored-workflow.d.ts.map +1 -0
  95. package/dist/resources/tool-provider.d.ts +80 -0
  96. package/dist/resources/tool-provider.d.ts.map +1 -0
  97. package/dist/resources/tool.d.ts +4 -4
  98. package/dist/resources/vector.d.ts +9 -9
  99. package/dist/resources/vector.d.ts.map +1 -1
  100. package/dist/resources/workflow.d.ts +32 -231
  101. package/dist/resources/workflow.d.ts.map +1 -1
  102. package/dist/resources/workspace.d.ts +129 -0
  103. package/dist/resources/workspace.d.ts.map +1 -0
  104. package/dist/route-types.generated.d.ts +18087 -0
  105. package/dist/route-types.generated.d.ts.map +1 -0
  106. package/dist/tools.d.ts +3 -6
  107. package/dist/tools.d.ts.map +1 -1
  108. package/dist/types.d.ts +2740 -197
  109. package/dist/types.d.ts.map +1 -1
  110. package/dist/utils/client-tool-model-output.d.ts +16 -0
  111. package/dist/utils/client-tool-model-output.d.ts.map +1 -0
  112. package/dist/utils/index.d.ts +65 -4
  113. package/dist/utils/index.d.ts.map +1 -1
  114. package/dist/utils/process-a2a-stream.d.ts +4 -0
  115. package/dist/utils/process-a2a-stream.d.ts.map +1 -0
  116. package/dist/utils/process-client-tools.d.ts.map +1 -1
  117. package/dist/utils/process-mastra-stream.d.ts +8 -7
  118. package/dist/utils/process-mastra-stream.d.ts.map +1 -1
  119. package/dist/utils/stream-transforms.d.ts +9 -0
  120. package/dist/utils/stream-transforms.d.ts.map +1 -0
  121. package/dist/utils/verify-agent-card-signature.d.ts +21 -0
  122. package/dist/utils/verify-agent-card-signature.d.ts.map +1 -0
  123. package/dist/utils/zod-to-json-schema.d.ts +11 -2
  124. package/dist/utils/zod-to-json-schema.d.ts.map +1 -1
  125. package/package.json +26 -19
  126. package/dist/resources/network-memory-thread.d.ts +0 -47
  127. package/dist/resources/network-memory-thread.d.ts.map +0 -1
@@ -0,0 +1,393 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Workflows API
4
+
5
+ The Workflows API provides methods to interact with and execute automated workflows in Mastra.
6
+
7
+ ## Getting all workflows
8
+
9
+ Retrieve a list of all available workflows:
10
+
11
+ ```typescript
12
+ const workflows = await mastraClient.listWorkflows()
13
+ ```
14
+
15
+ ## Working with a specific workflow
16
+
17
+ Get an instance of a specific workflow by its ID:
18
+
19
+ ```typescript
20
+ export const testWorkflow = createWorkflow({
21
+ id: 'city-workflow',
22
+ })
23
+ ```
24
+
25
+ ```typescript
26
+ const workflow = mastraClient.getWorkflow('city-workflow')
27
+ ```
28
+
29
+ ## Workflow methods
30
+
31
+ ### `details()`
32
+
33
+ Retrieve detailed information about a workflow:
34
+
35
+ ```typescript
36
+ const details = await workflow.details()
37
+ ```
38
+
39
+ ### `createRun()`
40
+
41
+ Create a new workflow run instance:
42
+
43
+ ```typescript
44
+ const run = await workflow.createRun()
45
+
46
+ // Or with an existing runId
47
+ const run = await workflow.createRun({ runId: 'existing-run-id' })
48
+
49
+ // Or with a resourceId to associate the run with a specific resource
50
+ const run = await workflow.createRun({
51
+ runId: 'my-run-id',
52
+ resourceId: 'user-123',
53
+ })
54
+ ```
55
+
56
+ The `resourceId` parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.
57
+
58
+ ### `startAsync()`
59
+
60
+ Start a workflow run and await its completion, returning the full result as the workflow output.
61
+
62
+ ```typescript
63
+ const run = await workflow.createRun()
64
+
65
+ const result = await run.startAsync({
66
+ inputData: {
67
+ city: 'New York',
68
+ },
69
+ })
70
+ ```
71
+
72
+ You can also pass `initialState` to set the starting values for the workflow's state:
73
+
74
+ ```typescript
75
+ const result = await run.startAsync({
76
+ inputData: {
77
+ city: 'New York',
78
+ },
79
+ initialState: {
80
+ count: 0,
81
+ items: [],
82
+ },
83
+ })
84
+ ```
85
+
86
+ The `initialState` object should match the structure defined in the workflow's `stateSchema`. See [Workflow State](https://mastra.ai/docs/workflows/workflow-state) for more details.
87
+
88
+ To associate a run with a specific resource, pass `resourceId` to `createRun()`:
89
+
90
+ ```typescript
91
+ const run = await workflow.createRun({ resourceId: 'user-123' })
92
+
93
+ const result = await run.startAsync({
94
+ inputData: {
95
+ city: 'New York',
96
+ },
97
+ })
98
+ ```
99
+
100
+ ### `start()`
101
+
102
+ Start a workflow run without waiting for completion (fire-and-forget). Returns immediately with a success message. Use `runById()` on the workflow instance to check results later:
103
+
104
+ ```typescript
105
+ const run = await workflow.createRun()
106
+
107
+ await run.start({
108
+ inputData: {
109
+ city: 'New York',
110
+ },
111
+ })
112
+
113
+ // Poll for results later
114
+ const result = await workflow.runById(run.runId)
115
+ ```
116
+
117
+ This is useful for long-running workflows where you want to start execution and check results later.
118
+
119
+ ### `resumeAsync()`
120
+
121
+ Resume a suspended workflow step and await the full result:
122
+
123
+ ```typescript
124
+ const run = await workflow.createRun({ runId: prevRunId })
125
+
126
+ const result = await run.resumeAsync({
127
+ step: 'step-id',
128
+ resumeData: { key: 'value' },
129
+ })
130
+ ```
131
+
132
+ ### `resume()`
133
+
134
+ Resume a suspended workflow step without waiting for completion:
135
+
136
+ ```typescript
137
+ const run = await workflow.createRun({ runId: prevRunId })
138
+
139
+ await run.resume({
140
+ step: 'step-id',
141
+ resumeData: { key: 'value' },
142
+ })
143
+ ```
144
+
145
+ When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based. `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.
146
+
147
+ ```typescript
148
+ await run.resume({
149
+ step: 'approve',
150
+ resumeData: { ok: true },
151
+ forEachIndex: 1, // resumes the second iteration
152
+ })
153
+ ```
154
+
155
+ `forEachIndex` is also supported by `resumeAsync()` and `resumeStream()`.
156
+
157
+ ### `cancel()`
158
+
159
+ Cancel a running workflow:
160
+
161
+ ```typescript
162
+ const run = await workflow.createRun({ runId: existingRunId })
163
+
164
+ const result = await run.cancel()
165
+ // Returns: { message: 'Workflow run canceled' }
166
+ ```
167
+
168
+ This method stops any running steps and prevents subsequent steps from executing. Steps that check the `abortSignal` parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).
169
+
170
+ See the [Run.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
171
+
172
+ ### `stream()`
173
+
174
+ Stream workflow execution for real-time updates:
175
+
176
+ ```typescript
177
+ const run = await workflow.createRun()
178
+
179
+ const stream = await run.stream({
180
+ inputData: {
181
+ city: 'New York',
182
+ },
183
+ })
184
+
185
+ for await (const chunk of stream) {
186
+ console.log(JSON.stringify(chunk, null, 2))
187
+ }
188
+ ```
189
+
190
+ ### `runById()`
191
+
192
+ Get the execution result for a workflow run:
193
+
194
+ ```typescript
195
+ const result = await workflow.runById(runId)
196
+
197
+ // Or with options for performance optimization:
198
+ const result = await workflow.runById(runId, {
199
+ fields: ['status', 'result'], // Only fetch specific fields
200
+ withNestedWorkflows: false, // Skip expensive nested workflow data
201
+ requestContext: { userId: 'user-123' }, // Optional request context
202
+ })
203
+ ```
204
+
205
+ ### Run result format
206
+
207
+ A workflow run result yields the following:
208
+
209
+ **runId** (`string`): Unique identifier for this workflow run instance
210
+
211
+ **eventTimestamp** (`Date`): The timestamp of the event
212
+
213
+ **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
214
+
215
+ ## Stored workflows
216
+
217
+ > **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
218
+
219
+ Stored workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for the definition format.
220
+
221
+ ### `listStoredWorkflows()`
222
+
223
+ List stored workflow definitions, optionally filtered by `status` (`'active' | 'archived'`) and `authorId`:
224
+
225
+ ```typescript
226
+ const { definitions, total } = await mastraClient.listStoredWorkflows({
227
+ status: 'active',
228
+ })
229
+ ```
230
+
231
+ ### `upsertStoredWorkflow()`
232
+
233
+ Create or replace a stored workflow definition. The server validates the definition, persists it, and live-registers it for execution:
234
+
235
+ ```typescript
236
+ const stored = await mastraClient.upsertStoredWorkflow({
237
+ id: 'greeting-workflow',
238
+ description: 'Returns a greeting for the supplied name',
239
+ inputSchema: {
240
+ type: 'object',
241
+ properties: { name: { type: 'string' } },
242
+ required: ['name'],
243
+ },
244
+ outputSchema: {
245
+ type: 'object',
246
+ properties: { message: { type: 'string' } },
247
+ required: ['message'],
248
+ },
249
+ graph: [
250
+ {
251
+ type: 'mapping',
252
+ id: 'create-greeting',
253
+ mapConfig: JSON.stringify({
254
+ message: { template: 'Hello, ${initData.name}!' },
255
+ }),
256
+ },
257
+ ],
258
+ })
259
+ ```
260
+
261
+ When the root definition nests helper workflows that don't exist yet, pass them in the same request through `dependencies`. The server validates and registers the bundle as a unit and echoes the helper ids back as `dependencyIds`:
262
+
263
+ ```typescript
264
+ const stored = await mastraClient.upsertStoredWorkflow({
265
+ id: 'root-workflow',
266
+ // ...schemas and graph referencing 'helper-workflow'...
267
+ dependencies: [helperDefinition],
268
+ })
269
+
270
+ console.log(stored.dependencyIds) // ['helper-workflow']
271
+ ```
272
+
273
+ ### `getStoredWorkflow()`
274
+
275
+ Get a stored workflow instance for definition management. To execute a stored workflow, use `getWorkflow(id).createRun()` like any other workflow:
276
+
277
+ ```typescript
278
+ const storedWorkflow = mastraClient.getStoredWorkflow('greeting-workflow')
279
+ ```
280
+
281
+ ### `storedWorkflow.details()`
282
+
283
+ Retrieve the persisted definition, including schemas, graph, status, and timestamps:
284
+
285
+ ```typescript
286
+ const definition = await storedWorkflow.details()
287
+ ```
288
+
289
+ ### `storedWorkflow.delete()`
290
+
291
+ Delete the stored definition and unregister the live workflow:
292
+
293
+ ```typescript
294
+ await storedWorkflow.delete()
295
+ ```
296
+
297
+ ### Executing a stored workflow
298
+
299
+ Once registered, a stored workflow runs through the ordinary workflow API:
300
+
301
+ ```typescript
302
+ const workflow = mastraClient.getWorkflow('greeting-workflow')
303
+ const run = await workflow.createRun()
304
+ const result = await run.startAsync({ inputData: { name: 'Ada' } })
305
+ ```
306
+
307
+ ## Schedules
308
+
309
+ Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing workflow schedules at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
310
+
311
+ ### `createSchedule()`
312
+
313
+ Create a workflow schedule by passing `workflowId`.
314
+
315
+ ```typescript
316
+ const schedule = await mastraClient.createSchedule({
317
+ workflowId: 'daily-report',
318
+ cron: '0 9 * * *',
319
+ inputData: { reportType: 'summary' },
320
+ })
321
+ ```
322
+
323
+ ### `listSchedules()`
324
+
325
+ List workflow schedules, optionally filtered by workflow ID or status.
326
+
327
+ ```typescript
328
+ const schedules = await mastraClient.listSchedules({
329
+ workflowId: 'daily-report',
330
+ status: 'active',
331
+ })
332
+ ```
333
+
334
+ ### `getSchedule()`
335
+
336
+ Fetch a single workflow schedule by ID.
337
+
338
+ ```typescript
339
+ const schedule = await mastraClient.getSchedule('daily-report')
340
+ ```
341
+
342
+ ### `updateSchedule()`
343
+
344
+ Update a workflow schedule.
345
+
346
+ ```typescript
347
+ const updated = await mastraClient.updateSchedule('daily-report', {
348
+ cron: '0 10 * * *',
349
+ inputData: { reportType: 'summary' },
350
+ })
351
+ ```
352
+
353
+ ### `deleteSchedule()`
354
+
355
+ Delete a workflow schedule.
356
+
357
+ ```typescript
358
+ await mastraClient.deleteSchedule('daily-report')
359
+ ```
360
+
361
+ ### `runSchedule()`
362
+
363
+ Fire a workflow schedule once immediately without changing its cron cadence.
364
+
365
+ ```typescript
366
+ const run = await mastraClient.runSchedule('daily-report')
367
+ ```
368
+
369
+ ### `pauseSchedule()`
370
+
371
+ Pause a schedule so the scheduler stops firing it. Returns the updated schedule.
372
+
373
+ ```typescript
374
+ await mastraClient.pauseSchedule('daily-report')
375
+ ```
376
+
377
+ ### `resumeSchedule()`
378
+
379
+ Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.
380
+
381
+ ```typescript
382
+ await mastraClient.resumeSchedule('daily-report')
383
+ ```
384
+
385
+ ### `listScheduleTriggers()`
386
+
387
+ List the trigger history for a workflow schedule, including the joined run summary for each fire.
388
+
389
+ ```typescript
390
+ const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {
391
+ limit: 50,
392
+ })
393
+ ```
@@ -0,0 +1,130 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Versioning
4
+
5
+ Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations. Code-backed agent overrides use deterministic files and Git history.
6
+
7
+ See [Editor versioning](https://mastra.ai/docs/editor/overview) for release and experimentation patterns.
8
+
9
+ ## Database lifecycle
10
+
11
+ The resource record stores an `activeVersionId`. Individual snapshots don't store a lifecycle status.
12
+
13
+ | Term | Meaning |
14
+ | ---------- | -------------------------------------------------------------------------------------------- |
15
+ | Latest | The most recently created configuration snapshot |
16
+ | Published | The snapshot selected by `activeVersionId` |
17
+ | Draft | The latest snapshot when it differs from `activeVersionId`, or when no active version exists |
18
+ | Historical | Any other retained snapshot |
19
+
20
+ Saving changed snapshot fields creates a new latest version. Saving identical snapshot fields or changing metadata alone doesn't create a version.
21
+
22
+ If an active version exists, creating a draft doesn't change the version handling published requests. Publishing updates `activeVersionId`. Restoring a historical version copies its configuration into a new inactive draft.
23
+
24
+ The direct namespace methods and REST APIs differ in one important way. `editor.prompt.update()` creates an inactive draft. `editor.agent.update()` creates a version and immediately assigns it to `activeVersionId`. The stored-agent REST `PATCH` route creates an inactive draft unless `autoPublish` is enabled.
25
+
26
+ When a generic stored resource has no active version, published resolution can fall back to the latest snapshot. For a code-defined agent override, requesting `status: 'published'` without an active override returns the original code agent.
27
+
28
+ ## Code source
29
+
30
+ With `source: 'code'`, active agent overrides are serialized as deterministic JSON under `<codePath>/agents/<encodedAgentId>.json`. The default `codePath` is `./mastra/editor`.
31
+
32
+ The initial agent is published to create the file. Later server updates create a draft by default and write the file when that version becomes active. Git versions are read-only in Studio and use the commit message as their change message. The default history scan reads up to 50 recent commits and skips consecutive commits whose parsed JSON snapshot is unchanged.
33
+
34
+ See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for source options.
35
+
36
+ ## Select an agent version
37
+
38
+ Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/editor/overview) for a TypeScript example.
39
+
40
+ With the default server prefix, pass selectors as query parameters under `/api`:
41
+
42
+ ```bash
43
+ # Published version
44
+ curl http://localhost:4111/api/agents/support-agent
45
+
46
+ # Latest draft
47
+ curl http://localhost:4111/api/agents/support-agent?status=draft
48
+
49
+ # Exact version
50
+ curl http://localhost:4111/api/agents/support-agent?versionId=abc-123
51
+ ```
52
+
53
+ See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agents) for Client SDK and React SDK selectors.
54
+
55
+ ## Sub-agent versioning
56
+
57
+ Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:
58
+
59
+ 1. `Mastra` instance `versions`: Defaults for every invocation
60
+ 2. Server request-body `versions`: Per-request values added to request context
61
+ 3. Direct `generate()` or `stream()` `versions`: Per-invocation values
62
+
63
+ Entries merge by agent ID. For the same ID, precedence is **direct invocation > request body or existing request context > Mastra instance default**.
64
+
65
+ Set defaults on the Mastra instance:
66
+
67
+ ```typescript
68
+ import { Mastra } from '@mastra/core'
69
+ import { MastraEditor } from '@mastra/editor'
70
+
71
+ export const mastra = new Mastra({
72
+ agents: { supervisor, researchAgent, writerAgent },
73
+ editor: new MastraEditor(),
74
+ versions: {
75
+ agents: {
76
+ 'research-agent': { status: 'published' },
77
+ 'writer-agent': { versionId: 'abc-123' },
78
+ },
79
+ },
80
+ })
81
+ ```
82
+
83
+ Override one sub-agent for a direct invocation:
84
+
85
+ ```typescript
86
+ const result = await supervisor.generate('Research and write about AI safety', {
87
+ versions: {
88
+ agents: {
89
+ 'research-agent': { status: 'draft' },
90
+ },
91
+ },
92
+ })
93
+ ```
94
+
95
+ Or pass selectors in the server request body:
96
+
97
+ ```bash
98
+ curl -X POST http://localhost:4111/api/agents/supervisor/generate \
99
+ -H "Content-Type: application/json" \
100
+ -d '{
101
+ "messages": [{ "role": "user", "content": "Research AI safety" }],
102
+ "versions": {
103
+ "agents": {
104
+ "research-agent": { "status": "draft" }
105
+ }
106
+ }
107
+ }'
108
+ ```
109
+
110
+ If Editor isn't configured or a version can't be resolved, Mastra logs a warning and uses the code-defined sub-agent.
111
+
112
+ ## Stored-agent REST API
113
+
114
+ The default Mastra server prefix is `/api`. A custom server prefix changes the paths below.
115
+
116
+ | Method | Path | Description |
117
+ | -------- | ---------------------------------------------- | -------------------------------------------------------------------- |
118
+ | `GET` | `/api/stored/agents` | List stored agents |
119
+ | `POST` | `/api/stored/agents` | Create a stored agent |
120
+ | `GET` | `/api/stored/agents/:storedAgentId` | Get a stored agent |
121
+ | `PATCH` | `/api/stored/agents/:storedAgentId` | Update a stored agent |
122
+ | `DELETE` | `/api/stored/agents/:storedAgentId` | Delete a stored agent |
123
+ | `GET` | `/api/stored/agents/:storedAgentId/dependents` | List readable dependents and count hidden cross-workspace references |
124
+ | `POST` | `/api/stored/agents/:storedAgentId/export` | Export the allowed override fields as deterministic JSON |
125
+
126
+ The dependents response lists caller-readable agents by `id` and `name`. Its `hiddenCount` field counts cross-workspace references that the caller can't read, but only when the target agent is public.
127
+
128
+ Version-management routes are nested under `/api/stored/agents/:storedAgentId/versions`. See [version management](https://mastra.ai/reference/client-js/agents) for operations and Client SDK methods.
129
+
130
+ The Client SDK exposes `listStoredAgents()`, `createStoredAgent()`, and `getStoredAgent()`. The resource returned by `getStoredAgent(id)` includes methods for updates, deletion, dependents, export, and version management.