@mastra/core 1.2.1-alpha.0 → 1.3.0-alpha.1

package/dist/docs/references/docs-agents-agent-memory.md

@@ -2,7 +2,7 @@
 
 Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track message history and recall relevant information.
 
-Mastra agents can be configured to store message history, with optional [working memory](https://mastra.ai/docs/memory/working-memory) to maintain recent context or [semantic recall](https://mastra.ai/docs/memory/semantic-recall) to retrieve past messages based on meaning.
+Mastra agents can be configured to store message history, with optional [working memory](https://mastra.ai/docs/memory/working-memory) to maintain recent context, [semantic recall](https://mastra.ai/docs/memory/semantic-recall) to retrieve past messages based on meaning, or [observational memory](https://mastra.ai/docs/memory/observational-memory) for automatic long-term memory that compresses conversations as they grow.
 
 ## When to use memory
 
@@ -134,6 +134,49 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 
 To learn more about memory see the [Memory](https://mastra.ai/docs/memory/overview) documentation.
 
+## Observational Memory
+
+For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    options: {
+      observationalMemory: true,
+    },
+  }),
+});
+```
+
+Setting `observationalMemory: true` uses `google/gemini-2.5-flash` as the default model for the Observer and Reflector. To use a different model or customize thresholds, pass a config object:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+export const memoryAgent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        model: "deepseek/deepseek-reasoner",
+        observation: {
+          messageTokens: 20_000,
+        },
+      },
+    },
+  }),
+});
+```
+
+> **Info:** See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
+
 ## Using `RequestContext`
 
 Use [RequestContext](https://mastra.ai/docs/server/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
@@ -162,6 +205,7 @@ export const memoryAgent = new Agent({
 
 ## Related
 
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
 - [Working Memory](https://mastra.ai/docs/memory/working-memory)
 - [Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)
 - [Storage](https://mastra.ai/docs/memory/storage)

package/dist/docs/references/docs-agents-network-approval.md

@@ -1,6 +1,6 @@
 # Network Approval
 
-Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in individual agents and workflows. When a tool, sub-agent, or workflow within a network requires approval or suspends execution, the network pauses and emits events that allow your application to collect user input before resuming.
+Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in individual agents and workflows. When a tool, subagent, or workflow within a network requires approval or suspends execution, the network pauses and emits events that allow your application to collect user input before resuming.
 
 ## Storage
 

package/dist/docs/references/docs-agents-networks.md

@@ -1,6 +1,6 @@
 # Agent Networks
 
-Agent networks in Mastra coordinate multiple agents, workflows, and tools to handle tasks that aren't clearly defined upfront but can be inferred from the user's message or context. A top-level **routing agent** (a Mastra agent with other agents, workflows, and tools configured) uses an LLM to interpret the request and decide which primitives (sub-agents, workflows, or tools) to call, in what order, and with what data.
+Agent networks in Mastra coordinate multiple agents, workflows, and tools to handle tasks that aren't clearly defined upfront but can be inferred from the user's message or context. A top-level **routing agent** (a Mastra agent with other agents, workflows, and tools configured) uses an LLM to interpret the request and decide which primitives (subagents, workflows, or tools) to call, in what order, and with what data.
 
 ## When to use networks
 
@@ -16,7 +16,7 @@ Mastra agent networks operate using these principles:
 
 ## Creating an agent network
 
-An agent network is built around a top-level routing agent that delegates tasks to agents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
+An agent network is built around a top-level routing agent that delegates tasks to subagents, workflows, and tools defined in its configuration. Memory is configured on the routing agent using the `memory` option, and `instructions` define the agent's routing behavior.
 
 ```typescript
 import { Agent } from "@mastra/core/agent";
@@ -64,7 +64,7 @@ When configuring a Mastra agent network, each primitive (agent, workflow, or too
 
 #### Agent descriptions
 
-Each agent in a network should include a clear `description` that explains what the agent does.
+Each subagent in a network should include a clear `description` that explains what the agent does.
 
 ```typescript
 export const researchAgent = new Agent({

package/dist/docs/references/docs-agents-overview.md

@@ -119,6 +119,14 @@ export const mastra = new Mastra({
 });
 ```
 
+### Registering subagents
+
+You can register subagents within an agent. They'll be executed as tools from the parent agent. Read the [using agents as tools](https://mastra.ai/docs/agents/using-tools) documentation to learn more.
+
+### Registering subworkflows
+
+You can register subworkflows within an agent. They'll be executed as tools from the parent agent. Read the [using workflows as tools](https://mastra.ai/docs/agents/using-tools) documentation to learn more.
+
 ## Referencing an agent
 
 You can call agents from workflow steps, tools, the Mastra Client, or the command line. Get a reference by calling `.getAgent()` on your `mastra` or `mastraClient` instance, depending on your setup:

package/dist/docs/references/docs-agents-using-tools.md

@@ -57,84 +57,49 @@ export const weatherAgent = new Agent({
 });
 ```
 
-## Controlling `toolName` in stream responses
+## Using multiple tools
 
-The `toolName` in stream responses is determined by the **object key** you use, not the `id` property of the tool, agent, or workflow.
+When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
 
 ```typescript
-// Tool defined with id: "weather-tool"
-export const weatherTool = createTool({
-  id: "weather-tool",
-  // ...
-});
-
-// Using the variable name as the key
-tools: { weatherTool }
-// Stream returns: toolName: "weatherTool"
-
-// Using the tool's id as the key
-tools: { [weatherTool.id]: weatherTool }
-// Stream returns: toolName: "weather-tool"
+import { weatherTool } from "../tools/weather-tool";
+import { activitiesTool } from "../tools/activities-tool";
 
-// Using a custom key
-tools: { "my-custom-name": weatherTool }
-// Stream returns: toolName: "my-custom-name"
+export const weatherAgent = new Agent({
+  id: "weather-agent",
+  name: "Weather Agent",
+  tools: { weatherTool, activitiesTool },
+});
 ```
 
-This lets you specify how tools are identified in the stream. If you want the `toolName` to match the tool's `id`, use the tool's `id` as the object key.
-
-### Sub-agents and workflows as tools
-
-Sub-agents and workflows follow the same pattern. They are converted to tools with a prefix followed by your object key:
+## Using agents as tools
 
-| Property    | Prefix      | Example key | `toolName`          |
-| ----------- | ----------- | ----------- | ------------------- |
-| `agents`    | `agent-`    | `weather`   | `agent-weather`     |
-| `workflows` | `workflow-` | `research`  | `workflow-research` |
+Agents can be added to other agents through the `agents` configuration. When you add a subagent, Mastra automatically converts it to a tool that the parent agent can call. The generated tool is named `agent-<agentName>`.
 
 ```typescript
-const orchestrator = new Agent({
-  // ...
+import { Agent } from "@mastra/core/agent";
+
+export const parentAgent = new Agent({
+  id: "parent-agent",
+  name: "Parent Agent",
+  description: "Take care in writing a good description here",
+  instructions: `Instructions`,
+  model: "openai/gpt-5.1",
   agents: {
-    weather: weatherAgent,  // toolName: "agent-weather"
-  },
-  workflows: {
-    research: researchWorkflow,  // toolName: "workflow-research"
+    subAgent,
   },
 });
-```
-
-Note that for sub-agents, you'll see two different identifiers in stream responses:
 
-- `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
-- `id: "weather-agent"` in `data-tool-agent` chunks — the sub-agent's actual `id` property
-
-## Calling an agent
-
-The agent uses the tool's `inputSchema` to infer what data the tool expects. In this case, it extracts `London` as the `location` from the message and passes it to the tool's inputData parameter.
-
-```typescript
-import { mastra } from "./mastra";
-
-const agent = mastra.getAgent("weatherAgent");
-
-const result = await agent.generate("What's the weather in London?");
+const subAgent = new Agent({
+  id: "sub-agent",
+  name: "Sub Agent",
+  description: "Take care in writing a good description here",
+  instructions: `Instructions`,
+  model: "openai/gpt-5.1",
+})
 ```
 
-## Using multiple tools
-
-When multiple tools are available, the agent may choose to use one, several, or none, depending on what's needed to answer the query.
-
-```typescript
-import { weatherTool } from "../tools/weather-tool";
-import { activitiesTool } from "../tools/activities-tool";
-
-export const weatherAgent = new Agent({
-  id: "weather-agent",
-  name: "Weather Agent",
-  tools: { weatherTool, activitiesTool },
-});
-```
+The subagent should include a `description` to help the parent agent understand when to use it. See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
 
 ## Using workflows as tools
 
@@ -169,16 +134,8 @@ import { z } from "zod";
 export const researchWorkflow = createWorkflow({
   id: "research-workflow",
   description: "Gathers information on a topic and compiles a summary report.",
-  inputSchema: z.object({
-    topic: z.string(),
-  }),
-  outputSchema: z.object({
-    summary: z.string(),
-    sources: z.array(z.string()),
-  }),
+  // Rest of the workflow...
 })
-  .then(gatherSourcesStep)
-  .then(compileReportStep)
   .commit();
 ```
 
@@ -191,6 +148,59 @@ When the agent calls the workflow tool, it receives a response containing the wo
 }
 ```
 
+See the [`toolName` docs](#subagents-and-workflows-as-tools) to learn more about the tool naming scheme.
+
+## Controlling `toolName` in stream responses
+
+The `toolName` in stream responses is determined by the **object key** you use, not the `id` property of the tool, agent, or workflow.
+
+```typescript
+// Tool defined with id: "weather-tool"
+export const weatherTool = createTool({
+  id: "weather-tool",
+  // ...
+});
+
+// Using the variable name as the key
+tools: { weatherTool }
+// Stream returns: toolName: "weatherTool"
+
+// Using the tool's id as the key
+tools: { [weatherTool.id]: weatherTool }
+// Stream returns: toolName: "weather-tool"
+
+// Using a custom key
+tools: { "my-custom-name": weatherTool }
+// Stream returns: toolName: "my-custom-name"
+```
+
+This lets you specify how tools are identified in the stream. If you want the `toolName` to match the tool's `id`, use the tool's `id` as the object key.
+
+### Subagents and workflows as tools
+
+Subagents and workflows follow the same pattern. They are converted to tools with a prefix followed by your object key:
+
+| Property    | Prefix      | Example key | `toolName`          |
+| ----------- | ----------- | ----------- | ------------------- |
+| `agents`    | `agent-`    | `weather`   | `agent-weather`     |
+| `workflows` | `workflow-` | `research`  | `workflow-research` |
+
+```typescript
+const orchestrator = new Agent({
+  agents: {
+    weather: weatherAgent,  // toolName: "agent-weather"
+  },
+  workflows: {
+    research: researchWorkflow,  // toolName: "workflow-research"
+  },
+});
+```
+
+Note that for subagents, you'll see two different identifiers in stream responses:
+
+- `toolName: "agent-weather"` in tool call events — the generated tool wrapper name
+- `id: "weather-agent"` in `data-tool-agent` chunks — the subagent's actual `id` property
+
 ## Tools with structured output
 
 When using tools with [structured output](https://mastra.ai/docs/agents/structured-output), some models don't support combining both features in the same API call. If your tools aren't being called when structured output is enabled, or you receive errors about incompatible options, see [Combining tools and structured output](https://mastra.ai/docs/agents/structured-output) for model compatibility information and workarounds.

package/dist/docs/references/docs-memory-observational-memory.md

@@ -1,9 +1,13 @@
 # Observational Memory
 
+**Added in:** `@mastra/memory@1.1.0`
+
 Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** and a **Reflector** — watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
 
 ## Quick Start
 
+Enable `observationalMemory` in the memory options when creating your agent:
+
 ```typescript
 import { Memory } from "@mastra/memory";
 import { Agent } from "@mastra/core/agent";
@@ -20,11 +24,21 @@ export const agent = new Agent({
 });
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations.
+That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model or customize thresholds, pass a config object instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "deepseek/deepseek-reasoner",
+    },
+  },
+});
+```
 
 See [configuration options](https://mastra.ai/reference/memory/observational-memory) for full API details.
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It also uses background agents for managing memory. The default model (configurable) is `google/gemini-2.5-flash` as it's the one we've tested the most.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, and `@mastra/mongodb` storage adapters. It uses background agents for managing memory. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
 ## Benefits
 
@@ -65,15 +79,17 @@ When observations exceed their threshold (default: 40,000 tokens), the Reflector
 
 The result is a three-tier system:
 
-1. **Recent messages** — exact conversation history for the current task
-2. **Observations** — a log of what the Observer has seen
-3. **Reflections** — condensed observations when memory becomes too long
+1. **Recent messages**: Exact conversation history for the current task
+2. **Observations**: A log of what the Observer has seen
+3. **Reflections**: Condensed observations when memory becomes too long
 
 ## Models
 
 The Observer and Reflector run in the background. Any model that works with Mastra's model routing (e.g. `openai/...`, `google/...`, `deepseek/...`) can be used.
 
-The default is `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
+When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+
+We recommend `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
 
 We've also tested `deepseek`, `qwen3`, and `glm-4.7` for the Observer. For the Reflector, make sure the model's context window can fit all observations. Note that Claude 4.5 models currently don't work well as observer or reflector.
 
@@ -96,9 +112,14 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 Each thread has its own observations.
 
 ```typescript
-observationalMemory: {
-  scope: "thread",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "thread",
+    },
+  },
+});
 ```
 
 ### Resource scope
@@ -106,9 +127,14 @@ observationalMemory: {
 Observations are shared across all threads for a resource (typically a user). Enables cross-conversation memory.
 
 ```typescript
