@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.
- package/CHANGELOG.md +9405 -3
- package/LICENSE.md +15 -0
- package/README.md +11 -13
- package/dist/_types/@ai-sdk_provider/dist/index.d.ts +1587 -0
- package/dist/_types/@ai-sdk_provider-utils/dist/index.d.ts +379 -0
- package/dist/_types/@ai-sdk_ui-utils/dist/index.d.ts +820 -0
- package/dist/agent-learning.d.ts +182 -0
- package/dist/agent-learning.d.ts.map +1 -0
- package/dist/client.d.ts +767 -80
- package/dist/client.d.ts.map +1 -1
- package/dist/docs/SKILL.md +52 -0
- package/dist/docs/assets/SOURCE_MAP.json +6 -0
- package/dist/docs/references/docs-agents-a2a.md +340 -0
- package/dist/docs/references/docs-editor-overview.md +349 -0
- package/dist/docs/references/docs-long-running-agents-schedules.md +201 -0
- package/dist/docs/references/docs-long-running-agents-signals.md +426 -0
- package/dist/docs/references/docs-server-auth-auth0.md +262 -0
- package/dist/docs/references/docs-server-auth-clerk.md +154 -0
- package/dist/docs/references/docs-server-auth-firebase.md +294 -0
- package/dist/docs/references/docs-server-auth-jwt.md +116 -0
- package/dist/docs/references/docs-server-auth-supabase.md +139 -0
- package/dist/docs/references/docs-server-auth-workos.md +271 -0
- package/dist/docs/references/docs-server-mastra-client.md +323 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-messages.md +97 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-stream.md +282 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v4-messages.md +81 -0
- package/dist/docs/references/reference-ai-sdk-to-ai-sdk-v5-messages.md +78 -0
- package/dist/docs/references/reference-client-js-agents.md +959 -0
- package/dist/docs/references/reference-client-js-conversations.md +137 -0
- package/dist/docs/references/reference-client-js-error-handling.md +18 -0
- package/dist/docs/references/reference-client-js-logs.md +26 -0
- package/dist/docs/references/reference-client-js-mastra-client.md +96 -0
- package/dist/docs/references/reference-client-js-memory.md +237 -0
- package/dist/docs/references/reference-client-js-observability.md +183 -0
- package/dist/docs/references/reference-client-js-responses.md +219 -0
- package/dist/docs/references/reference-client-js-telemetry.md +22 -0
- package/dist/docs/references/reference-client-js-tools.md +46 -0
- package/dist/docs/references/reference-client-js-vectors.md +81 -0
- package/dist/docs/references/reference-client-js-workflows.md +393 -0
- package/dist/docs/references/reference-editor-versioning.md +130 -0
- package/dist/index.cjs +7638 -3257
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +9 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7606 -3252
- package/dist/index.js.map +1 -1
- package/dist/observability/collector.d.ts +45 -0
- package/dist/observability/collector.d.ts.map +1 -0
- package/dist/observability/index.d.ts +14 -0
- package/dist/observability/index.d.ts.map +1 -0
- package/dist/observability/types.d.ts +27 -0
- package/dist/observability/types.d.ts.map +1 -0
- package/dist/resources/a2a.d.ts +80 -11
- package/dist/resources/a2a.d.ts.map +1 -1
- package/dist/resources/agent-builder.d.ts +57 -72
- package/dist/resources/agent-builder.d.ts.map +1 -1
- package/dist/resources/agent-controller.d.ts +589 -0
- package/dist/resources/agent-controller.d.ts.map +1 -0
- package/dist/resources/agent.d.ts +368 -59
- package/dist/resources/agent.d.ts.map +1 -1
- package/dist/resources/base.d.ts +2 -1
- package/dist/resources/base.d.ts.map +1 -1
- package/dist/resources/channels.d.ts +63 -0
- package/dist/resources/channels.d.ts.map +1 -0
- package/dist/resources/conversations.d.ts +15 -0
- package/dist/resources/conversations.d.ts.map +1 -0
- package/dist/resources/index.d.ts +14 -0
- package/dist/resources/index.d.ts.map +1 -1
- package/dist/resources/mcp-tool.d.ts +5 -5
- package/dist/resources/mcp-tool.d.ts.map +1 -1
- package/dist/resources/memory-thread.d.ts +51 -16
- package/dist/resources/memory-thread.d.ts.map +1 -1
- package/dist/resources/observability.d.ts +222 -19
- package/dist/resources/observability.d.ts.map +1 -1
- package/dist/resources/processor-provider.d.ts +15 -0
- package/dist/resources/processor-provider.d.ts.map +1 -0
- package/dist/resources/processor.d.ts +20 -0
- package/dist/resources/processor.d.ts.map +1 -0
- package/dist/resources/responses.d.ts +22 -0
- package/dist/resources/responses.d.ts.map +1 -0
- package/dist/resources/run.d.ts +256 -0
- package/dist/resources/run.d.ts.map +1 -0
- package/dist/resources/stored-agent.d.ts +112 -0
- package/dist/resources/stored-agent.d.ts.map +1 -0
- package/dist/resources/stored-mcp-client.d.ts +30 -0
- package/dist/resources/stored-mcp-client.d.ts.map +1 -0
- package/dist/resources/stored-prompt-block.d.ts +83 -0
- package/dist/resources/stored-prompt-block.d.ts.map +1 -0
- package/dist/resources/stored-scorer.d.ts +83 -0
- package/dist/resources/stored-scorer.d.ts.map +1 -0
- package/dist/resources/stored-skill.d.ts +40 -0
- package/dist/resources/stored-skill.d.ts.map +1 -0
- package/dist/resources/stored-workflow.d.ts +18 -0
- package/dist/resources/stored-workflow.d.ts.map +1 -0
- package/dist/resources/tool-provider.d.ts +80 -0
- package/dist/resources/tool-provider.d.ts.map +1 -0
- package/dist/resources/tool.d.ts +4 -4
- package/dist/resources/vector.d.ts +9 -9
- package/dist/resources/vector.d.ts.map +1 -1
- package/dist/resources/workflow.d.ts +32 -231
- package/dist/resources/workflow.d.ts.map +1 -1
- package/dist/resources/workspace.d.ts +129 -0
- package/dist/resources/workspace.d.ts.map +1 -0
- package/dist/route-types.generated.d.ts +18087 -0
- package/dist/route-types.generated.d.ts.map +1 -0
- package/dist/tools.d.ts +3 -6
- package/dist/tools.d.ts.map +1 -1
- package/dist/types.d.ts +2740 -197
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/client-tool-model-output.d.ts +16 -0
- package/dist/utils/client-tool-model-output.d.ts.map +1 -0
- package/dist/utils/index.d.ts +65 -4
- package/dist/utils/index.d.ts.map +1 -1
- package/dist/utils/process-a2a-stream.d.ts +4 -0
- package/dist/utils/process-a2a-stream.d.ts.map +1 -0
- package/dist/utils/process-client-tools.d.ts.map +1 -1
- package/dist/utils/process-mastra-stream.d.ts +8 -7
- package/dist/utils/process-mastra-stream.d.ts.map +1 -1
- package/dist/utils/stream-transforms.d.ts +9 -0
- package/dist/utils/stream-transforms.d.ts.map +1 -0
- package/dist/utils/verify-agent-card-signature.d.ts +21 -0
- package/dist/utils/verify-agent-card-signature.d.ts.map +1 -0
- package/dist/utils/zod-to-json-schema.d.ts +11 -2
- package/dist/utils/zod-to-json-schema.d.ts.map +1 -1
- package/package.json +26 -19
- package/dist/resources/network-memory-thread.d.ts +0 -47
- 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.
|