@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.
Files changed (126) hide show
  1. package/.docs/organized/changelogs/%40internal%2Fchangeset-cli.md +2 -0
  2. package/.docs/organized/changelogs/%40internal%2Fstorage-test-utils.md +9 -9
  3. package/.docs/organized/changelogs/%40internal%2Ftypes-builder.md +2 -0
  4. package/.docs/organized/changelogs/%40mastra%2Fagent-builder.md +31 -31
  5. package/.docs/organized/changelogs/%40mastra%2Fai-sdk.md +36 -0
  6. package/.docs/organized/changelogs/%40mastra%2Fastra.md +16 -16
  7. package/.docs/organized/changelogs/%40mastra%2Fchroma.md +16 -16
  8. package/.docs/organized/changelogs/%40mastra%2Fclickhouse.md +16 -16
  9. package/.docs/organized/changelogs/%40mastra%2Fclient-js.md +28 -28
  10. package/.docs/organized/changelogs/%40mastra%2Fcloud.md +16 -16
  11. package/.docs/organized/changelogs/%40mastra%2Fcloudflare-d1.md +16 -16
  12. package/.docs/organized/changelogs/%40mastra%2Fcloudflare.md +16 -16
  13. package/.docs/organized/changelogs/%40mastra%2Fcore.md +106 -106
  14. package/.docs/organized/changelogs/%40mastra%2Fcouchbase.md +16 -16
  15. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloud.md +37 -37
  16. package/.docs/organized/changelogs/%40mastra%2Fdeployer-cloudflare.md +25 -25
  17. package/.docs/organized/changelogs/%40mastra%2Fdeployer-netlify.md +25 -25
  18. package/.docs/organized/changelogs/%40mastra%2Fdeployer-vercel.md +25 -25
  19. package/.docs/organized/changelogs/%40mastra%2Fdeployer.md +49 -49
  20. package/.docs/organized/changelogs/%40mastra%2Fdynamodb.md +16 -16
  21. package/.docs/organized/changelogs/%40mastra%2Fevals.md +33 -33
  22. package/.docs/organized/changelogs/%40mastra%2Flance.md +16 -16
  23. package/.docs/organized/changelogs/%40mastra%2Flibsql.md +16 -16
  24. package/.docs/organized/changelogs/%40mastra%2Floggers.md +16 -16
  25. package/.docs/organized/changelogs/%40mastra%2Fmcp-docs-server.md +23 -23
  26. package/.docs/organized/changelogs/%40mastra%2Fmcp-registry-registry.md +16 -16
  27. package/.docs/organized/changelogs/%40mastra%2Fmcp.md +16 -16
  28. package/.docs/organized/changelogs/%40mastra%2Fmemory.md +36 -36
  29. package/.docs/organized/changelogs/%40mastra%2Fmongodb.md +16 -16
  30. package/.docs/organized/changelogs/%40mastra%2Fmssql.md +16 -16
  31. package/.docs/organized/changelogs/%40mastra%2Fopensearch.md +17 -17
  32. package/.docs/organized/changelogs/%40mastra%2Fpg.md +31 -31
  33. package/.docs/organized/changelogs/%40mastra%2Fpinecone.md +16 -16
  34. package/.docs/organized/changelogs/%40mastra%2Fplayground-ui.md +67 -67
  35. package/.docs/organized/changelogs/%40mastra%2Fqdrant.md +16 -16
  36. package/.docs/organized/changelogs/%40mastra%2Frag.md +16 -16
  37. package/.docs/organized/changelogs/%40mastra%2Freact.md +37 -0
  38. package/.docs/organized/changelogs/%40mastra%2Fs3vectors.md +15 -0
  39. package/.docs/organized/changelogs/%40mastra%2Fserver.md +37 -37
  40. package/.docs/organized/changelogs/%40mastra%2Fturbopuffer.md +16 -16
  41. package/.docs/organized/changelogs/%40mastra%2Fupstash.md +19 -19
  42. package/.docs/organized/changelogs/%40mastra%2Fvectorize.md +17 -17
  43. package/.docs/organized/changelogs/%40mastra%2Fvoice-azure.md +18 -18
  44. package/.docs/organized/changelogs/%40mastra%2Fvoice-cloudflare.md +16 -16
  45. package/.docs/organized/changelogs/%40mastra%2Fvoice-deepgram.md +16 -16
  46. package/.docs/organized/changelogs/%40mastra%2Fvoice-elevenlabs.md +16 -16
  47. package/.docs/organized/changelogs/%40mastra%2Fvoice-gladia.md +16 -16
  48. package/.docs/organized/changelogs/%40mastra%2Fvoice-google-gemini-live.md +15 -0
  49. package/.docs/organized/changelogs/%40mastra%2Fvoice-google.md +16 -16
  50. package/.docs/organized/changelogs/%40mastra%2Fvoice-murf.md +16 -16
  51. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai-realtime.md +16 -16
  52. package/.docs/organized/changelogs/%40mastra%2Fvoice-openai.md +16 -16
  53. package/.docs/organized/changelogs/%40mastra%2Fvoice-playai.md +16 -16
  54. package/.docs/organized/changelogs/%40mastra%2Fvoice-sarvam.md +16 -16
  55. package/.docs/organized/changelogs/%40mastra%2Fvoice-speechify.md +16 -16
  56. package/.docs/organized/changelogs/create-mastra.md +35 -35
  57. package/.docs/organized/changelogs/mastra.md +63 -63
  58. package/.docs/organized/code-examples/agent.md +26 -7
  59. package/.docs/organized/code-examples/agui.md +4 -4
  60. package/.docs/organized/code-examples/ai-elements.md +1 -1
  61. package/.docs/organized/code-examples/ai-sdk-useChat.md +2 -2
  62. package/.docs/organized/code-examples/ai-sdk-v5.md +2 -2
  63. package/.docs/organized/code-examples/assistant-ui.md +2 -2
  64. package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md +2 -2
  65. package/.docs/organized/code-examples/bird-checker-with-nextjs.md +2 -2
  66. package/.docs/organized/code-examples/client-side-tools.md +4 -4
  67. package/.docs/organized/code-examples/crypto-chatbot.md +2 -2
  68. package/.docs/organized/code-examples/heads-up-game.md +2 -2
  69. package/.docs/organized/code-examples/openapi-spec-writer.md +2 -2
  70. package/.docs/raw/agents/adding-voice.mdx +118 -25
  71. package/.docs/raw/agents/agent-memory.mdx +73 -89
  72. package/.docs/raw/agents/guardrails.mdx +1 -1
  73. package/.docs/raw/agents/networks.mdx +12 -6
  74. package/.docs/raw/agents/overview.mdx +46 -11
  75. package/.docs/raw/agents/using-tools.mdx +95 -0
  76. package/.docs/raw/deployment/overview.mdx +9 -11
  77. package/.docs/raw/frameworks/agentic-uis/ai-sdk.mdx +7 -4
  78. package/.docs/raw/frameworks/servers/express.mdx +2 -2
  79. package/.docs/raw/getting-started/installation.mdx +34 -132
  80. package/.docs/raw/getting-started/mcp-docs-server.mdx +13 -1
  81. package/.docs/raw/index.mdx +49 -14
  82. package/.docs/raw/observability/ai-tracing/exporters/otel.mdx +3 -0
  83. package/.docs/raw/reference/agents/generateLegacy.mdx +4 -4
  84. package/.docs/raw/reference/observability/ai-tracing/exporters/otel.mdx +6 -0
  85. package/.docs/raw/reference/scorers/answer-relevancy.mdx +105 -7
  86. package/.docs/raw/reference/scorers/answer-similarity.mdx +266 -16
  87. package/.docs/raw/reference/scorers/bias.mdx +107 -6
  88. package/.docs/raw/reference/scorers/completeness.mdx +131 -8
  89. package/.docs/raw/reference/scorers/content-similarity.mdx +107 -8
  90. package/.docs/raw/reference/scorers/context-precision.mdx +234 -18
  91. package/.docs/raw/reference/scorers/context-relevance.mdx +418 -35
  92. package/.docs/raw/reference/scorers/faithfulness.mdx +122 -8
  93. package/.docs/raw/reference/scorers/hallucination.mdx +125 -8
  94. package/.docs/raw/reference/scorers/keyword-coverage.mdx +141 -9
  95. package/.docs/raw/reference/scorers/noise-sensitivity.mdx +478 -6
  96. package/.docs/raw/reference/scorers/prompt-alignment.mdx +351 -102
  97. package/.docs/raw/reference/scorers/textual-difference.mdx +134 -6
  98. package/.docs/raw/reference/scorers/tone-consistency.mdx +133 -0
  99. package/.docs/raw/reference/scorers/tool-call-accuracy.mdx +422 -65
  100. package/.docs/raw/reference/scorers/toxicity.mdx +125 -7
  101. package/.docs/raw/reference/streaming/agents/MastraModelOutput.mdx +9 -5
  102. package/.docs/raw/reference/streaming/agents/streamLegacy.mdx +4 -4
  103. package/.docs/raw/reference/streaming/workflows/observeStream.mdx +49 -0
  104. package/.docs/raw/reference/streaming/workflows/observeStreamVNext.mdx +47 -0
  105. package/.docs/raw/reference/streaming/workflows/resumeStreamVNext.mdx +7 -5
  106. package/.docs/raw/reference/streaming/workflows/stream.mdx +1 -1
  107. package/.docs/raw/reference/workflows/workflow.mdx +33 -0
  108. package/.docs/raw/scorers/custom-scorers.mdx +244 -3
  109. package/.docs/raw/scorers/overview.mdx +8 -38
  110. package/.docs/raw/server-db/middleware.mdx +5 -2
  111. package/.docs/raw/server-db/runtime-context.mdx +178 -0
  112. package/.docs/raw/streaming/workflow-streaming.mdx +28 -1
  113. package/.docs/raw/tools-mcp/overview.mdx +25 -7
  114. package/.docs/raw/workflows/overview.mdx +28 -1
  115. package/CHANGELOG.md +15 -0
  116. package/package.json +6 -6
  117. package/.docs/raw/agents/runtime-context.mdx +0 -103
  118. package/.docs/raw/agents/using-tools-and-mcp.mdx +0 -241
  119. package/.docs/raw/getting-started/model-providers.mdx +0 -63
  120. package/.docs/raw/reference/agents/migration-guide.mdx +0 -291
  121. package/.docs/raw/tools-mcp/runtime-context.mdx +0 -63
  122. /package/.docs/raw/{evals → scorers/evals-old-api}/custom-eval.mdx +0 -0
  123. /package/.docs/raw/{evals → scorers/evals-old-api}/overview.mdx +0 -0
  124. /package/.docs/raw/{evals → scorers/evals-old-api}/running-in-ci.mdx +0 -0
  125. /package/.docs/raw/{evals → scorers/evals-old-api}/textual-evals.mdx +0 -0
  126. /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