-observationalMemory: {
-  scope: "resource",
-}
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      scope: "resource",
+    },
+  },
+});
 ```
 
 > **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
@@ -121,6 +147,7 @@ OM uses token thresholds to decide when to observe and reflect. See [token budge
 const memory = new Memory({
   options: {
     observationalMemory: {
+      model: "google/gemini-2.5-flash",
       observation: {
         // when to run the Observer (default: 30,000)
         messageTokens: 30_000,
@@ -130,12 +157,58 @@ const memory = new Memory({
         observationTokens: 40_000,
       },
       // let message history borrow from observation budget
+      // requires bufferTokens: false (temporary limitation)
       shareTokenBudget: false,
     },
   },
 });
 ```
 
+## Async Buffering
+
+Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
+
+### How it works
+
+As the agent converses, message tokens accumulate. At regular intervals (`bufferTokens`), a background Observer call runs without blocking the agent. Each call produces a "chunk" of observations that's stored in a buffer.
+
+When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
+
+If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort.
+
+Reflection works similarly — the Reflector runs in the background when observations reach a fraction of the reflection threshold.
+
+### Settings
+
+| Setting                        | Default | What it controls                                                                                                                                                                      |
+| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`     | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).    |
+| `observation.bufferActivation` | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history. |
+| `observation.blockAfter`       | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                  |
+| `reflection.bufferActivation`  | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                  |
+| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                           |
+
+### Disabling
+
+To disable async buffering and use synchronous observation/reflection instead:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: "google/gemini-2.5-flash",
+      observation: {
+        bufferTokens: false,
+      },
+    },
+  },
+});
+```
+
+Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
+
+> **Note:** Async buffering is not supported with `scope: 'resource'`. It is automatically disabled in resource scope.
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.
@@ -149,10 +222,9 @@ Mastra Studio shows OM status in real time in the memory tab: token usage, which
 
 ## Comparing OM with other memory features
 
