@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,349 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Editor
4
+
5
+ Editor works like a CMS for Mastra agents. Collaborators can change an agent's instructions and tools in Studio without accessing the codebase or writing code. They can test changes before making them live.
6
+
7
+ TypeScript defines the agent's default values. Editor saves changes separately instead of updating the source code, so collaborators can improve the agent while developers retain control over its model, identity, and runtime.
8
+
9
+ A [deployed Studio](https://mastra.ai/docs/studio/deployment) makes Editor available to collaborators outside local development.
10
+
11
+ > **📹 Watch:** Watch the [Mastra Editor workshop](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D) for a guided walkthrough.
12
+
13
+ ## When to use Editor
14
+
15
+ Use Editor when an agent is defined in code but the people responsible for its behavior shouldn't edit the codebase. It works well when instructions or tools change often and need testing before they reach users. If developers own every change and release agent configuration with the application, keep the [agent configuration in code](https://mastra.ai/docs/agents/overview) instead.
16
+
17
+ ## Quickstart
18
+
19
+ Install `@mastra/editor`. This quickstart uses LibSQL to store Editor changes:
20
+
21
+ **npm**:
22
+
23
+ ```bash
24
+ npm install @mastra/editor @mastra/libsql
25
+ ```
26
+
27
+ **pnpm**:
28
+
29
+ ```bash
30
+ pnpm add @mastra/editor @mastra/libsql
31
+ ```
32
+
33
+ **Yarn**:
34
+
35
+ ```bash
36
+ yarn add @mastra/editor @mastra/libsql
37
+ ```
38
+
39
+ **Bun**:
40
+
41
+ ```bash
42
+ bun add @mastra/editor @mastra/libsql
43
+ ```
44
+
45
+ Add `MastraEditor` and storage to the `Mastra` instance. Existing storage can be reused instead of adding the LibSQL store shown here.
46
+
47
+ ```typescript
48
+ import { Mastra } from '@mastra/core'
49
+ import { MastraEditor } from '@mastra/editor'
50
+ import { LibSQLStore } from '@mastra/libsql'
51
+
52
+ export const mastra = new Mastra({
53
+ agents: {/* existing agents */},
54
+ storage: new LibSQLStore({
55
+ id: 'mastra-storage',
56
+ url: 'file:./mastra.db',
57
+ }),
58
+ editor: new MastraEditor(),
59
+ })
60
+ ```
61
+
62
+ ## Use Editor in Studio
63
+
64
+ In [Studio](https://mastra.ai/docs/studio/overview), open **Agents**, select an agent, then select **Editor**. Collaborators can update the agent's instructions and tools based on its Editor permissions.
65
+
66
+ With database storage, save changes as a draft to test them without affecting the live agent. Publish the draft when it's ready to use.
67
+
68
+ ## Instructions
69
+
70
+ The **Instructions** section shows the agent's system prompt defined in code. Collaborators can override it or add instruction blocks.
71
+
72
+ An instruction block can include values from the current request. For example, `{{userName}}` inserts a name supplied through [request context](https://mastra.ai/docs/server/request-context). A [display condition](https://mastra.ai/reference/editor/prompt-blocks) can show a block only for a customer, role, or feature flag.
73
+
74
+ ### Prompt blocks
75
+
76
+ A prompt block is a saved piece of instruction text that can be used by more than one agent. Create one under **Prompts**, publish it, then open an agent's **Instructions** section and select **Add block**.
77
+
78
+ For example, agents for support, returns, and order status may all need the same refund policy. Save the policy as a prompt block and add it to each agent. When the policy changes, update and publish the block once instead of editing three agents.
79
+
80
+ When a prompt block changes, every agent that references its published version receives the update. Draft changes are used only while previewing, so they don't affect the live agents until the block is published.
81
+
82
+ See the [prompt blocks reference](https://mastra.ai/reference/editor/prompt-blocks) for template syntax, conditions, versions, and APIs.
83
+
84
+ ## Tools
85
+
86
+ Tools let an agent take actions. Collaborators choose from the tools available to Editor, but they can't implement new tools in Studio. How tools become available depends on their source:
87
+
88
+ - **Project tools** must be implemented and registered in the Mastra project by a developer.
89
+ - **Integration tools** become available after a developer registers a provider such as Composio or Arcade. Collaborators can then browse the provider's catalog and add tools without each tool being added in code first.
90
+ - **MCP tools** become available when an MCP client is configured. A collaborator with access can create the client in Studio, then choose from the tools exposed by its servers.
91
+
92
+ In the agent's **Tools** section, collaborators can add the tools it needs or rewrite a tool's description for that agent. A more specific description helps the agent understand when to use the tool without changing the tool itself.
93
+
94
+ ### Project tools
95
+
96
+ Developers can register a project tool on the `Mastra` instance to make it available in Editor:
97
+
98
+ ```typescript
99
+ import { Mastra } from '@mastra/core'
100
+ import { MastraEditor } from '@mastra/editor'
101
+ import { searchOrders } from './tools/search-orders'
102
+
103
+ export const mastra = new Mastra({
104
+ tools: {
105
+ searchOrders,
106
+ },
107
+ agents: {/* agents */},
108
+ editor: new MastraEditor(),
109
+ })
110
+ ```
111
+
112
+ The Studio tool picker lists the tool. A collaborator can add it to an agent when that agent allows tool editing. The agent's Editor view also lists tools attached in code.
113
+
114
+ ### Composio
115
+
116
+ [Composio](https://composio.dev) provides tools for services such as GitHub, Slack, and Gmail. Register the provider with a Composio API key to make its tool catalog available in Editor:
117
+
118
+ ```typescript
119
+ import { Mastra } from '@mastra/core'
120
+ import { MastraEditor } from '@mastra/editor'
121
+ import { ComposioToolProvider } from '@mastra/editor/composio'
122
+
123
+ export const mastra = new Mastra({
124
+ agents: {/* agents */},
125
+ editor: new MastraEditor({
126
+ toolProviders: {
127
+ composio: new ComposioToolProvider({
128
+ apiKey: process.env.COMPOSIO_API_KEY!,
129
+ }),
130
+ },
131
+ }),
132
+ })
133
+ ```
134
+
135
+ Composio tool IDs look like `GITHUB_CREATE_ISSUE`. By default, a selected tool uses the connection associated with the agent's author. See [connection scope](https://agent-builder.mastra.ai/tool-providers#connection-scope) to use each caller's connection instead.
136
+
137
+ ### Arcade
138
+
139
+ [Arcade](https://arcade.dev) provides another catalog of tools with built-in authentication. Register it with an Arcade API key:
140
+
141
+ ```typescript
142
+ import { Mastra } from '@mastra/core'
143
+ import { MastraEditor } from '@mastra/editor'
144
+ import { ArcadeToolProvider } from '@mastra/editor/arcade'
145
+
146
+ export const mastra = new Mastra({
147
+ agents: {/* agents */},
148
+ editor: new MastraEditor({
149
+ toolProviders: {
150
+ arcade: new ArcadeToolProvider({
151
+ apiKey: process.env.ARCADE_API_KEY!,
152
+ }),
153
+ },
154
+ }),
155
+ })
156
+ ```
157
+
158
+ Arcade tool IDs use `Toolkit.ToolName` format, such as `Github.GetRepository`.
159
+
160
+ ### MCP clients
161
+
162
+ Collaborators can also create a reusable MCP client in Studio and add its tools to an agent. Stored clients can start a local `stdio` server or connect to a remote HTTP server. Tool filters let each agent use only the tools it needs from that server.
163
+
164
+ See the [Editor tools reference](https://mastra.ai/reference/editor/tools) for MCP configuration, conditions, filtering, and resolution order. See [`ToolProvider`](https://mastra.ai/reference/editor/tool-provider) for provider options.
165
+
166
+ ## Decide what collaborators can edit
167
+
168
+ By default, collaborators can change an agent's instructions and manage its tools, including their descriptions. The agent's `id`, `name`, and `model` always come from code.
169
+
170
+ Use the agent's `editor` field to limit what can be changed:
171
+
172
+ ```typescript
173
+ import { Agent } from '@mastra/core/agent'
174
+
175
+ export const supportAgent = new Agent({
176
+ id: 'support-agent',
177
+ name: 'Support agent',
178
+ instructions: 'Help customers with Acme products.',
179
+ model: 'openai/gpt-5.6-sol',
180
+ editor: {
181
+ instructions: true,
182
+ tools: {
183
+ description: true,
184
+ },
185
+ },
186
+ })
187
+ ```
188
+
189
+ This agent lets collaborators change its instructions and improve the descriptions of tools already attached to it. They can't add or remove tools.
190
+
191
+ | `editor` value | What collaborators can change |
192
+ | ---------------------------------- | ------------------------------------------- |
193
+ | Omitted | Instructions, tools, and tool descriptions |
194
+ | `false` | Nothing |
195
+ | `{ instructions: true }` | Instructions |
196
+ | `{ tools: true }` | Tools and tool descriptions |
197
+ | `{ tools: { description: true } }` | Descriptions of tools already added in code |
198
+
199
+ Studio shows everything else as read-only. See [editor overrides](https://mastra.ai/reference/agents/agent) for the complete configuration.
200
+
201
+ ## Choose where changes are stored
202
+
203
+ Editor can save changes in the configured database or as files in the repository.
204
+
205
+ ### Database storage
206
+
207
+ The database option is the default. Editor uses the storage configured on the `Mastra` instance, so the application and Editor can share the same backend.
208
+
209
+ To use a separate backend for Editor data, set the `editor` option on [`MastraCompositeStore`](https://mastra.ai/reference/storage/composite). Storage domains without an explicit route continue to use its `default` store.
210
+
211
+ The following example keeps application and Editor data in separate LibSQL files:
212
+
213
+ ```typescript
214
+ import { Mastra } from '@mastra/core'
215
+ import { MastraCompositeStore } from '@mastra/core/storage'
216
+ import { MastraEditor } from '@mastra/editor'
217
+ import { LibSQLStore } from '@mastra/libsql'
218
+
219
+ export const mastra = new Mastra({
220
+ agents: {/* existing agents */},
221
+ storage: new MastraCompositeStore({
222
+ id: 'mastra-storage',
223
+ default: new LibSQLStore({
224
+ id: 'app-storage',
225
+ url: 'file:./mastra.db',
226
+ }),
227
+ editor: new LibSQLStore({
228
+ id: 'editor-storage',
229
+ url: 'file:./editor.db',
230
+ }),
231
+ }),
232
+ editor: new MastraEditor(),
233
+ })
234
+ ```
235
+
236
+ ### Repository files
237
+
238
+ Use the code source to keep overrides alongside application code. Developers can review the files in pull requests and deploy them with the application:
239
+
240
+ ```typescript
241
+ import { Mastra } from '@mastra/core'
242
+ import { MastraEditor } from '@mastra/editor'
243
+
244
+ export const mastra = new Mastra({
245
+ agents: {/* existing agents */},
246
+ editor: new MastraEditor({
247
+ source: 'code',
248
+ codePath: './mastra/editor',
249
+ }),
250
+ })
251
+ ```
252
+
253
+ In this mode, each edited agent has one JSON override file. Editor doesn't generate TypeScript or change the file where the agent was created. By default, an agent with the ID `support-agent` gets this file:
254
+
255
+ ```text
256
+ mastra/editor/agents/support-agent.json
257
+ ```
258
+
259
+ The file contains only the parts managed by Editor. For example:
260
+
261
+ ```json
262
+ {
263
+ "instructions": "Help customers with Acme products and answer in their language.",
264
+ "tools": {
265
+ "searchOrders": {
266
+ "description": "Look up an order by its number"
267
+ }
268
+ }
269
+ }
270
+ ```
271
+
272
+ The agent's model, name, and other code-owned fields stay in its TypeScript file. Mastra reads the JSON and applies these values when the agent runs.
273
+
274
+ When a collaborator saves in Studio, they can write the file to the local filesystem or download it. With a source-control integration, Studio can open a pull request instead. Git then provides the review and version history.
275
+
276
+ See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for file locations and source options.
277
+
278
+ ## Versioning
279
+
280
+ Database-backed agents and prompt blocks use draft and published versions. Saving creates a draft while the live agent continues using the published version. Publishing makes the draft live. Restoring an older version creates a draft that collaborators can test before publishing.
281
+
282
+ Code-backed agent overrides use JSON files and Git history.
283
+
284
+ ### Select a version
285
+
286
+ An application can choose a stored version for each request by passing a status (`published` or `draft`) or an exact version ID:
287
+
288
+ ```typescript
289
+ const publishedAgent = await mastra.getAgentById('support-agent', {
290
+ status: 'published',
291
+ })
292
+
293
+ const draftAgent = await mastra.getAgentById('support-agent', {
294
+ status: 'draft',
295
+ })
296
+
297
+ const versionedAgent = await mastra.getAgentById('support-agent', {
298
+ versionId: 'abc-123',
299
+ })
300
+ ```
301
+
302
+ Version selection supports:
303
+
304
+ - Compare two versions in an A/B test.
305
+ - Give a draft to a small group before publishing it for everyone.
306
+ - Keep production on the published version while staging uses the latest draft.
307
+ - Pin a customer to a particular version.
308
+
309
+ The same version controls work when a supervisor calls sub-agents. Developers can test a draft sub-agent without changing the rest of the system.
310
+
311
+ See the [Editor versioning reference](https://mastra.ai/reference/editor/versioning) for version selection, sub-agent behavior, REST endpoints, and SDK methods.
312
+
313
+ ## Programmatic access
314
+
315
+ Everything available in Studio is also available programmatically through [`mastra.getEditor()`](https://mastra.ai/reference/core/getEditor), the REST API, or the Client SDK. Use it to script bulk updates or seed stored configurations from code. It can also power automation that tunes agents based on [evaluation results](https://mastra.ai/docs/datasets/running-experiments).
316
+
317
+ Call `mastra.getEditor()` when application code has access to the Mastra instance:
318
+
319
+ ```typescript
320
+ import { mastra } from '../mastra'
321
+
322
+ const editor = mastra.getEditor()!
323
+
324
+ await editor.agent.update({
325
+ id: 'support-agent',
326
+ instructions: 'Help customers with Acme products. Reply in their language.',
327
+ })
328
+ ```
329
+
330
+ The direct `editor.agent.update()` method activates the new version immediately. To create a draft without changing the live agent, use the stored-agent REST API or Client SDK instead:
331
+
332
+ ```bash
333
+ curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
334
+ -H "Content-Type: application/json" \
335
+ -d '{
336
+ "instructions": "Help customers with Acme products. Reply in their language."
337
+ }'
338
+ ```
339
+
340
+ The default server prefix is `/api`. Developers can set a custom prefix in the server configuration.
341
+
342
+ See the [`MastraEditor` namespaces](https://mastra.ai/reference/editor/mastra-editor) and [Client SDK agents API](https://mastra.ai/reference/client-js/agents) for available operations.
343
+
344
+ ## Next steps
345
+
346
+ - [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor)
347
+ - [Prompt blocks reference](https://mastra.ai/reference/editor/prompt-blocks)
348
+ - [Editor tools reference](https://mastra.ai/reference/editor/tools)
349
+ - [Editor versioning reference](https://mastra.ai/reference/editor/versioning)
@@ -0,0 +1,201 @@
1
+ > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
2
+
3
+ # Schedules
4
+
5
+ **Added in:** `@mastra/core@1.50.0`
6
+
7
+ > **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
8
+
9
+ A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
10
+
11
+ Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
12
+
13
+ > **Note:** Schedules require a [storage](https://mastra.ai/docs/storage/overview) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
14
+
15
+ ## Quickstart
16
+
17
+ The following schedule runs the `pinger` agent every hour. It has no thread, so each fire is an isolated `agent.generate()` run.
18
+
19
+ ```typescript
20
+ import { Mastra } from '@mastra/core'
21
+ import { Agent } from '@mastra/core/agent'
22
+ import { LibSQLStore } from '@mastra/libsql'
23
+
24
+ const pinger = new Agent({
25
+ id: 'pinger',
26
+ name: 'Pinger',
27
+ instructions: 'Report the current system status in one sentence.',
28
+ model: 'openai/gpt-5.6-sol',
29
+ })
30
+
31
+ const mastra = new Mastra({
32
+ agents: { pinger },
33
+ storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
34
+ })
35
+
36
+ await mastra.schedules.create({
37
+ agentId: 'pinger',
38
+ cron: '0 * * * *',
39
+ prompt: 'Give me a status update.',
40
+ })
41
+ ```
42
+
43
+ Mastra starts the scheduler the first time a schedule is created, then fires the agent on the cron you specify.
44
+
45
+ ## Cadence
46
+
47
+ Schedules fire on a cron expression. The `cron` field accepts a standard 5-, 6-, or 7-part cron expression, and it's validated when you create or update the schedule.
48
+
49
+ `croner` nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
50
+
51
+ ```typescript
52
+ // Every weekday at 9am
53
+ await mastra.schedules.create({
54
+ agentId: 'pinger',
55
+ cron: '0 9 * * 1-5',
56
+ prompt: 'Start-of-day check.',
57
+ })
58
+ ```
59
+
60
+ Set `timezone` to an IANA timezone, for example `America/New_York`, so fire times don't depend on the host's locale. When omitted, the cron resolves against the host's local timezone.
61
+
62
+ For more readable cron construction, you can use a userland builder such as [`cron-time-generator`](https://www.npmjs.com/package/cron-time-generator) and pass its output to `cron`.
63
+
64
+ ## Threadless and threaded schedules
65
+
66
+ An agent schedule fires in one of two modes, decided by whether you pass a `threadId`.
67
+
68
+ ### Threadless
69
+
70
+ Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing is written to a conversation thread. This is the simplest mode and suits status checks, reports, and other work that doesn't need conversation context.
71
+
72
+ ### Threaded
73
+
74
+ With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/long-running-agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
75
+
76
+ ```typescript
77
+ await mastra.schedules.create({
78
+ agentId: 'pinger',
79
+ cron: '0 9 * * *',
80
+ prompt: 'Summarize anything new since yesterday.',
81
+ threadId: 'thread-123',
82
+ resourceId: 'user-456',
83
+ })
84
+ ```
85
+
86
+ Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
87
+
88
+ These fields require a `threadId`. For the full threaded input shape, see the [agent schedule input reference](https://mastra.ai/reference/schedules/overview).
89
+
90
+ ```typescript
91
+ await mastra.schedules.create({
92
+ agentId: 'pinger',
93
+ cron: '0 9 * * *',
94
+ prompt: 'Summarize anything new since yesterday.',
95
+ threadId: 'thread-123',
96
+ resourceId: 'user-456',
97
+ tagName: 'check-in', // renders as <check-in>…</check-in>
98
+ attributes: { source: 'cron' },
99
+ ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
100
+ ifIdle: {
101
+ behavior: 'wake', // wake the agent if the thread is idle
102
+ streamOptions: { requestContext: { locale: 'en-US' } },
103
+ },
104
+ })
105
+ ```
106
+
107
+ `providerOptions` are merged into the signal payload on every fire and apply to both threaded and threadless schedules.
108
+
109
+ ## Managing schedules
110
+
111
+ Use `mastra.schedules` for all schedule operations. The service can create, read, update, pause, resume, manually run, and delete schedules.
112
+
113
+ ```typescript
114
+ const schedule = await mastra.schedules.create({
115
+ agentId: 'pinger',
116
+ cron: '0 * * * *',
117
+ prompt: 'Status check.',
118
+ })
119
+
120
+ await mastra.schedules.pause(schedule.id)
121
+ await mastra.schedules.resume(schedule.id)
122
+ await mastra.schedules.run(schedule.id) // Fire once now, off-schedule
123
+ ```
124
+
125
+ `pause` and `resume` are durable. `run` fires the schedule once immediately without affecting its cadence. For the complete method list, filters, and patch fields, see the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
126
+
127
+ ### Workflow schedules
128
+
129
+ The same service creates schedules that run a workflow instead of an agent. Pass `workflowId` and the workflow-shaped fields:
130
+
131
+ ```typescript
132
+ await mastra.schedules.create({
133
+ workflowId: 'daily-report',
134
+ cron: '0 9 * * *',
135
+ inputData: { userId: 'system' },
136
+ })
137
+ ```
138
+
139
+ Workflow schedules created this way are independent of the declarative `schedule` field on `createWorkflow`, see [scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows) for the declarative form and Studio views.
140
+
141
+ ### Custom IDs
142
+
143
+ Pass `id` when you need a predictable handle to look up, update, or delete later.
144
+
145
+ ```typescript
146
+ await mastra.schedules.create({
147
+ id: 'nightly-summary',
148
+ agentId: 'pinger',
149
+ cron: '0 9 * * *',
150
+ prompt: 'Summarize anything new since yesterday.',
151
+ })
152
+ ```
153
+
154
+ See the [`create(input)` reference](https://mastra.ai/reference/schedules/overview) for ID normalization rules and duplicate ID behavior.
155
+
156
+ ### From the client
157
+
158
+ The same operations are available from `@mastra/client-js` over the `/api/schedules` routes, so you can manage schedules from a separate process or a UI. See the [client-js agent schedules reference](https://mastra.ai/reference/client-js/agents) for the client method list.
159
+
160
+ ## Lifecycle hooks
161
+
162
+ Hooks let you run code at key points in an agent schedule's lifecycle, for example to compute fire-time parameters or react to the outcome. Configure them on the `Mastra` constructor under `schedules`. The hooks are a single flat bundle that runs for every agent's schedules; each hook context carries the firing `agentId`, so branch on it when you need per-agent behavior. Hooks live at the `Mastra` level so they apply to both code-defined and stored agents.
163
+
164
+ ```typescript
165
+ const mastra = new Mastra({
166
+ agents: { pinger },
167
+ storage: new LibSQLStore({ id: 'mastra-storage', url: 'file:./mastra.db' }),
168
+ schedules: {
169
+ prepare: async ({ agentId, schedule, trigger }) => {
170
+ // Return overrides, null to skip this fire, or undefined for defaults
171
+ return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
172
+ },
173
+ onFinish: async ({ agentId, outcome, runId }) => {
174
+ // Runs on any non-error, non-abort outcome
175
+ },
176
+ onError: async ({ agentId, phase, error }) => {
177
+ // Runs when prepare, the signal, or the agent run threw
178
+ },
179
+ onAbort: async ({ agentId, runId }) => {
180
+ // Runs when the run was aborted mid-stream
181
+ },
182
+ },
183
+ })
184
+ ```
185
+
186
+ The hooks are:
187
+
188
+ - `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
189
+ - `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
190
+ - `onError`: runs after a failure in `prepare` or the signal. It also runs when the agent run fails.
191
+ - `onAbort`: runs when the run was aborted mid-stream.
192
+
193
+ Every hook context includes `agentId` (the agent the schedule fired for) alongside `schedule` and `trigger`.
194
+
195
+ Hook exceptions are caught and logged. They never re-route the worker or trigger another hook.
196
+
197
+ ## Related
198
+
199
+ - [`mastra.schedules`](https://mastra.ai/reference/schedules/overview): API reference for creating and managing schedules.
200
+ - [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded schedules.
201
+ - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): declare a cron schedule on a workflow definition.