- **Scorers** are evaluation tools that measure the quality, accuracy, or performance of AI-generated outputs. Scorers provide an automated way to assess whether your agents, workflows, or language models are producing the desired results by analyzing their responses against specific criteria.
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
- **Scores** are 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.
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
- ## Evaluation pipeline
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
- Mastra scorers follow a flexible four-step pipeline that allows for simple to complex evaluation workflows:
16
+ ## Types of Scorers
17
17
 
18
- 1. **preprocess** (Optional): Prepare or transform input/output data for evaluation
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
- This modular structure enables both simple single-step evaluations and complex multi-stage analysis workflows, allowing you to build evaluations that match your specific needs.
24
-
25
- ### When to use each step
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") as RuntimeContext<WeatherRuntimeContext>;
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.stream({
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
- ## Compatibility Layer for Tool Schemas
59
+ ## Using `RuntimeContext`
60
60
 
61
- Different models interpret schemas differently. Some error when certain schema properties are passed and some ignore certain schema properties but don't throw an error. Mastra adds a compatibility layer for tool schemas, ensuring tools work consistently across different model providers and that the schema constraints are respected.
61
+ Use `RuntimeContext` to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
62
62
 
63
- Some providers that we include this layer for:
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
- - **Google Gemini & Anthropic:** Remove unsupported schema properties and append relevant constraints to the tool description.
66
- - **OpenAI (including reasoning models):** Strip or adapt schema fields that are ignored or unsupported, and add instructions to the description for agent guidance.
67
- - **DeepSeek & Meta:** Apply similar compatibility logic to ensure schema alignment and tool usability.
72
+ const baseTools = () => {
73
+ // ...
74
+ };
68
75
 
69
- This approach makes tool usage more reliable and model-agnostic for both custom and MCP tools.
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.29",
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.20.2",
37
- "@mastra/mcp": "^0.13.4"
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": "^7.0.3",
46
- "eslint": "^9.35.0",
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.20.2"
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
- ![Agents Runtime Context](/image/agents/agents-runtime-context.jpg)
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)