-- **[Message history](https://mastra.ai/docs/memory/message-history)** — high-fidelity record of the current conversation
-- **[Working memory](https://mastra.ai/docs/memory/working-memory)** — small, structured state (JSON or markdown) for user preferences, names, goals
-- **[Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)** — RAG-based retrieval of relevant past messages
-- **Observational Memory** — long-context agentic memory that compresses extended sessions
+- **[Message history](https://mastra.ai/docs/memory/message-history)**: High-fidelity record of the current conversation
+- **[Working memory](https://mastra.ai/docs/memory/working-memory)**: Small, structured state (JSON or markdown) for user preferences, names, goals
+- **[Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)**: RAG-based retrieval of relevant past messages
 
 If you're using working memory to store conversation summaries or ongoing state that grows over time, OM is a better fit. Working memory is for small, structured data; OM is for long-running event logs. OM also manages message history automatically—the `messageTokens` setting controls how much raw history remains before observation runs.
 
@@ -160,7 +232,7 @@ In practical terms, OM replaces both working memory and message history, and has
 
 ## Related
 
-- [Observational Memory Reference](https://mastra.ai/reference/memory/observational-memory) — configuration options and API
+- [Observational Memory Reference](https://mastra.ai/reference/memory/observational-memory)
 - [Memory Overview](https://mastra.ai/docs/memory/overview)
 - [Message History](https://mastra.ai/docs/memory/message-history)
 - [Memory Processors](https://mastra.ai/docs/memory/memory-processors)

package/dist/docs/references/docs-observability-overview.md

@@ -57,7 +57,7 @@ export const mastra = new Mastra({
 });
 ```
 
-> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel-deployer) for a complete example.
+> **Serverless environments:** The `file:./mastra.db` storage URL uses the local filesystem, which doesn't work in serverless environments like Vercel, AWS Lambda, or Cloudflare Workers. For serverless deployments, use external storage. See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete example.
 
 With this basic setup, you will see Traces and Logs in both Studio and in Mastra Cloud.
 

package/dist/docs/references/docs-observability-tracing-exporters-langsmith.md

@@ -126,6 +126,76 @@ new LangSmithExporter({
 
 The `projectName` config option takes precedence over the `LANGCHAIN_PROJECT` environment variable, allowing you to programmatically route traces to different projects.
 
+## Dynamic Configuration
+
+You can dynamically override LangSmith settings per-span using `withLangsmithMetadata`. This is useful for routing traces to different projects based on runtime conditions (e.g., customer, environment, or feature).
+
+### Using the Helper
+
+Use `withLangsmithMetadata` with `buildTracingOptions` to set LangSmith-specific options:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { buildTracingOptions } from "@mastra/observability";
+import { withLangsmithMetadata } from "@mastra/langsmith";
+
+export const supportAgent = new Agent({
+  id: "support-agent",
+  name: "support-agent",
+  instructions: "You are a helpful support agent.",
+  model: "openai/gpt-4o",
+  defaultOptions: {
+    tracingOptions: buildTracingOptions(
+      withLangsmithMetadata({ projectName: "customer-support" }),
+    ),
+  },
+});
+```
+
+### Dynamic Project Routing
+
+Use `requestContext` to route traces to different projects based on runtime conditions.
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { buildTracingOptions } from "@mastra/observability";
+import { withLangsmithMetadata } from "@mastra/langsmith";
+
+export const supportAgent = new Agent({
+  id: "support-agent",
+  name: "support-agent",
+  instructions: "You are a helpful support agent.",
+  model: "openai/gpt-4o",
+  defaultOptions: ({ requestContext }) => {
+    const userTier = requestContext?.get("user-tier") as string;
+    const userId = requestContext?.get("user-id") as string;
+
+    return {
+      tracingOptions: buildTracingOptions(
+        withLangsmithMetadata({
+          projectName: userTier === "enterprise"
+            ? "enterprise-traces"
+            : "standard-traces",
+          sessionId: userId,
+        }),
+      ),
+    };
+  },
+});
+```
+
+### Available Fields
+
+The `withLangsmithMetadata` helper accepts these fields:
+
+| Field         | Type   | Description                         |
+| ------------- | ------ | ----------------------------------- |
+| `projectName` | string | Override the project for this trace |
+| `sessionId`   | string | Group related traces by session     |
+| `sessionName` | string | Display name for the session        |
+
+All fields are optional. The helper merges with any existing metadata, so you can call it multiple times or combine with other tracing options.
+
 ## Related
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)

package/dist/docs/references/docs-observability-tracing-overview.md

@@ -1023,7 +1023,7 @@ This creates a single distributed trace that includes both the HTTP request hand
 
 In serverless environments like Vercel's fluid compute, AWS Lambda, or Cloudflare Workers, runtime instances can be reused across multiple requests. The `flush()` method allows you to ensure all buffered spans are exported before the runtime terminates, without shutting down the exporter (which would prevent future exports).
 
-> **Storage requirements:** Serverless environments have ephemeral filesystems. Use external storage instead of local file storage (`file:./mastra.db`). See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel-deployer) for a complete setup example.
+> **Storage requirements:** Serverless environments have ephemeral filesystems. Use external storage instead of local file storage (`file:./mastra.db`). See the [Vercel deployment guide](https://mastra.ai/guides/deployment/vercel) for a complete setup example.
 
 ### Using flush()
 

package/dist/docs/references/docs-server-middleware.md

@@ -50,8 +50,6 @@ registerApiRoute("/my-custom-route", {
 });
 ```
 
-***
-
 ## Common examples
 
 ### Using `RequestContext`

package/dist/docs/references/docs-server-request-context.md

@@ -453,6 +453,23 @@ requestContextSchema: z.object({
 
 **Handle tool validation errors**: Since tools return error objects instead of throwing, check for errors in your agent or workflow logic when tool execution is critical.
 
+## Testing with Studio presets
+
+When developing locally, you can define named presets in a JSON file and load them into Studio with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
+
+```bash
+mastra dev --request-context-presets ./presets.json
+```
+
+```json
+{
+  "development": { "userId": "dev-user", "env": "development" },
+  "production": { "userId": "prod-user", "env": "production" }
+}
+```
+
+When you select a preset from the dropdown, the JSON editor populates with that preset's values. Editing the JSON manually switches the dropdown back to "Custom".
+
 ## Related
 
 - [Agent Request Context](https://mastra.ai/docs/agents/overview)

package/dist/docs/references/docs-workflows-agents-and-tools.md

@@ -57,7 +57,7 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
-> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/input-data-mapping) for more information.
+> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
 
 When no `structuredOutput` option is provided, Mastra agents use a default schema that expects a `prompt` string as input and returns a `text` string as output:
 
@@ -162,7 +162,7 @@ export const testWorkflow = createWorkflow({})
   .commit();
 ```
 
-> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/input-data-mapping) for more information.
+> **Info:** Visit [Input Data Mapping](https://mastra.ai/docs/workflows/control-flow) for more information.
 
 ## Related
 

package/dist/docs/references/docs-workflows-overview.md

@@ -8,7 +8,7 @@ Workflows let you define complex sequences of tasks using clear, structured step
 
 Use workflows for tasks that are clearly defined upfront and involve multiple steps with a specific execution order. They give you fine-grained control over how data flows and transforms between steps, and which primitives are called at each stage.
 
-> **📹 Watch**: → An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
+> **Watch an introduction:** An introduction to workflows, and how they compare to agents [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
 ## Core principles