@mastra/mcp-docs-server 1.0.0-beta.14 → 1.0.0-beta.16
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/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +41 -41
- package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +51 -51
- package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +85 -85
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Fconvex.md +258 -0
- package/.docs/organized/changelogs/%40mastra%2Fcore.md +338 -338
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +27 -27
- package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +67 -67
- package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Fevals.md +10 -10
- package/.docs/organized/changelogs/%40mastra%2Ffastembed.md +6 -0
- package/.docs/organized/changelogs/%40mastra%2Flance.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Flibsql.md +235 -235
- package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fmcp.md +30 -30
- package/.docs/organized/changelogs/%40mastra%2Fmemory.md +168 -168
- package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +259 -259
- package/.docs/organized/changelogs/%40mastra%2Fmssql.md +259 -259
- package/.docs/organized/changelogs/%40mastra%2Fpg.md +279 -279
- package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +108 -108
- package/.docs/organized/changelogs/%40mastra%2Freact.md +77 -77
- package/.docs/organized/changelogs/%40mastra%2Fserver.md +180 -180
- package/.docs/organized/changelogs/%40mastra%2Fupstash.md +235 -235
- package/.docs/organized/changelogs/create-mastra.md +11 -11
- package/.docs/organized/changelogs/mastra.md +40 -40
- package/.docs/organized/code-examples/agent-v6.md +70 -11
- package/.docs/organized/code-examples/client-side-tools.md +1 -1
- package/.docs/raw/agents/adding-voice.mdx +8 -3
- package/.docs/raw/deployment/overview.mdx +3 -4
- package/.docs/raw/deployment/workflow-runners.mdx +14 -0
- package/.docs/raw/getting-started/studio.mdx +1 -1
- package/.docs/raw/guides/deployment/inngest.mdx +198 -140
- package/.docs/raw/guides/migrations/upgrade-to-v1/memory.mdx +11 -3
- package/.docs/raw/guides/migrations/upgrade-to-v1/processors.mdx +11 -0
- package/.docs/raw/guides/migrations/upgrade-to-v1/storage.mdx +68 -0
- package/.docs/raw/mastra-cloud/deployment.mdx +39 -0
- package/.docs/raw/mastra-cloud/observability.mdx +9 -15
- package/.docs/raw/mastra-cloud/overview.mdx +14 -44
- package/.docs/raw/mastra-cloud/setup.mdx +64 -0
- package/.docs/raw/mastra-cloud/studio.mdx +35 -0
- package/.docs/raw/reference/client-js/workflows.mdx +15 -0
- package/.docs/raw/reference/logging/pino-logger.mdx +1 -1
- package/.docs/raw/reference/processors/token-limiter-processor.mdx +39 -18
- package/.docs/raw/reference/storage/cloudflare-d1.mdx +4 -2
- package/.docs/raw/reference/storage/composite.mdx +223 -0
- package/.docs/raw/reference/storage/lance.mdx +3 -2
- package/.docs/raw/reference/storage/libsql.mdx +5 -2
- package/.docs/raw/reference/storage/mongodb.mdx +4 -2
- package/.docs/raw/reference/storage/mssql.mdx +4 -2
- package/.docs/raw/reference/storage/postgresql.mdx +4 -2
- package/.docs/raw/reference/tools/mcp-server.mdx +9 -0
- package/.docs/raw/reference/workflows/run-methods/cancel.mdx +51 -3
- package/.docs/raw/reference/workflows/run.mdx +8 -2
- package/.docs/raw/voice/overview.mdx +1 -1
- package/.docs/raw/workflows/overview.mdx +1 -1
- package/.docs/raw/workflows/snapshots.mdx +2 -1
- package/CHANGELOG.md +15 -0
- package/package.json +5 -5
- package/.docs/raw/mastra-cloud/dashboard.mdx +0 -96
- package/.docs/raw/mastra-cloud/setting-up.mdx +0 -106
- package/.docs/raw/workflows/inngest-workflow.mdx +0 -362
|
@@ -1,46 +1,40 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: "
|
|
2
|
+
title: "Observability | Mastra Cloud"
|
|
3
3
|
description: Monitoring and debugging tools for Mastra Cloud deployments
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Observability
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Cloud provides observability for production applications, giving you insight into how your agents and workflows behave. Observability works whether your application is deployed to Mastra Cloud, running locally, or hosted on your own infrastructure. Any Mastra project can send traces and logs to the platform regardless of where it's running.
|
|
9
9
|
|
|
10
10
|
For details on configuring observability, see the [Cloud Exporter](/docs/v1/observability/tracing/exporters/cloud) docs.
|
|
11
11
|
|
|
12
12
|
## Traces
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Traces are available for both agents and workflows by enabling [observability](/docs/v1/observability/tracing/overview) using one of the [supported providers](/docs/v1/observability/tracing/overview#exporters).
|
|
15
15
|
|
|
16
16
|
### Agents
|
|
17
17
|
|
|
18
|
-
With observability enabled, you can view detailed outputs from your agents in the **Traces** section in Studio.
|
|
18
|
+
With observability enabled, you can view detailed outputs from your agents in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
|
|
19
19
|
|
|
20
20
|

|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
Agent traces break a run into clear steps, model calls, tool calls, and intermediate chunks, each with timing, inputs, outputs, and errors. You can drill into any span to inspect prompts, token usage, and results, making it easy to diagnose issues and understand how the agent produced its output.
|
|
22
|
+
Agent traces break a run into clear steps: model calls, tool calls, and intermediate chunks. Each includes timing, inputs, outputs, and errors. Drill into any span to inspect prompts, token usage, and results.
|
|
25
23
|
|
|
26
24
|
### Workflows
|
|
27
25
|
|
|
28
|
-
With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in Studio.
|
|
26
|
+
With observability enabled, you can view detailed outputs from your workflows in the **Traces** section in [Studio](/docs/v1/mastra-cloud/studio).
|
|
29
27
|
|
|
30
28
|

|
|
31
29
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls inside the workflow. You can inspect inputs, outputs, and errors for every step, making it easy to debug long-running or multi-step processes and understand how data flows through the workflow.
|
|
30
|
+
Workflow traces capture each step in the run, including transitions, branching, timing, and any tool calls. Inspect inputs, outputs, and errors for every step to debug long-running or multi-step processes.
|
|
35
31
|
|
|
36
32
|
## Logs
|
|
37
33
|
|
|
38
|
-
|
|
34
|
+
The **Logs** page in the [project dashboard](/docs/v1/mastra-cloud/deployment#project-dashboard) displays detailed information for debugging and monitoring your application's behavior.
|
|
39
35
|
|
|
40
36
|

|
|
41
37
|
|
|
42
|
-
Key features:
|
|
43
|
-
|
|
44
38
|
Each log entry includes its severity level and a detailed message showing agent, workflow, or storage activity.
|
|
45
39
|
|
|
46
40
|
## Next steps
|
|
@@ -5,57 +5,27 @@ description: Deployment and monitoring service for Mastra applications
|
|
|
5
5
|
|
|
6
6
|
# Mastra Cloud
|
|
7
7
|
|
|
8
|
-
[Mastra Cloud](https://mastra.ai
|
|
8
|
+
[Mastra Cloud](https://cloud.mastra.ai) is a platform for deploying, managing, and monitoring Mastra applications. [Import your project](/docs/v1/mastra-cloud/setup) to get started.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Studio
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Run [Studio](/docs/v1/mastra-cloud/studio) in the cloud and share access with your team via a link. Team members can test agents and workflows, tweak system prompts, and give feedback without running the project locally.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Deploy
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
Enable [deployments](/docs/v1/mastra-cloud/deployment) and Mastra Cloud hosts your server for you. Connect your GitHub repository for automatic deployments whenever you push to your configured branch. Mastra Cloud exposes your agents, tools, and workflows as REST API endpoints.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Once deployed, the project dashboard gives you visibility into:
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
- Deployment status and history
|
|
21
|
+
- Build logs and configuration
|
|
22
|
+
- Environment variables and settings
|
|
21
23
|
|
|
22
|
-
|
|
24
|
+
## Observability
|
|
23
25
|
|
|
24
|
-
|
|
26
|
+
[Observability](/docs/v1/mastra-cloud/observability) provides insight into how your agents and workflows behave in production. View detailed traces of agent runs, workflow executions, and logs to debug issues and understand performance.
|
|
25
27
|
|
|
26
|
-
|
|
28
|
+
:::info
|
|
29
|
+
You don’t need to deploy to Mastra Cloud to use Observability. You can send traces to Mastra from any environment
|
|
30
|
+
:::
|
|
27
31
|
|
|
28
|
-
The Project Dashboard gives you an overview of your application's status and deployments, with access to logs and a Studio for testing agents and workflows.
|
|
29
|
-
|
|
30
|
-
## Project structure
|
|
31
|
-
|
|
32
|
-
Use a standard Mastra project structure for proper detection and deployment.
|
|
33
|
-
|
|
34
|
-
```shell
|
|
35
|
-
src
|
|
36
|
-
└── mastra
|
|
37
|
-
├── agents
|
|
38
|
-
│ └── agent-name.ts
|
|
39
|
-
├── tools
|
|
40
|
-
│ └── tool-name.ts
|
|
41
|
-
├── workflows
|
|
42
|
-
│ └── workflow-name.ts
|
|
43
|
-
└── index.ts
|
|
44
|
-
package.json
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Mastra Cloud scans your repository for:
|
|
48
|
-
|
|
49
|
-
- **Agents**: Defined using: `new Agent({...})`
|
|
50
|
-
- **Tools**: Defined using: `createTool({...})`
|
|
51
|
-
- **Workflows**: Defined using: `createWorkflow({...})`
|
|
52
|
-
- **Steps**: Defined using: `createStep({...})`
|
|
53
|
-
- **Environment Variables**: API keys and configuration variables
|
|
54
|
-
|
|
55
|
-
## Technical implementation
|
|
56
|
-
|
|
57
|
-
Mastra Cloud is purpose-built for Mastra agents, tools, and workflows. It handles long-running requests, records detailed traces for every execution, and includes built-in support for evals.
|
|
58
|
-
|
|
59
|
-
## Next steps
|
|
60
|
-
|
|
61
|
-
- [Setting Up and Deploying](/docs/v1/mastra-cloud/setting-up)
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Setup | Mastra Cloud"
|
|
3
|
+
description: Import your Mastra project to Mastra Cloud
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import Steps from "@site/src/components/Steps";
|
|
7
|
+
import StepItem from "@site/src/components/StepItem";
|
|
8
|
+
|
|
9
|
+
# Setup
|
|
10
|
+
|
|
11
|
+
Import your Mastra project to [Mastra Cloud](https://cloud.mastra.ai) to use [Studio](/docs/v1/mastra-cloud/studio) and optionally [deploy](/docs/v1/mastra-cloud/deployment) your agent.
|
|
12
|
+
|
|
13
|
+
## Before you begin
|
|
14
|
+
|
|
15
|
+
- [Sign in](https://cloud.mastra.ai) to Cloud
|
|
16
|
+
- Push your [Mastra project](/docs/v1/getting-started/start) to GitHub
|
|
17
|
+
|
|
18
|
+
## Options
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+

|
|
22
|
+
|
|
23
|
+
When you create a new project, you can choose from three options:
|
|
24
|
+
|
|
25
|
+
1. **Create from GitHub** - Import a Mastra project from GitHub
|
|
26
|
+
2. **Create from your server** - Connect a self-hosted Mastra instance to [Studio](/docs/v1/mastra-cloud/studio)
|
|
27
|
+
3. **Create from template** - Start from a [pre-built template](https://mastra.ai/templates)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
To create a project from GitHub, follow these steps:
|
|
31
|
+
|
|
32
|
+
## Create from GitHub
|
|
33
|
+
|
|
34
|
+
<Steps>
|
|
35
|
+
|
|
36
|
+
<StepItem>
|
|
37
|
+
Connect to GitHub when prompted
|
|
38
|
+
|
|
39
|
+

|
|
40
|
+
</StepItem>
|
|
41
|
+
|
|
42
|
+
<StepItem>
|
|
43
|
+
Search for your repository and click **Import**
|
|
44
|
+
|
|
45
|
+

|
|
46
|
+
</StepItem>
|
|
47
|
+
|
|
48
|
+
<StepItem>
|
|
49
|
+
Configure your project settings. Mastra Cloud auto-detects most settings, but you'll still need to enter the environment variables for your configured [model provider](/models/v1):
|
|
50
|
+
|
|
51
|
+

|
|
52
|
+
</StepItem>
|
|
53
|
+
|
|
54
|
+
<StepItem>
|
|
55
|
+
|
|
56
|
+
Click **Create Project**
|
|
57
|
+
</StepItem>
|
|
58
|
+
</Steps>
|
|
59
|
+
|
|
60
|
+
## Next steps
|
|
61
|
+
|
|
62
|
+
Once your project is imported, [Studio](/docs/v1/mastra-cloud/studio) automatically creates a sandbox where you can interact with your agents and share access with your team.
|
|
63
|
+
|
|
64
|
+
When you're ready for production, enable [Deployment](/docs/v1/mastra-cloud/deployment) settings and hit deploy!
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Studio | Mastra Cloud"
|
|
3
|
+
description: Run Studio in the cloud for team collaboration
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import YouTube from "@site/src/components/YouTube-player";
|
|
7
|
+
|
|
8
|
+
# Studio
|
|
9
|
+
|
|
10
|
+
<YouTube id="ojGu6Bi4wYk" />
|
|
11
|
+
|
|
12
|
+
Mastra Cloud provides a hosted version of [Studio](/docs/v1/getting-started/studio) that gives your team a shared environment for interacting with and testing your agents. Team members can chat with agents, review traces, give feedback, and tweak system prompts - without needing to run the project locally.
|
|
13
|
+
|
|
14
|
+
[Set up your project](/docs/v1/mastra-cloud/setup) to access Studio in the cloud.
|
|
15
|
+
|
|
16
|
+
See the [Studio documentation](/docs/v1/getting-started/studio) for details on features like the Agents playground, Workflows runner, Tools testing, and MCP Servers.
|
|
17
|
+
|
|
18
|
+
:::note
|
|
19
|
+
You don't need to deploy your agent to use Studio. Studio runs in a sandbox environment separate from your production deployment
|
|
20
|
+
:::
|
|
21
|
+
|
|
22
|
+
## Sharing access
|
|
23
|
+
|
|
24
|
+
To invite team members, go to [Mastra Cloud](https://cloud.mastra.ai), click **Team Settings**, then **Members** to add them. Once invited, they can sign in and access your project's Studio.
|
|
25
|
+
|
|
26
|
+

|
|
27
|
+
|
|
28
|
+
:::warning
|
|
29
|
+
Team members can view environment variables and delete projects. Only invite people you trust.
|
|
30
|
+
:::
|
|
31
|
+
|
|
32
|
+
## Next steps
|
|
33
|
+
|
|
34
|
+
- [Deployment](/docs/v1/mastra-cloud/deployment) - Manage deployments and settings
|
|
35
|
+
- [Observability](/docs/v1/mastra-cloud/observability) - Monitor traces and logs
|
|
@@ -145,6 +145,21 @@ await run.resume({
|
|
|
145
145
|
});
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
+
### cancel()
|
|
149
|
+
|
|
150
|
+
Cancel a running workflow:
|
|
151
|
+
|
|
152
|
+
```typescript
|
|
153
|
+
const run = await workflow.createRun({ runId: existingRunId });
|
|
154
|
+
|
|
155
|
+
const result = await run.cancel();
|
|
156
|
+
// Returns: { message: 'Workflow run canceled' }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
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.).
|
|
160
|
+
|
|
161
|
+
See the [Run.cancel()](/reference/v1/workflows/run-methods/cancel) reference for detailed information about how cancellation works and how to write steps that respond to cancellation.
|
|
162
|
+
|
|
148
163
|
### stream()
|
|
149
164
|
|
|
150
165
|
Stream workflow execution for real-time updates:
|
|
@@ -7,7 +7,7 @@ description: Documentation for PinoLogger, which provides methods to record even
|
|
|
7
7
|
|
|
8
8
|
A Logger instance is created using `new PinoLogger()` and provides methods to record events at various severity levels.
|
|
9
9
|
|
|
10
|
-
When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/
|
|
10
|
+
When deploying to Mastra Cloud, logs are displayed on the [Logs](/docs/v1/mastra-cloud/observability#logs) page. In self-hosted or custom environments, logs can be directed to files or external services depending on the configured transports.
|
|
11
11
|
|
|
12
12
|
## Usage example
|
|
13
13
|
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Reference: Token Limiter Processor | Processors"
|
|
3
|
-
description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in
|
|
3
|
+
description: "Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# TokenLimiterProcessor
|
|
7
7
|
|
|
8
|
-
The `TokenLimiterProcessor`
|
|
8
|
+
The `TokenLimiterProcessor` limits the number of tokens in messages. It can be used as both an input and output processor:
|
|
9
|
+
|
|
10
|
+
- **Input processor**: Filters historical messages to fit within the context window, prioritizing recent messages
|
|
11
|
+
- **Output processor**: Limits generated response tokens via streaming or non-streaming with configurable strategies for handling exceeded limits
|
|
9
12
|
|
|
10
13
|
## Usage example
|
|
11
14
|
|
|
@@ -82,6 +85,12 @@ const processor = new TokenLimiterProcessor({
|
|
|
82
85
|
description: "Optional processor display name",
|
|
83
86
|
isOptional: true,
|
|
84
87
|
},
|
|
88
|
+
{
|
|
89
|
+
name: "processInput",
|
|
90
|
+
type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
|
|
91
|
+
description: "Filters input messages to fit within token limit, prioritizing recent messages while preserving system messages",
|
|
92
|
+
isOptional: false,
|
|
93
|
+
},
|
|
85
94
|
{
|
|
86
95
|
name: "processOutputStream",
|
|
87
96
|
type: "(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>",
|
|
@@ -90,22 +99,10 @@ const processor = new TokenLimiterProcessor({
|
|
|
90
99
|
},
|
|
91
100
|
{
|
|
92
101
|
name: "processOutputResult",
|
|
93
|
-
type: "(args: { messages:
|
|
102
|
+
type: "(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>",
|
|
94
103
|
description: "Processes final output results to limit token count in non-streaming scenarios",
|
|
95
104
|
isOptional: false,
|
|
96
105
|
},
|
|
97
|
-
{
|
|
98
|
-
name: "reset",
|
|
99
|
-
type: "() => void",
|
|
100
|
-
description: "Reset the token counter (useful for testing or reusing the processor)",
|
|
101
|
-
isOptional: false,
|
|
102
|
-
},
|
|
103
|
-
{
|
|
104
|
-
name: "getCurrentTokens",
|
|
105
|
-
type: "() => number",
|
|
106
|
-
description: "Get the current token count",
|
|
107
|
-
isOptional: false,
|
|
108
|
-
},
|
|
109
106
|
{
|
|
110
107
|
name: "getMaxTokens",
|
|
111
108
|
type: "() => number",
|
|
@@ -117,14 +114,38 @@ const processor = new TokenLimiterProcessor({
|
|
|
117
114
|
|
|
118
115
|
## Extended usage example
|
|
119
116
|
|
|
120
|
-
|
|
117
|
+
### As an input processor (limit context window)
|
|
118
|
+
|
|
119
|
+
Use `inputProcessors` to limit historical messages sent to the model, which helps stay within context window limits:
|
|
120
|
+
|
|
121
|
+
```typescript title="src/mastra/agents/context-limited-agent.ts"
|
|
122
|
+
import { Agent } from "@mastra/core/agent";
|
|
123
|
+
import { Memory } from "@mastra/memory";
|
|
124
|
+
import { TokenLimiterProcessor } from "@mastra/core/processors";
|
|
125
|
+
|
|
126
|
+
export const agent = new Agent({
|
|
127
|
+
name: "context-limited-agent",
|
|
128
|
+
instructions: "You are a helpful assistant",
|
|
129
|
+
model: "openai/gpt-4o",
|
|
130
|
+
memory: new Memory({ /* ... */ }),
|
|
131
|
+
inputProcessors: [
|
|
132
|
+
new TokenLimiterProcessor({ limit: 4000 }) // Limits historical messages to ~4000 tokens
|
|
133
|
+
]
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### As an output processor (limit response length)
|
|
138
|
+
|
|
139
|
+
Use `outputProcessors` to limit the length of generated responses:
|
|
140
|
+
|
|
141
|
+
```typescript title="src/mastra/agents/response-limited-agent.ts"
|
|
121
142
|
import { Agent } from "@mastra/core/agent";
|
|
122
143
|
import { TokenLimiterProcessor } from "@mastra/core/processors";
|
|
123
144
|
|
|
124
145
|
export const agent = new Agent({
|
|
125
|
-
name: "limited-agent",
|
|
146
|
+
name: "response-limited-agent",
|
|
126
147
|
instructions: "You are a helpful assistant",
|
|
127
|
-
model: "openai/gpt-
|
|
148
|
+
model: "openai/gpt-4o",
|
|
128
149
|
outputProcessors: [
|
|
129
150
|
new TokenLimiterProcessor({
|
|
130
151
|
limit: 1000,
|
|
@@ -118,14 +118,16 @@ If you're using storage directly without Mastra, you must call `init()` explicit
|
|
|
118
118
|
import { D1Store } from "@mastra/cloudflare-d1";
|
|
119
119
|
|
|
120
120
|
const storage = new D1Store({
|
|
121
|
+
id: 'd1-storage',
|
|
121
122
|
binding: D1Database,
|
|
122
123
|
});
|
|
123
124
|
|
|
124
125
|
// Required when using storage directly
|
|
125
126
|
await storage.init();
|
|
126
127
|
|
|
127
|
-
//
|
|
128
|
-
await storage.
|
|
128
|
+
// Access domain-specific stores via getStore()
|
|
129
|
+
const memoryStore = await storage.getStore('memory');
|
|
130
|
+
const thread = await memoryStore?.getThreadById({ threadId: "..." });
|
|
129
131
|
```
|
|
130
132
|
|
|
131
133
|
:::warning
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Reference: Storage Composition | Storage"
|
|
3
|
+
description: Documentation for combining multiple storage backends in Mastra.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Storage Composition
|
|
7
|
+
|
|
8
|
+
MastraStorage can compose storage domains from different adapters. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
MastraStorage is included in `@mastra/core`:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @mastra/core@beta
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
You'll also need to install the storage adapters you want to compose:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @mastra/pg@beta @mastra/libsql@beta
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Basic composition
|
|
27
|
+
|
|
28
|
+
Import domain classes directly from each store package and compose them:
|
|
29
|
+
|
|
30
|
+
```typescript
|
|
31
|
+
import { MastraStorage } from "@mastra/core/storage";
|
|
32
|
+
import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
|
|
33
|
+
import { MemoryLibSQL } from "@mastra/libsql";
|
|
34
|
+
import { Mastra } from "@mastra/core";
|
|
35
|
+
|
|
36
|
+
const mastra = new Mastra({
|
|
37
|
+
storage: new MastraStorage({
|
|
38
|
+
id: "composite",
|
|
39
|
+
domains: {
|
|
40
|
+
memory: new MemoryLibSQL({ url: "file:./local.db" }),
|
|
41
|
+
workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
|
|
42
|
+
scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
|
|
43
|
+
},
|
|
44
|
+
}),
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### With a default storage
|
|
49
|
+
|
|
50
|
+
Use `default` to specify a fallback storage, then override specific domains:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { MastraStorage } from "@mastra/core/storage";
|
|
54
|
+
import { PostgresStore } from "@mastra/pg";
|
|
55
|
+
import { MemoryLibSQL } from "@mastra/libsql";
|
|
56
|
+
import { Mastra } from "@mastra/core";
|
|
57
|
+
|
|
58
|
+
const pgStore = new PostgresStore({
|
|
59
|
+
id: "pg",
|
|
60
|
+
connectionString: process.env.DATABASE_URL,
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
const mastra = new Mastra({
|
|
64
|
+
storage: new MastraStorage({
|
|
65
|
+
id: "composite",
|
|
66
|
+
default: pgStore,
|
|
67
|
+
domains: {
|
|
68
|
+
memory: new MemoryLibSQL({ url: "file:./local.db" }),
|
|
69
|
+
},
|
|
70
|
+
}),
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Options
|
|
75
|
+
|
|
76
|
+
<PropertiesTable
|
|
77
|
+
content={[
|
|
78
|
+
{
|
|
79
|
+
name: "id",
|
|
80
|
+
type: "string",
|
|
81
|
+
description: "Unique identifier for this storage instance.",
|
|
82
|
+
isOptional: false,
|
|
83
|
+
},
|
|
84
|
+
{
|
|
85
|
+
name: "default",
|
|
86
|
+
type: "MastraStorage",
|
|
87
|
+
description:
|
|
88
|
+
"Default storage adapter. Domains not explicitly specified in `domains` will use this storage's domains as fallbacks.",
|
|
89
|
+
isOptional: true,
|
|
90
|
+
},
|
|
91
|
+
{
|
|
92
|
+
name: "domains",
|
|
93
|
+
type: "object",
|
|
94
|
+
description:
|
|
95
|
+
"Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over the default storage.",
|
|
96
|
+
isOptional: true,
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
name: "domains.memory",
|
|
100
|
+
type: "MemoryStorage",
|
|
101
|
+
description: "Storage for threads, messages, and resources.",
|
|
102
|
+
isOptional: true,
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
name: "domains.workflows",
|
|
106
|
+
type: "WorkflowsStorage",
|
|
107
|
+
description: "Storage for workflow snapshots.",
|
|
108
|
+
isOptional: true,
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
name: "domains.scores",
|
|
112
|
+
type: "ScoresStorage",
|
|
113
|
+
description: "Storage for evaluation scores.",
|
|
114
|
+
isOptional: true,
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
name: "domains.observability",
|
|
118
|
+
type: "ObservabilityStorage",
|
|
119
|
+
description: "Storage for traces and spans.",
|
|
120
|
+
isOptional: true,
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
name: "domains.agents",
|
|
124
|
+
type: "AgentsStorage",
|
|
125
|
+
description: "Storage for stored agent configurations.",
|
|
126
|
+
isOptional: true,
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
name: "disableInit",
|
|
130
|
+
type: "boolean",
|
|
131
|
+
description:
|
|
132
|
+
"When true, automatic initialization is disabled. You must call init() explicitly.",
|
|
133
|
+
isOptional: true,
|
|
134
|
+
},
|
|
135
|
+
]}
|
|
136
|
+
/>
|
|
137
|
+
|
|
138
|
+
## Initialization
|
|
139
|
+
|
|
140
|
+
MastraStorage initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
|
|
141
|
+
|
|
142
|
+
```typescript
|
|
143
|
+
import { MastraStorage } from "@mastra/core/storage";
|
|
144
|
+
import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
|
|
145
|
+
import { Mastra } from "@mastra/core";
|
|
146
|
+
|
|
147
|
+
const storage = new MastraStorage({
|
|
148
|
+
id: "composite",
|
|
149
|
+
domains: {
|
|
150
|
+
memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
|
|
151
|
+
workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
|
|
152
|
+
scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
|
|
156
|
+
const mastra = new Mastra({
|
|
157
|
+
storage, // init() called automatically
|
|
158
|
+
});
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
If using storage directly, call `init()` explicitly:
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
const storage = new MastraStorage({
|
|
165
|
+
id: "composite",
|
|
166
|
+
domains: {
|
|
167
|
+
memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
|
|
168
|
+
},
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
await storage.init();
|
|
172
|
+
|
|
173
|
+
// Access domain-specific stores via getStore()
|
|
174
|
+
const memoryStore = await storage.getStore("memory");
|
|
175
|
+
const thread = await memoryStore?.getThreadById({ threadId: "..." });
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## Use Cases
|
|
179
|
+
|
|
180
|
+
### Separate databases for different workloads
|
|
181
|
+
|
|
182
|
+
Use a local database for development while keeping production data in a managed service:
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
import { MastraStorage } from "@mastra/core/storage";
|
|
186
|
+
import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
|
|
187
|
+
import { MemoryLibSQL } from "@mastra/libsql";
|
|
188
|
+
|
|
189
|
+
const storage = new MastraStorage({
|
|
190
|
+
id: "composite",
|
|
191
|
+
domains: {
|
|
192
|
+
// Use local SQLite for development, PostgreSQL for production
|
|
193
|
+
memory:
|
|
194
|
+
process.env.NODE_ENV === "development"
|
|
195
|
+
? new MemoryLibSQL({ url: "file:./dev.db" })
|
|
196
|
+
: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
|
|
197
|
+
workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
|
|
198
|
+
scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
|
|
199
|
+
},
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Specialized storage for observability
|
|
204
|
+
|
|
205
|
+
Use a time-series database for traces while keeping other data in PostgreSQL:
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
import { MastraStorage } from "@mastra/core/storage";
|
|
209
|
+
import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
|
|
210
|
+
import { ObservabilityStorageClickhouse } from "@mastra/clickhouse";
|
|
211
|
+
|
|
212
|
+
const storage = new MastraStorage({
|
|
213
|
+
id: "composite",
|
|
214
|
+
domains: {
|
|
215
|
+
memory: new MemoryPG({ connectionString: process.env.DATABASE_URL }),
|
|
216
|
+
workflows: new WorkflowsPG({ connectionString: process.env.DATABASE_URL }),
|
|
217
|
+
scores: new ScoresPG({ connectionString: process.env.DATABASE_URL }),
|
|
218
|
+
observability: new ObservabilityStorageClickhouse({
|
|
219
|
+
url: process.env.CLICKHOUSE_URL,
|
|
220
|
+
}),
|
|
221
|
+
},
|
|
222
|
+
});
|
|
223
|
+
```
|
|
@@ -98,8 +98,9 @@ const storage = await LanceStorage.create("my-storage", "/path/to/db");
|
|
|
98
98
|
// Required when using storage directly
|
|
99
99
|
await storage.init();
|
|
100
100
|
|
|
101
|
-
//
|
|
102
|
-
await storage.
|
|
101
|
+
// Access domain-specific stores via getStore()
|
|
102
|
+
const memoryStore = await storage.getStore('memory');
|
|
103
|
+
const thread = await memoryStore?.getThreadById({ threadId: "..." });
|
|
103
104
|
```
|
|
104
105
|
|
|
105
106
|
:::warning
|
|
@@ -115,7 +115,7 @@ const mastra = new Mastra({
|
|
|
115
115
|
|
|
116
116
|
If using storage directly without Mastra, call `init()` explicitly:
|
|
117
117
|
|
|
118
|
-
```typescript
|
|
118
|
+
```typescript
|
|
119
119
|
import { LibSQLStore } from "@mastra/libsql";
|
|
120
120
|
|
|
121
121
|
const storage = new LibSQLStore({
|
|
@@ -124,5 +124,8 @@ const storage = new LibSQLStore({
|
|
|
124
124
|
});
|
|
125
125
|
|
|
126
126
|
await storage.init();
|
|
127
|
-
|
|
127
|
+
|
|
128
|
+
// Access domain-specific stores via getStore()
|
|
129
|
+
const memoryStore = await storage.getStore('memory');
|
|
130
|
+
const thread = await memoryStore?.getThreadById({ threadId: "..." });
|
|
128
131
|
```
|
|
@@ -117,6 +117,7 @@ If you're using storage directly without Mastra, you must call `init()` explicit
|
|
|
117
117
|
import { MongoDBStore } from "@mastra/mongodb";
|
|
118
118
|
|
|
119
119
|
const storage = new MongoDBStore({
|
|
120
|
+
id: 'mongodb-storage',
|
|
120
121
|
url: process.env.MONGODB_URL,
|
|
121
122
|
dbName: process.env.MONGODB_DATABASE,
|
|
122
123
|
});
|
|
@@ -124,8 +125,9 @@ const storage = new MongoDBStore({
|
|
|
124
125
|
// Required when using storage directly
|
|
125
126
|
await storage.init();
|
|
126
127
|
|
|
127
|
-
//
|
|
128
|
-
await storage.
|
|
128
|
+
// Access domain-specific stores via getStore()
|
|
129
|
+
const memoryStore = await storage.getStore('memory');
|
|
130
|
+
const thread = await memoryStore?.getThreadById({ threadId: "..." });
|
|
129
131
|
```
|
|
130
132
|
|
|
131
133
|
:::warning
|