@mastra/libsql 1.19.0-alpha.1 → 1.19.0-alpha.2
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 +16 -0
- package/dist/docs/SKILL.md +3 -4
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/docs-editor-overview.md +349 -0
- package/dist/docs/references/{docs-rag-retrieval.md → guides-rag-retrieval.md} +1 -1
- package/dist/docs/references/reference-core-mastra-class.md +1 -1
- package/dist/docs/references/reference-storage-composite.md +2 -0
- package/dist/index.cjs +18 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +18 -6
- package/dist/index.js.map +1 -1
- package/dist/storage/domains/datasets/index.d.ts.map +1 -1
- package/package.json +3 -3
- package/dist/docs/references/docs-agent-builder-deploying.md +0 -124
- package/dist/docs/references/docs-agent-builder-overview.md +0 -114
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# @mastra/libsql
|
|
2
2
|
|
|
3
|
+
## 1.19.0-alpha.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Dataset item scorer selections now persist across LibSQL writes and reads. Setting `scorerIds` to `null` clears an item override, while `[]` remains an explicit override with no scorers. ([#20191](https://github.com/mastra-ai/mastra/pull/20191))
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
await dataset.addItem({
|
|
11
|
+
input: 'Evaluate this response',
|
|
12
|
+
scorerIds: [],
|
|
13
|
+
});
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
- Updated dependencies [[`82201f7`](https://github.com/mastra-ai/mastra/commit/82201f75fae8e050a8de2df08b74875ee74c6b83), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`0a6598b`](https://github.com/mastra-ai/mastra/commit/0a6598bde80bde008986ad6616bed9632b9294cb), [`9e1dad8`](https://github.com/mastra-ai/mastra/commit/9e1dad8f7b1cab2bb7ade90e5b7561f24577b88a), [`2f43145`](https://github.com/mastra-ai/mastra/commit/2f4314504c03cbba280414ac81ba3197448ee6b0), [`34d34d8`](https://github.com/mastra-ai/mastra/commit/34d34d8c811df512fef4dd5459f79b7821be1866)]:
|
|
17
|
+
- @mastra/core@1.56.0-alpha.6
|
|
18
|
+
|
|
3
19
|
## 1.19.0-alpha.1
|
|
4
20
|
|
|
5
21
|
### Patch Changes
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-libsql
|
|
|
3
3
|
description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/libsql"
|
|
6
|
-
version: "1.19.0-alpha.
|
|
6
|
+
version: "1.19.0-alpha.2"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -16,24 +16,23 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
16
16
|
|
|
17
17
|
### Docs
|
|
18
18
|
|
|
19
|
-
- [Deploying](references/docs-agent-builder-deploying.md) - Swap local Agent Builder primitives for cloud-backed storage, filesystems, sandboxes, an EE license, auth, and a public channel URL for production.
|
|
20
|
-
- [Agent Builder overview](references/docs-agent-builder-overview.md) - Let teammates create, configure, and operate Mastra agents from a browser, with admin-pinned defaults, RBAC, and channel integrations.
|
|
21
19
|
- [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals and suspend tool execution, plus automatically resume suspended tools while keeping humans in control of agent workflows.
|
|
22
20
|
- [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
|
|
23
21
|
- [Workers](references/docs-deployment-workers.md) - Separate background processing from the API layer by running workflow execution, cron schedules, and background tasks in dedicated worker processes.
|
|
22
|
+
- [Editor](references/docs-editor-overview.md) - Let collaborators update an agent in Studio, test their changes, and publish without editing code.
|
|
24
23
|
- [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
|
|
25
24
|
- [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
|
|
26
25
|
- [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
|
|
27
26
|
- [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
|
|
28
27
|
- [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
|
|
29
28
|
- [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
|
|
30
|
-
- [Retrieval, semantic search, reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
|
|
31
29
|
- [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
|
|
32
30
|
- [Snapshots](references/docs-workflows-snapshots.md) - Learn how to save and resume workflow execution state with snapshots in Mastra
|
|
33
31
|
|
|
34
32
|
### Guides
|
|
35
33
|
|
|
36
34
|
- [AI SDK](references/guides-agent-frameworks-ai-sdk.md) - Use Mastra processors and memory with the Vercel AI SDK
|
|
35
|
+
- [Retrieval, semantic search, reranking](references/guides-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
|
|
37
36
|
|
|
38
37
|
### Reference
|
|
39
38
|
|
|
@@ -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)
|
|
@@ -517,4 +517,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
|
|
|
517
517
|
|
|
518
518
|
For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
|
|
519
519
|
|
|
520
|
-
For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/
|
|
520
|
+
For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.
|
|
@@ -97,7 +97,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
|
|
|
97
97
|
|
|
98
98
|
**notifications.dispatch.batchSize** (`number`): Maximum number of due notification records to process per dispatch run.
|
|
99
99
|
|
|
100
|
-
**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
|
|
100
|
+
**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 Editor versioning for details.
|
|
101
101
|
|
|
102
102
|
**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.
|
|
103
103
|
|
|
@@ -188,6 +188,8 @@ export const mastra = new Mastra({
|
|
|
188
188
|
|
|
189
189
|
**default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in domains will use this storage's domains as fallbacks.
|
|
190
190
|
|
|
191
|
+
**editor** (`MastraCompositeStore`): Storage adapter for Editor-owned domains, including agents, prompt blocks, scorers, MCP clients and servers, workspaces, and skills. Takes precedence over default storage but not explicit domain overrides.
|
|
192
|
+
|
|
191
193
|
**disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
|
|
192
194
|
|
|
193
195
|
**domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.
|
package/dist/index.cjs
CHANGED
|
@@ -3469,6 +3469,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3469
3469
|
await this.#addColumnIfNotExists(_mastra_core_storage.TABLE_DATASET_ITEMS, "projectId", "TEXT");
|
|
3470
3470
|
await this.#addColumnIfNotExists(_mastra_core_storage.TABLE_DATASET_ITEMS, "toolMocks", "TEXT");
|
|
3471
3471
|
await this.#addColumnIfNotExists(_mastra_core_storage.TABLE_DATASET_ITEMS, "unmockedToolPolicy", "TEXT");
|
|
3472
|
+
await this.#addColumnIfNotExists(_mastra_core_storage.TABLE_DATASET_ITEMS, "scorerIds", "TEXT");
|
|
3472
3473
|
await this.#addColumnIfNotExists(_mastra_core_storage.TABLE_DATASET_ITEMS, "externalId", "TEXT");
|
|
3473
3474
|
await this.#client.batch([
|
|
3474
3475
|
{
|
|
@@ -3566,6 +3567,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3566
3567
|
expectedTrajectory: row.expectedTrajectory ? (0, _mastra_core_storage.safelyParseJSON)(row.expectedTrajectory) : void 0,
|
|
3567
3568
|
toolMocks: row.toolMocks ? (0, _mastra_core_storage.safelyParseJSON)(row.toolMocks) : void 0,
|
|
3568
3569
|
unmockedToolPolicy: row.unmockedToolPolicy ?? void 0,
|
|
3570
|
+
scorerIds: row.scorerIds ? (0, _mastra_core_storage.safelyParseJSON)(row.scorerIds) : void 0,
|
|
3569
3571
|
requestContext: row.requestContext ? (0, _mastra_core_storage.safelyParseJSON)(row.requestContext) : void 0,
|
|
3570
3572
|
metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : void 0,
|
|
3571
3573
|
source: row.source ? (0, _mastra_core_storage.safelyParseJSON)(row.source) : void 0,
|
|
@@ -3588,6 +3590,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3588
3590
|
expectedTrajectory: row.expectedTrajectory ? (0, _mastra_core_storage.safelyParseJSON)(row.expectedTrajectory) : void 0,
|
|
3589
3591
|
toolMocks: row.toolMocks ? (0, _mastra_core_storage.safelyParseJSON)(row.toolMocks) : void 0,
|
|
3590
3592
|
unmockedToolPolicy: row.unmockedToolPolicy ?? void 0,
|
|
3593
|
+
scorerIds: row.scorerIds ? (0, _mastra_core_storage.safelyParseJSON)(row.scorerIds) : void 0,
|
|
3591
3594
|
requestContext: row.requestContext ? (0, _mastra_core_storage.safelyParseJSON)(row.requestContext) : void 0,
|
|
3592
3595
|
metadata: row.metadata ? (0, _mastra_core_storage.safelyParseJSON)(row.metadata) : void 0,
|
|
3593
3596
|
source: row.source ? (0, _mastra_core_storage.safelyParseJSON)(row.source) : void 0,
|
|
@@ -3901,7 +3904,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3901
3904
|
args: [args.datasetId]
|
|
3902
3905
|
},
|
|
3903
3906
|
{
|
|
3904
|
-
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,
|
|
3907
|
+
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,datasetId,datasetVersion,externalId,organizationId,projectId,validTo,isDeleted,input,groundTruth,expectedTrajectory,toolMocks,unmockedToolPolicy,scorerIds,requestContext,metadata,source,createdAt,updatedAt) VALUES (?,?,(SELECT version FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),?,(SELECT organizationId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),(SELECT projectId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),NULL,0,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,?)`,
|
|
3905
3908
|
args: [
|
|
3906
3909
|
id,
|
|
3907
3910
|
args.datasetId,
|
|
@@ -3914,6 +3917,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3914
3917
|
jsonbArg(args.expectedTrajectory),
|
|
3915
3918
|
jsonbArg(args.toolMocks),
|
|
3916
3919
|
args.unmockedToolPolicy ?? null,
|
|
3920
|
+
jsonbArg(args.scorerIds),
|
|
3917
3921
|
jsonbArg(args.requestContext),
|
|
3918
3922
|
jsonbArg(args.metadata),
|
|
3919
3923
|
jsonbArg(args.source),
|
|
@@ -3944,6 +3948,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3944
3948
|
expectedTrajectory: args.expectedTrajectory,
|
|
3945
3949
|
toolMocks: args.toolMocks,
|
|
3946
3950
|
unmockedToolPolicy: args.unmockedToolPolicy,
|
|
3951
|
+
scorerIds: args.scorerIds,
|
|
3947
3952
|
requestContext: args.requestContext,
|
|
3948
3953
|
metadata: args.metadata,
|
|
3949
3954
|
source: args.source,
|
|
@@ -3987,6 +3992,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
3987
3992
|
const mergedExpectedTrajectory = args.expectedTrajectory !== void 0 ? args.expectedTrajectory : existing.expectedTrajectory;
|
|
3988
3993
|
const mergedToolMocks = args.toolMocks !== void 0 ? args.toolMocks : existing.toolMocks;
|
|
3989
3994
|
const mergedUnmockedToolPolicy = args.unmockedToolPolicy !== void 0 ? args.unmockedToolPolicy : existing.unmockedToolPolicy;
|
|
3995
|
+
const mergedScorerIds = args.scorerIds !== void 0 ? args.scorerIds ?? void 0 : existing.scorerIds;
|
|
3990
3996
|
const mergedRequestContext = args.requestContext !== void 0 ? args.requestContext : existing.requestContext;
|
|
3991
3997
|
const mergedMetadata = args.metadata !== void 0 ? args.metadata : existing.metadata;
|
|
3992
3998
|
const mergedSource = args.source !== void 0 ? args.source : existing.source;
|
|
@@ -4000,7 +4006,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4000
4006
|
args: [args.datasetId, args.id]
|
|
4001
4007
|
},
|
|
4002
4008
|
{
|
|
4003
|
-
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,
|
|
4009
|
+
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,datasetId,datasetVersion,externalId,organizationId,projectId,validTo,isDeleted,input,groundTruth,expectedTrajectory,toolMocks,unmockedToolPolicy,scorerIds,requestContext,metadata,source,createdAt,updatedAt) VALUES (?,?,(SELECT version FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),?,(SELECT organizationId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),(SELECT projectId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),NULL,0,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,?)`,
|
|
4004
4010
|
args: [
|
|
4005
4011
|
args.id,
|
|
4006
4012
|
args.datasetId,
|
|
@@ -4013,6 +4019,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4013
4019
|
jsonbArg(mergedExpectedTrajectory),
|
|
4014
4020
|
jsonbArg(mergedToolMocks),
|
|
4015
4021
|
mergedUnmockedToolPolicy ?? null,
|
|
4022
|
+
jsonbArg(mergedScorerIds),
|
|
4016
4023
|
jsonbArg(mergedRequestContext),
|
|
4017
4024
|
jsonbArg(mergedMetadata),
|
|
4018
4025
|
jsonbArg(mergedSource),
|
|
@@ -4041,6 +4048,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4041
4048
|
expectedTrajectory: mergedExpectedTrajectory,
|
|
4042
4049
|
toolMocks: mergedToolMocks,
|
|
4043
4050
|
unmockedToolPolicy: mergedUnmockedToolPolicy,
|
|
4051
|
+
scorerIds: mergedScorerIds,
|
|
4044
4052
|
requestContext: mergedRequestContext,
|
|
4045
4053
|
metadata: mergedMetadata,
|
|
4046
4054
|
source: mergedSource,
|
|
@@ -4081,7 +4089,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4081
4089
|
args: [datasetId, id]
|
|
4082
4090
|
},
|
|
4083
4091
|
{
|
|
4084
|
-
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,
|
|
4092
|
+
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,datasetId,datasetVersion,externalId,organizationId,projectId,validTo,isDeleted,input,groundTruth,expectedTrajectory,toolMocks,unmockedToolPolicy,scorerIds,requestContext,metadata,source,createdAt,updatedAt) VALUES (?,?,(SELECT version FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),?,(SELECT organizationId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),(SELECT projectId FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),NULL,1,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,?)`,
|
|
4085
4093
|
args: [
|
|
4086
4094
|
id,
|
|
4087
4095
|
datasetId,
|
|
@@ -4094,6 +4102,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4094
4102
|
jsonbArg(existing.expectedTrajectory),
|
|
4095
4103
|
jsonbArg(existing.toolMocks),
|
|
4096
4104
|
existing.unmockedToolPolicy ?? null,
|
|
4105
|
+
jsonbArg(existing.scorerIds),
|
|
4097
4106
|
jsonbArg(existing.requestContext),
|
|
4098
4107
|
jsonbArg(existing.metadata),
|
|
4099
4108
|
jsonbArg(existing.source),
|
|
@@ -4389,7 +4398,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4389
4398
|
});
|
|
4390
4399
|
const externalIds = [...new Set(input.items.flatMap((item) => item.externalId ? [item.externalId] : []))];
|
|
4391
4400
|
const historyResult = externalIds.length ? await tx.execute({
|
|
4392
|
-
sql: `SELECT id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, json(input) AS input, json(groundTruth) AS groundTruth, json(expectedTrajectory) AS expectedTrajectory, json(toolMocks) AS toolMocks, unmockedToolPolicy, json(requestContext) AS requestContext, json(metadata) AS metadata, json(source) AS source, createdAt, updatedAt FROM ${_mastra_core_storage.TABLE_DATASET_ITEMS} WHERE datasetId = ? AND externalId IN (${externalIds.map(() => "?").join(",")}) ORDER BY datasetVersion`,
|
|
4401
|
+
sql: `SELECT id, datasetId, datasetVersion, externalId, organizationId, projectId, validTo, isDeleted, json(input) AS input, json(groundTruth) AS groundTruth, json(expectedTrajectory) AS expectedTrajectory, json(toolMocks) AS toolMocks, unmockedToolPolicy, json(scorerIds) AS scorerIds, json(requestContext) AS requestContext, json(metadata) AS metadata, json(source) AS source, createdAt, updatedAt FROM ${_mastra_core_storage.TABLE_DATASET_ITEMS} WHERE datasetId = ? AND externalId IN (${externalIds.map(() => "?").join(",")}) ORDER BY datasetVersion`,
|
|
4393
4402
|
args: [input.datasetId, ...externalIds]
|
|
4394
4403
|
}) : { rows: [] };
|
|
4395
4404
|
const plan = this.planDatasetItemBatch(input.items, historyResult.rows.map((row) => this.transformItemRowFull(row)), () => crypto.randomUUID());
|
|
@@ -4404,7 +4413,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4404
4413
|
});
|
|
4405
4414
|
for (const { id, item } of plan.inserts) {
|
|
4406
4415
|
await tx.execute({
|
|
4407
|
-
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,
|
|
4416
|
+
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,datasetId,datasetVersion,externalId,organizationId,projectId,validTo,isDeleted,input,groundTruth,expectedTrajectory,toolMocks,unmockedToolPolicy,scorerIds,requestContext,metadata,source,createdAt,updatedAt) VALUES (?,?,?,?,?,?,NULL,0,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,?)`,
|
|
4408
4417
|
args: [
|
|
4409
4418
|
id,
|
|
4410
4419
|
input.datasetId,
|
|
@@ -4417,6 +4426,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4417
4426
|
jsonbArg(item.expectedTrajectory),
|
|
4418
4427
|
jsonbArg(item.toolMocks),
|
|
4419
4428
|
item.unmockedToolPolicy ?? null,
|
|
4429
|
+
jsonbArg(item.scorerIds),
|
|
4420
4430
|
jsonbArg(item.requestContext),
|
|
4421
4431
|
jsonbArg(item.metadata),
|
|
4422
4432
|
jsonbArg(item.source),
|
|
@@ -4436,6 +4446,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4436
4446
|
expectedTrajectory: item.expectedTrajectory,
|
|
4437
4447
|
toolMocks: item.toolMocks,
|
|
4438
4448
|
unmockedToolPolicy: item.unmockedToolPolicy,
|
|
4449
|
+
scorerIds: item.scorerIds,
|
|
4439
4450
|
requestContext: item.requestContext,
|
|
4440
4451
|
metadata: item.metadata,
|
|
4441
4452
|
source: item.source,
|
|
@@ -4496,7 +4507,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4496
4507
|
args: [input.datasetId, item.id]
|
|
4497
4508
|
});
|
|
4498
4509
|
statements.push({
|
|
4499
|
-
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,
|
|
4510
|
+
sql: `INSERT INTO ${_mastra_core_storage.TABLE_DATASET_ITEMS} (id,datasetId,datasetVersion,externalId,organizationId,projectId,validTo,isDeleted,input,groundTruth,expectedTrajectory,toolMocks,unmockedToolPolicy,scorerIds,requestContext,metadata,source,createdAt,updatedAt) VALUES (?,?,(SELECT version FROM ${_mastra_core_storage.TABLE_DATASETS} WHERE id = ?),?,?,?,NULL,1,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,jsonb(?),jsonb(?),jsonb(?),jsonb(?),?,?)`,
|
|
4500
4511
|
args: [
|
|
4501
4512
|
item.id,
|
|
4502
4513
|
input.datasetId,
|
|
@@ -4509,6 +4520,7 @@ var DatasetsLibSQL = class extends _mastra_core_storage.DatasetsStorage {
|
|
|
4509
4520
|
jsonbArg(item.expectedTrajectory),
|
|
4510
4521
|
jsonbArg(item.toolMocks),
|
|
4511
4522
|
item.unmockedToolPolicy ?? null,
|
|
4523
|
+
jsonbArg(item.scorerIds),
|
|
4512
4524
|
jsonbArg(item.requestContext),
|
|
4513
4525
|
jsonbArg(item.metadata),
|
|
4514
4526
|
jsonbArg(item.source),
|