@mastra/mcp-docs-server 0.13.29 → 0.13.30-alpha.1
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/%40internal%2Fchangeset-cli.md +2 -0
- package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +9 -9
- package/.docs/organized/changelogs/%40internal%2Ftypes-builder.md +2 -0
- package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +31 -31
- package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +36 -0
- package/.docs/organized/changelogs/%40mastra%2Fastra.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fchroma.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +28 -28
- package/.docs/organized/changelogs/%40mastra%2Fcloud.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fcore.md +106 -106
- package/.docs/organized/changelogs/%40mastra%2Fcouchbase.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +37 -37
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +25 -25
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +25 -25
- package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +25 -25
- package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +49 -49
- package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fevals.md +33 -33
- package/.docs/organized/changelogs/%40mastra%2Flance.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Flibsql.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Floggers.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +23 -23
- package/.docs/organized/changelogs/%40mastra%2Fmcp-registry-registry.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fmcp.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fmemory.md +36 -36
- package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fmssql.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fopensearch.md +17 -17
- package/.docs/organized/changelogs/%40mastra%2Fpg.md +31 -31
- package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +67 -67
- package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Frag.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Freact.md +37 -0
- package/.docs/organized/changelogs/%40mastra%2Fs3vectors.md +15 -0
- package/.docs/organized/changelogs/%40mastra%2Fserver.md +37 -37
- package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fupstash.md +19 -19
- package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +17 -17
- package/.docs/organized/changelogs/%40mastra%2Fvoice-azure.md +18 -18
- package/.docs/organized/changelogs/%40mastra%2Fvoice-cloudflare.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-deepgram.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-elevenlabs.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-gladia.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-google-gemini-live.md +15 -0
- package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-murf.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-openai-realtime.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-openai.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-playai.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-sarvam.md +16 -16
- package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md +16 -16
- package/.docs/organized/changelogs/create-mastra.md +35 -35
- package/.docs/organized/changelogs/mastra.md +63 -63
- package/.docs/organized/code-examples/agent.md +26 -7
- package/.docs/organized/code-examples/agui.md +4 -4
- package/.docs/organized/code-examples/ai-elements.md +1 -1
- package/.docs/organized/code-examples/ai-sdk-useChat.md +2 -2
- package/.docs/organized/code-examples/ai-sdk-v5.md +2 -2
- package/.docs/organized/code-examples/assistant-ui.md +2 -2
- package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md +2 -2
- package/.docs/organized/code-examples/bird-checker-with-nextjs.md +2 -2
- package/.docs/organized/code-examples/client-side-tools.md +4 -4
- package/.docs/organized/code-examples/crypto-chatbot.md +2 -2
- package/.docs/organized/code-examples/heads-up-game.md +2 -2
- package/.docs/organized/code-examples/openapi-spec-writer.md +2 -2
- package/.docs/raw/agents/adding-voice.mdx +118 -25
- package/.docs/raw/agents/agent-memory.mdx +73 -89
- package/.docs/raw/agents/guardrails.mdx +1 -1
- package/.docs/raw/agents/networks.mdx +12 -6
- package/.docs/raw/agents/overview.mdx +46 -11
- package/.docs/raw/agents/using-tools.mdx +95 -0
- package/.docs/raw/deployment/overview.mdx +9 -11
- package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx +7 -4
- package/.docs/raw/frameworks/servers/express.mdx +2 -2
- package/.docs/raw/getting-started/installation.mdx +34 -132
- package/.docs/raw/getting-started/mcp-docs-server.mdx +13 -1
- package/.docs/raw/index.mdx +49 -14
- package/.docs/raw/observability/ai-tracing/exporters/otel.mdx +3 -0
- package/.docs/raw/reference/agents/generateLegacy.mdx +4 -4
- package/.docs/raw/reference/observability/ai-tracing/exporters/otel.mdx +6 -0
- package/.docs/raw/reference/scorers/answer-relevancy.mdx +105 -7
- package/.docs/raw/reference/scorers/answer-similarity.mdx +266 -16
- package/.docs/raw/reference/scorers/bias.mdx +107 -6
- package/.docs/raw/reference/scorers/completeness.mdx +131 -8
- package/.docs/raw/reference/scorers/content-similarity.mdx +107 -8
- package/.docs/raw/reference/scorers/context-precision.mdx +234 -18
- package/.docs/raw/reference/scorers/context-relevance.mdx +418 -35
- package/.docs/raw/reference/scorers/faithfulness.mdx +122 -8
- package/.docs/raw/reference/scorers/hallucination.mdx +125 -8
- package/.docs/raw/reference/scorers/keyword-coverage.mdx +141 -9
- package/.docs/raw/reference/scorers/noise-sensitivity.mdx +478 -6
- package/.docs/raw/reference/scorers/prompt-alignment.mdx +351 -102
- package/.docs/raw/reference/scorers/textual-difference.mdx +134 -6
- package/.docs/raw/reference/scorers/tone-consistency.mdx +133 -0
- package/.docs/raw/reference/scorers/tool-call-accuracy.mdx +422 -65
- package/.docs/raw/reference/scorers/toxicity.mdx +125 -7
- package/.docs/raw/reference/streaming/agents/MastraModelOutput.mdx +9 -5
- package/.docs/raw/reference/streaming/agents/streamLegacy.mdx +4 -4
- package/.docs/raw/reference/streaming/workflows/observeStream.mdx +49 -0
- package/.docs/raw/reference/streaming/workflows/observeStreamVNext.mdx +47 -0
- package/.docs/raw/reference/streaming/workflows/resumeStreamVNext.mdx +7 -5
- package/.docs/raw/reference/streaming/workflows/stream.mdx +1 -1
- package/.docs/raw/reference/workflows/workflow.mdx +33 -0
- package/.docs/raw/scorers/custom-scorers.mdx +244 -3
- package/.docs/raw/scorers/overview.mdx +8 -38
- package/.docs/raw/server-db/middleware.mdx +5 -2
- package/.docs/raw/server-db/runtime-context.mdx +178 -0
- package/.docs/raw/streaming/workflow-streaming.mdx +28 -1
- package/.docs/raw/tools-mcp/overview.mdx +25 -7
- package/.docs/raw/workflows/overview.mdx +28 -1
- package/CHANGELOG.md +15 -0
- package/package.json +6 -6
- package/.docs/raw/agents/runtime-context.mdx +0 -103
- package/.docs/raw/agents/using-tools-and-mcp.mdx +0 -241
- package/.docs/raw/getting-started/model-providers.mdx +0 -63
- package/.docs/raw/reference/agents/migration-guide.mdx +0 -291
- package/.docs/raw/tools-mcp/runtime-context.mdx +0 -63
- /package/.docs/raw/{evals → scorers/evals-old-api}/custom-eval.mdx +0 -0
- /package/.docs/raw/{evals → scorers/evals-old-api}/overview.mdx +0 -0
- /package/.docs/raw/{evals → scorers/evals-old-api}/running-in-ci.mdx +0 -0
- /package/.docs/raw/{evals → scorers/evals-old-api}/textual-evals.mdx +0 -0
- /package/.docs/raw/{server-db → workflows}/snapshots.mdx +0 -0
|
@@ -7,48 +7,19 @@ import { Callout } from "nextra/components";
|
|
|
7
7
|
|
|
8
8
|
# Scorers overview
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
While traditional software tests have clear pass/fail conditions, AI outputs are non-deterministic — they can vary with the same input. **Scorers** help bridge this gap by providing quantifiable metrics for measuring agent quality.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
Scorers are automated tests that evaluate Agents outputs using model-graded, rule-based, and statistical methods. Scorers return **scores**: numerical values (typically between 0 and 1) that quantify how well an output meets your evaluation criteria. These scores enable you to objectively track performance, compare different approaches, and identify areas for improvement in your AI systems. Scorers can be customized with your own prompts and scoring functions.
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Scorers can be run in the cloud, capturing real-time results. But scorers can also be part of your CI/CD pipeline, allowing you to test and monitor your agents over time.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
## Types of Scorers
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
2. **analyze** (Optional): Perform evaluation analysis and gather insights
|
|
20
|
-
3. **generateScore** (Required): Convert analysis into a numerical score
|
|
21
|
-
4. **generateReason** (Optional): Generate explanations or justifications for the score
|
|
18
|
+
There are different kinds of scorers, each serving a specific purpose. Here are some common types:
|
|
22
19
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
**preprocess step** - Use when your content is complex or needs preprocessing:
|
|
28
|
-
- Extracting specific elements from complex data structures
|
|
29
|
-
- Cleaning or normalizing text before analysis
|
|
30
|
-
- Parsing multiple claims that need individual evaluation
|
|
31
|
-
- Filtering content to focus evaluation on relevant sections
|
|
32
|
-
|
|
33
|
-
**analyze step** - Use when you need structured evaluation analysis:
|
|
34
|
-
- Gathering insights that inform the scoring decision
|
|
35
|
-
- Breaking down complex evaluation criteria into components
|
|
36
|
-
- Performing detailed analysis that generateScore will use
|
|
37
|
-
- Collecting evidence or reasoning data for transparency
|
|
38
|
-
|
|
39
|
-
**generateScore step** - Always required for converting analysis to scores:
|
|
40
|
-
- Simple scenarios: Direct scoring of input/output pairs
|
|
41
|
-
- Complex scenarios: Converting detailed analysis results into numerical scores
|
|
42
|
-
- Applying business logic and weighting to analysis results
|
|
43
|
-
- The only step that produces the final numerical score
|
|
44
|
-
|
|
45
|
-
**generateReason step** - Use when explanations are important:
|
|
46
|
-
- Users need to understand why a score was assigned
|
|
47
|
-
- Debugging and transparency are critical
|
|
48
|
-
- Compliance or auditing requires explanations
|
|
49
|
-
- Providing actionable feedback for improvement
|
|
50
|
-
|
|
51
|
-
To learn how to create your own Scorers, see [Creating Custom Scorers](/docs/scorers/custom-scorers).
|
|
20
|
+
1. **Textual Scorers**: Evaluate accuracy, reliability, and context understanding of agent responses
|
|
21
|
+
2. **Classification Scorers**: Measure accuracy in categorizing data based on predefined categories
|
|
22
|
+
3. **Prompt Engineering Scorers**: Explore impact of different instructions and input formats
|
|
52
23
|
|
|
53
24
|
## Installation
|
|
54
25
|
|
|
@@ -165,4 +136,3 @@ For more details, see the [Local Dev Playground](/docs/server-db/local-dev-playg
|
|
|
165
136
|
- Learn how to create your own scorers in the [Creating Custom Scorers](/docs/scorers/custom-scorers) guide
|
|
166
137
|
- Explore built-in scorers in the [Off-the-shelf Scorers](/docs/scorers/off-the-shelf-scorers) section
|
|
167
138
|
- Test scorers with the [Local Dev Playground](/docs/server-db/local-dev-playground)
|
|
168
|
-
- See example scorers in the [Examples Overview](/examples) section
|
|
@@ -150,7 +150,6 @@ You can populate `runtimeContext` dynamically in server middleware by extracting
|
|
|
150
150
|
import { Mastra } from "@mastra/core/mastra";
|
|
151
151
|
import { RuntimeContext } from "@mastra/core/runtime-context";
|
|
152
152
|
import { testWeatherAgent } from "./agents/test-weather-agent";
|
|
153
|
-
import { WeatherRuntimeContext } from "./mastra/tools/test-weather-tool";
|
|
154
153
|
|
|
155
154
|
export const mastra = new Mastra({
|
|
156
155
|
agents: { testWeatherAgent },
|
|
@@ -158,7 +157,7 @@ export const mastra = new Mastra({
|
|
|
158
157
|
middleware: [
|
|
159
158
|
async (context, next) => {
|
|
160
159
|
const country = context.req.header("CF-IPCountry");
|
|
161
|
-
const runtimeContext = context.get("runtimeContext")
|
|
160
|
+
const runtimeContext = context.get("runtimeContext");
|
|
162
161
|
|
|
163
162
|
runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
|
|
164
163
|
|
|
@@ -168,3 +167,7 @@ export const mastra = new Mastra({
|
|
|
168
167
|
}
|
|
169
168
|
});
|
|
170
169
|
```
|
|
170
|
+
|
|
171
|
+
# Related
|
|
172
|
+
|
|
173
|
+
- [Runtime Context](./runtime-context.mdx)
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Runtime Context | Agents | Mastra Docs"
|
|
3
|
+
description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
import { Callout } from "nextra/components";
|
|
7
|
+
|
|
8
|
+
# Runtime Context
|
|
9
|
+
|
|
10
|
+
Agents, tools, and workflows can all accept `RuntimeContext` as a parameter, making request-specific values available to the underlying primitives.
|
|
11
|
+
|
|
12
|
+
## When to use `RuntimeContext`
|
|
13
|
+
|
|
14
|
+
Use `RuntimeContext` when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
|
|
15
|
+
|
|
16
|
+
<Callout>
|
|
17
|
+
**Note:** `RuntimeContext` is primarily used for passing data into specific
|
|
18
|
+
requests. It's distinct from agent memory, which handles conversation
|
|
19
|
+
history and state persistence across multiple calls.
|
|
20
|
+
</Callout>
|
|
21
|
+
|
|
22
|
+
## Setting values
|
|
23
|
+
|
|
24
|
+
Pass `runtimeContext` into an agent, workflow, or tool call to make values available to all underlying primitives during execution. Use `.set()` to define values before making the call.
|
|
25
|
+
|
|
26
|
+
The `.set()` method takes two arguments:
|
|
27
|
+
|
|
28
|
+
1. **key**: The name used to identify the value.
|
|
29
|
+
2. **value**: The data to associate with that key.
|
|
30
|
+
|
|
31
|
+
```typescript {7,9,13,21,28} showLineNumbers
|
|
32
|
+
import { RuntimeContext } from "@mastra/core/runtime-context";
|
|
33
|
+
|
|
34
|
+
export type UserTier = {
|
|
35
|
+
"user-tier": "enterprise" | "pro";
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
const runtimeContext = new RuntimeContext<UserTier>();
|
|
39
|
+
|
|
40
|
+
runtimeContext.set("user-tier", "enterprise");
|
|
41
|
+
|
|
42
|
+
const agent = mastra.getAgent("weatherAgent");
|
|
43
|
+
await agent.generate("What's the weather in London?", {
|
|
44
|
+
runtimeContext
|
|
45
|
+
})
|
|
46
|
+
|
|
47
|
+
const run = await mastra.getWorkflow("weatherWorkflow").createRunAsync();
|
|
48
|
+
await run.start({
|
|
49
|
+
inputData: {
|
|
50
|
+
location: "London"
|
|
51
|
+
},
|
|
52
|
+
runtimeContext
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
await weatherTool.execute({
|
|
56
|
+
context: {
|
|
57
|
+
location: "London"
|
|
58
|
+
},
|
|
59
|
+
runtimeContext
|
|
60
|
+
});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Setting values based on request headers
|
|
64
|
+
|
|
65
|
+
You can populate `runtimeContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
|
|
66
|
+
|
|
67
|
+
```typescript filename="src/mastra/index.ts" showLineNumbers copy
|
|
68
|
+
import { Mastra } from "@mastra/core/mastra";
|
|
69
|
+
import { RuntimeContext } from "@mastra/core/runtime-context";
|
|
70
|
+
import { testWeatherAgent } from "./agents/test-weather-agent";
|
|
71
|
+
|
|
72
|
+
export const mastra = new Mastra({
|
|
73
|
+
agents: { testWeatherAgent },
|
|
74
|
+
server: {
|
|
75
|
+
middleware: [
|
|
76
|
+
async (context, next) => {
|
|
77
|
+
const country = context.req.header("CF-IPCountry");
|
|
78
|
+
const runtimeContext = context.get("runtimeContext");
|
|
79
|
+
|
|
80
|
+
runtimeContext.set("temperature-unit", country === "US" ? "fahrenheit" : "celsius");
|
|
81
|
+
|
|
82
|
+
await next();
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
> See [Middleware](../server-db/middleware.mdx) for how to use server middleware.
|
|
90
|
+
|
|
91
|
+
## Accessing values with agents
|
|
92
|
+
|
|
93
|
+
You can access the `runtimeContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `runtimeContext`.
|
|
94
|
+
|
|
95
|
+
```typescript {7-8,15,18,21} filename="src/mastra/agents/weather-agent.ts" showLineNumbers
|
|
96
|
+
export type UserTier = {
|
|
97
|
+
"user-tier": "enterprise" | "pro";
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
export const weatherAgent = new Agent({
|
|
101
|
+
name: "weather-agent",
|
|
102
|
+
instructions: async ({ runtimeContext }) => {
|
|
103
|
+
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
|
|
104
|
+
|
|
105
|
+
if (userTier === "enterprise") {
|
|
106
|
+
// ...
|
|
107
|
+
}
|
|
108
|
+
// ...
|
|
109
|
+
},
|
|
110
|
+
model: ({ runtimeContext }) => {
|
|
111
|
+
// ...
|
|
112
|
+
},
|
|
113
|
+
tools: ({ runtimeContext }) => {
|
|
114
|
+
// ...
|
|
115
|
+
},
|
|
116
|
+
memory: ({ runtimeContext }) => {
|
|
117
|
+
// ...
|
|
118
|
+
},
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
You can also use `runtimeContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
|
|
123
|
+
|
|
124
|
+
> See [Agent](../../reference/agents/agent.mdx) for a full list of configuration options.
|
|
125
|
+
|
|
126
|
+
## Accessing values from workflow steps
|
|
127
|
+
|
|
128
|
+
You can access the `runtimeContext` argument from a workflow step's `execute` function. This function can be sync or async. Use the `.get()` method to read values from `runtimeContext`.
|
|
129
|
+
|
|
130
|
+
```typescript {7-8} filename="src/mastra/workflows/weather-workflow.ts" showLineNumbers copy
|
|
131
|
+
export type UserTier = {
|
|
132
|
+
"user-tier": "enterprise" | "pro";
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
const stepOne = createStep({
|
|
136
|
+
id: "step-one",
|
|
137
|
+
execute: async ({ runtimeContext }) => {
|
|
138
|
+
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
|
|
139
|
+
|
|
140
|
+
if (userTier === "enterprise") {
|
|
141
|
+
// ...
|
|
142
|
+
}
|
|
143
|
+
// ...
|
|
144
|
+
}
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
> See [createStep()](../../reference/workflows/step.mdx) for a full list of configuration options.
|
|
149
|
+
|
|
150
|
+
## Accessing values with tools
|
|
151
|
+
|
|
152
|
+
You can access the `runtimeContext` argument from a tool’s `execute` function. This function is `async`. Use the `.get()` method to read values from `runtimeContext`.
|
|
153
|
+
|
|
154
|
+
```typescript {7-8} filename="src/mastra/tools/weather-tool.ts" showLineNumbers
|
|
155
|
+
export type UserTier = {
|
|
156
|
+
"user-tier": "enterprise" | "pro";
|
|
157
|
+
};
|
|
158
|
+
|
|
159
|
+
export const weatherTool = createTool({
|
|
160
|
+
id: "weather-tool",
|
|
161
|
+
execute: async ({ runtimeContext }) => {
|
|
162
|
+
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
|
|
163
|
+
|
|
164
|
+
if (userTier === "enterprise") {
|
|
165
|
+
// ...
|
|
166
|
+
}
|
|
167
|
+
// ...
|
|
168
|
+
}
|
|
169
|
+
});
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
> See [createTool()](../../reference/tools/create-tool.mdx) for a full list of configuration options.
|
|
173
|
+
|
|
174
|
+
## Related
|
|
175
|
+
|
|
176
|
+
- [RuntimeContext Example](../../examples/agents/runtime-context.mdx)
|
|
177
|
+
- [Tool Runtime Context](../tools-mcp/runtime-context.mdx)
|
|
178
|
+
- [Server Middleware Runtime Context](../server-db/middleware.mdx)
|
|
@@ -18,6 +18,10 @@ By combining writable workflow streams with agent streaming, you gain fine-grain
|
|
|
18
18
|
|
|
19
19
|
### Using the `writer` argument
|
|
20
20
|
|
|
21
|
+
<Callout type="warning">
|
|
22
|
+
The writer is only available when using `streamVNext`.
|
|
23
|
+
</Callout>
|
|
24
|
+
|
|
21
25
|
The `writer` argument is passed to a workflow step's `execute` function and can be used to emit custom events, data, or values into the active stream. This enables workflow steps to provide intermediate results or status updates while execution is still in progress.
|
|
22
26
|
|
|
23
27
|
<Callout type="warning">
|
|
@@ -60,7 +64,7 @@ const testWorkflow = mastra.getWorkflow("testWorkflow");
|
|
|
60
64
|
|
|
61
65
|
const run = await testWorkflow.createRunAsync();
|
|
62
66
|
|
|
63
|
-
const stream = await run.
|
|
67
|
+
const stream = await run.streamVNext({
|
|
64
68
|
inputData: {
|
|
65
69
|
value: "initial data"
|
|
66
70
|
}
|
|
@@ -69,6 +73,29 @@ const stream = await run.stream({
|
|
|
69
73
|
for await (const chunk of stream) {
|
|
70
74
|
console.log(chunk);
|
|
71
75
|
}
|
|
76
|
+
|
|
77
|
+
if (result!.status === "suspended") {
|
|
78
|
+
// if the workflow is suspended, we can resume it with the resumeStreamVNext method
|
|
79
|
+
const resumedStream = await run.resumeStreamVNext({
|
|
80
|
+
resumeData: { value: "resume data" }
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
for await (const chunk of resumedStream) {
|
|
84
|
+
console.log(chunk);
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Resuming an interrupted workflow stream
|
|
90
|
+
|
|
91
|
+
If a workflow stream is closed or interrupted for any reason, you can resume it with the `resumeStreamVNext` method. This will return a new `ReadableStream` that you can use to observe the workflow events.
|
|
92
|
+
|
|
93
|
+
```typescript showLineNumbers copy
|
|
94
|
+
const newStream = await run.resumeStreamVNext();
|
|
95
|
+
|
|
96
|
+
for await (const chunk of newStream) {
|
|
97
|
+
console.log(chunk);
|
|
98
|
+
}
|
|
72
99
|
```
|
|
73
100
|
|
|
74
101
|
## Workflow using an agent
|
|
@@ -56,18 +56,36 @@ When creating tools, keep tool descriptions simple and focused on **what** the t
|
|
|
56
56
|
|
|
57
57
|
To make tools available to an agent, you configure them in the agent's definition. Mentioning available tools and their general purpose in the agent's system prompt can also improve tool usage. For detailed steps and examples, see the guide on [Using Tools and MCP with Agents](/docs/agents/using-tools-and-mcp#add-tools-to-an-agent).
|
|
58
58
|
|
|
59
|
-
##
|
|
59
|
+
## Using `RuntimeContext`
|
|
60
60
|
|
|
61
|
-
|
|
61
|
+
Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers
|
|
64
|
+
export type UserTier = {
|
|
65
|
+
"user-tier": "enterprise" | "pro";
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
const advancedTools = () => {
|
|
69
|
+
// ...
|
|
70
|
+
};
|
|
64
71
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
72
|
+
const baseTools = () => {
|
|
73
|
+
// ...
|
|
74
|
+
};
|
|
68
75
|
|
|
69
|
-
|
|
76
|
+
export const testTool = createTool({
|
|
77
|
+
// ...
|
|
78
|
+
execute: async ({ runtimeContext }) => {
|
|
79
|
+
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
|
|
80
|
+
|
|
81
|
+
return userTier === "enterprise"
|
|
82
|
+
? advancedTools
|
|
83
|
+
: baseTools;
|
|
84
|
+
}
|
|
85
|
+
});
|
|
86
|
+
```
|
|
70
87
|
|
|
88
|
+
> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
|
|
71
89
|
|
|
72
90
|
## Testing tools locally
|
|
73
91
|
There are two ways to run and test tools.
|
|
@@ -83,7 +83,11 @@ export const testWorkflow = createWorkflow({
|
|
|
83
83
|
}),
|
|
84
84
|
outputSchema: z.object({
|
|
85
85
|
output: z.string()
|
|
86
|
-
})
|
|
86
|
+
}),
|
|
87
|
+
options: {
|
|
88
|
+
// enables runtime validation of inputs and applies zod default values.
|
|
89
|
+
validateInputs: true,
|
|
90
|
+
}
|
|
87
91
|
})
|
|
88
92
|
.then(step1)
|
|
89
93
|
.commit();
|
|
@@ -171,6 +175,29 @@ export const mastra = new Mastra({
|
|
|
171
175
|
});
|
|
172
176
|
```
|
|
173
177
|
|
|
178
|
+
## Using `RuntimeContext`
|
|
179
|
+
|
|
180
|
+
Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
|
|
181
|
+
|
|
182
|
+
```typescript filename="src/mastra/workflows/test-workflow.ts" showLineNumbers
|
|
183
|
+
export type UserTier = {
|
|
184
|
+
"user-tier": "enterprise" | "pro";
|
|
185
|
+
};
|
|
186
|
+
|
|
187
|
+
const stepOne = createStep({
|
|
188
|
+
// ...
|
|
189
|
+
execute: async ({ runtimeContext }) => {
|
|
190
|
+
const userTier = runtimeContext.get("user-tier") as UserTier["user-tier"];
|
|
191
|
+
|
|
192
|
+
const maxResults = userTier === "enterprise"
|
|
193
|
+
? 1000
|
|
194
|
+
: 50;
|
|
195
|
+
|
|
196
|
+
return { maxResults };
|
|
197
|
+
}
|
|
198
|
+
});
|
|
199
|
+
```
|
|
200
|
+
|
|
174
201
|
## Testing workflows locally
|
|
175
202
|
There are two ways to run and test workflows.
|
|
176
203
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# @mastra/mcp-docs-server
|
|
2
2
|
|
|
3
|
+
## 0.13.30-alpha.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Updated dependencies [[`1ed9670`](https://github.com/mastra-ai/mastra/commit/1ed9670d3ca50cb60dc2e517738c5eef3968ed27), [`158381d`](https://github.com/mastra-ai/mastra/commit/158381d39335be934b81ef8a1947bccace492c25), [`fb703b9`](https://github.com/mastra-ai/mastra/commit/fb703b9634eeaff1a6eb2b5531ce0f9e8fb04727), [`37a2314`](https://github.com/mastra-ai/mastra/commit/37a23148e0e5a3b40d4f9f098b194671a8a49faf), [`05a9dee`](https://github.com/mastra-ai/mastra/commit/05a9dee3d355694d28847bfffb6289657fcf7dfa), [`e3c1077`](https://github.com/mastra-ai/mastra/commit/e3c107763aedd1643d3def5df450c235da9ff76c), [`1bccdb3`](https://github.com/mastra-ai/mastra/commit/1bccdb33eb90cbeba2dc5ece1c2561fb774b26b6), [`5ef944a`](https://github.com/mastra-ai/mastra/commit/5ef944a3721d93105675cac2b2311432ff8cc393), [`d6b186f`](https://github.com/mastra-ai/mastra/commit/d6b186fb08f1caf1b86f73d3a5ee88fb999ca3be), [`65493b3`](https://github.com/mastra-ai/mastra/commit/65493b31c36f6fdb78f9679f7e1ecf0c250aa5ee), [`a998b8f`](https://github.com/mastra-ai/mastra/commit/a998b8f858091c2ec47683e60766cf12d03001e4), [`8a37bdd`](https://github.com/mastra-ai/mastra/commit/8a37bddb6d8614a32c5b70303d583d80c620ea61)]:
|
|
8
|
+
- @mastra/core@0.21.0-alpha.1
|
|
9
|
+
|
|
10
|
+
## 0.13.30-alpha.0
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- Updated dependencies [[`b5a66b7`](https://github.com/mastra-ai/mastra/commit/b5a66b748a14fc8b3f63b04642ddb9621fbcc9e0), [`2ddb851`](https://github.com/mastra-ai/mastra/commit/2ddb8519c4b6f1d31be10ffd33b41d2b649a04ff), [`7b1ef57`](https://github.com/mastra-ai/mastra/commit/7b1ef57fc071c2aa2a2e32905b18cd88719c5a39), [`228228b`](https://github.com/mastra-ai/mastra/commit/228228b0b1de9291cb8887587f5cea1a8757ebad), [`b5a66b7`](https://github.com/mastra-ai/mastra/commit/b5a66b748a14fc8b3f63b04642ddb9621fbcc9e0), [`ee68e82`](https://github.com/mastra-ai/mastra/commit/ee68e8289ea4408d29849e899bc6e78b3bd4e843), [`228228b`](https://github.com/mastra-ai/mastra/commit/228228b0b1de9291cb8887587f5cea1a8757ebad), [`ea33930`](https://github.com/mastra-ai/mastra/commit/ea339301e82d6318257720d811b043014ee44064), [`b5a66b7`](https://github.com/mastra-ai/mastra/commit/b5a66b748a14fc8b3f63b04642ddb9621fbcc9e0), [`7b1ef57`](https://github.com/mastra-ai/mastra/commit/7b1ef57fc071c2aa2a2e32905b18cd88719c5a39), [`135d6f2`](https://github.com/mastra-ai/mastra/commit/135d6f22a326ed1dffff858700669dff09d2c9eb), [`59d036d`](https://github.com/mastra-ai/mastra/commit/59d036d4c2706b430b0e3f1f1e0ee853ce16ca04)]:
|
|
15
|
+
- @mastra/core@0.21.0-alpha.0
|
|
16
|
+
- @mastra/mcp@0.13.5-alpha.0
|
|
17
|
+
|
|
3
18
|
## 0.13.29
|
|
4
19
|
|
|
5
20
|
### Patch Changes
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/mcp-docs-server",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.30-alpha.1",
|
|
4
4
|
"description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -33,8 +33,8 @@
|
|
|
33
33
|
"uuid": "^11.1.0",
|
|
34
34
|
"zod": "^3.25.76",
|
|
35
35
|
"zod-to-json-schema": "^3.24.6",
|
|
36
|
-
"@mastra/core": "0.
|
|
37
|
-
"@mastra/mcp": "^0.13.
|
|
36
|
+
"@mastra/core": "0.21.0-alpha.1",
|
|
37
|
+
"@mastra/mcp": "^0.13.5-alpha.0"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {
|
|
40
40
|
"@hono/node-server": "^1.19.5",
|
|
@@ -42,15 +42,15 @@
|
|
|
42
42
|
"@types/node": "^20.19.0",
|
|
43
43
|
"@types/turndown": "^5.0.5",
|
|
44
44
|
"@wong2/mcp-cli": "^1.10.0",
|
|
45
|
-
"cross-env": "^
|
|
46
|
-
"eslint": "^9.
|
|
45
|
+
"cross-env": "^10.1.0",
|
|
46
|
+
"eslint": "^9.36.0",
|
|
47
47
|
"hono": "^4.9.7",
|
|
48
48
|
"tsup": "^8.5.0",
|
|
49
49
|
"tsx": "^4.19.4",
|
|
50
50
|
"typescript": "^5.8.3",
|
|
51
51
|
"vitest": "^3.2.4",
|
|
52
52
|
"@internal/lint": "0.0.48",
|
|
53
|
-
"@mastra/core": "0.
|
|
53
|
+
"@mastra/core": "0.21.0-alpha.1"
|
|
54
54
|
},
|
|
55
55
|
"homepage": "https://mastra.ai",
|
|
56
56
|
"repository": {
|
|
@@ -1,103 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: "Runtime Context | Agents | Mastra Docs"
|
|
3
|
-
description: Learn how to use Mastra's RuntimeContext to provide dynamic, request-specific configuration to agents.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Runtime Context
|
|
7
|
-
|
|
8
|
-
Agents use `RuntimeContext` to access request-specific values sent alongside user messages. These values let a single agent change its behavior, functionality, model, tools, or memory usage based on the needs of each request.
|
|
9
|
-
|
|
10
|
-

|
|
11
|
-
|
|
12
|
-
## When to use `RuntimeContext`
|
|
13
|
-
|
|
14
|
-
Use `RuntimeContext` when an agent's behavior should change based on the request or environment. For example, you might switch models or storage providers based on user details, or adjust instructions or tool selection based on the user's language.
|
|
15
|
-
|
|
16
|
-
## Configuring agents with `RuntimeContext`
|
|
17
|
-
|
|
18
|
-
You can access the `runtimeContext` argument from any of the agent’s supported parameters. These functions can be sync or `async`, allowing you to use context values to fetch data, apply logic, or adjust behavior at runtime.
|
|
19
|
-
|
|
20
|
-
```typescript {3,6,9,12} filename="src/dynamic-agent.ts" showLineNumbers copy
|
|
21
|
-
export const dynamicAgent = new Agent({
|
|
22
|
-
name: "dynamic-agent",
|
|
23
|
-
instructions: async ({ runtimeContext }) => {
|
|
24
|
-
// ...
|
|
25
|
-
},
|
|
26
|
-
model: ({ runtimeContext }) => {
|
|
27
|
-
// ...
|
|
28
|
-
},
|
|
29
|
-
tools: ({ runtimeContext }) => {
|
|
30
|
-
// ...
|
|
31
|
-
},
|
|
32
|
-
memory: ({ runtimeContext }) => {
|
|
33
|
-
// ...
|
|
34
|
-
},
|
|
35
|
-
});
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
You can also use `runtimeContext` with other parameters like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
|
|
39
|
-
|
|
40
|
-
> See [Agent](../../reference/agents/agent.mdx) for a full list of configuration options.
|
|
41
|
-
|
|
42
|
-
## Setting values
|
|
43
|
-
|
|
44
|
-
To set variables in `runtimeContext`, create a new instance using `new RuntimeContext()` and call `.set()` to define the values you want to include.
|
|
45
|
-
|
|
46
|
-
The `.set()` method takes two arguments:
|
|
47
|
-
|
|
48
|
-
1. **key**: The name used to identify the value.
|
|
49
|
-
2. **value**: The data to associate with that key.
|
|
50
|
-
|
|
51
|
-
After setting the values, pass the `runtimeContext` to `.generate()` or `.stream()` to make them available to the agent.
|
|
52
|
-
|
|
53
|
-
```typescript {8,11} filename="src/test-dynamic-agent.ts" showLineNumbers copy
|
|
54
|
-
import { mastra } from "./mastra";
|
|
55
|
-
import { RuntimeContext } from "@mastra/core/runtime-context";
|
|
56
|
-
import { UserTier } from "./mastra/agents/dynamic-agent"
|
|
57
|
-
|
|
58
|
-
const agent = mastra.getAgent("dynamicAgent");
|
|
59
|
-
|
|
60
|
-
const runtimeContext = new RuntimeContext<UserTier>();
|
|
61
|
-
runtimeContext.set("user-tier", "enterprise");
|
|
62
|
-
|
|
63
|
-
const response = await agent.generate("Help plan my day.", {
|
|
64
|
-
runtimeContext
|
|
65
|
-
});
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
## Accessing values
|
|
69
|
-
|
|
70
|
-
The example below accesses a `user-tier` value from `runtimeContext` to determine which model and instructions to use. The context is typed to provide safety and autocomplete when working with `.get()` and `.set()`.
|
|
71
|
-
|
|
72
|
-
```typescript {12,19} filename="src/mastra/agents/dynamic-agent.ts" showLineNumbers copy
|
|
73
|
-
import { openai } from "@ai-sdk/openai";
|
|
74
|
-
import { Agent } from "@mastra/core/agent";
|
|
75
|
-
import { RuntimeContext } from "@mastra/core/runtime-context";
|
|
76
|
-
|
|
77
|
-
export type UserTier = {
|
|
78
|
-
"user-tier": "enterprise" | "pro";
|
|
79
|
-
};
|
|
80
|
-
|
|
81
|
-
export const dynamicAgent = new Agent({
|
|
82
|
-
name: "dynamic-agent",
|
|
83
|
-
instructions: async ({ runtimeContext }: { runtimeContext: RuntimeContext<UserTier> }) => {
|
|
84
|
-
const userTier = runtimeContext.get("user-tier");
|
|
85
|
-
|
|
86
|
-
const result = await db.query("SELECT instructions FROM config WHERE tier = ?", [userTier]);
|
|
87
|
-
|
|
88
|
-
return result[0].instructions;
|
|
89
|
-
},
|
|
90
|
-
model: ({ runtimeContext }: { runtimeContext: RuntimeContext<UserTier> }) => {
|
|
91
|
-
const userTier = runtimeContext.get("user-tier");
|
|
92
|
-
|
|
93
|
-
return userTier === "enterprise"
|
|
94
|
-
? openai("gpt-4o-mini")
|
|
95
|
-
: openai("gpt-4.1-nano");
|
|
96
|
-
}
|
|
97
|
-
});
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
## Related
|
|
101
|
-
|
|
102
|
-
- [Tool Runtime Context](../tools-mcp/runtime-context.mdx)
|
|
103
|
-
- [Server Middleware Runtime Context](../server-db/middleware.mdx)
|