@mastra/core 1.0.0-beta.21 → 1.0.0-beta.22

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

@@ -1,8 +1,8 @@
 > Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 
 > **Code References:**
-- `Agent`: dist/agent/agent.d.ts → dist/chunk-IC2MIQBW.js:16163
-- `Mastra`: dist/mastra/index.d.ts → dist/chunk-XBZWAUZ3.js:24
+- `Agent`: dist/agent/agent.d.ts → dist/chunk-UVOQLIWL.js:16630
+- `Mastra`: dist/mastra/index.d.ts → dist/chunk-IFPQ2MLB.js:24
 
 # Using Agents
 

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

@@ -141,8 +141,13 @@ When the agent calls the workflow tool, it receives a response containing the wo
 }
 ```
 
+## Tools with structured output
+
+When using tools with [structured output](https://mastra.ai/docs/v1/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/v1/agents/structured-output#combining-tools-and-structured-output) for model compatibility information and workarounds.
+
 ## Related
 
 - [MCP Overview](https://mastra.ai/docs/v1/mcp/overview)
+- [Structured Output](https://mastra.ai/docs/v1/agents/structured-output)
 - [Agent Memory](https://mastra.ai/docs/v1/agents/agent-memory)
 - [Request Context](https://mastra.ai/docs/v1/server/request-context)

package/dist/docs/agents/04-structured-output.md

@@ -65,7 +65,7 @@ console.log(response.object);
 
 > **Note:**
 
-Visit [.generate()](https://mastra.ai/reference/v1/agents/generate#structuredoutput) for a full list of configuration options.
+Visit [.generate()](https://mastra.ai/reference/v1/agents/generate) for a full list of configuration options.
 
 ### Example output
 
@@ -149,9 +149,25 @@ const response = await testAgent.generate("Analyze the TypeScript programming la
 console.log(response.object);
 ```
 
-## LLM Structured Output support
+## Combining tools and structured output
 
-Structured output support varies across LLM's due to the model itself. There are various workarounds provided to be able to use the full range of features supported for structured output, mainly returning structured output, tool calling, and the combination of the two.
+When an agent has both tools and structured output configured, some models may not support using both features together. This is a limitation of the underlying model APIs, not Mastra itself.
+
+If your tools aren't being called when structured output is enabled, or you receive an error when combining both features, try one of the workarounds below.
+
+### Workaround options
+
+When your model doesn't support tools and structured output together, you have three options:
+
+1. **Use `jsonPromptInjection: true`** - Injects the schema into the prompt instead of using the API's `response_format` parameter
+2. **Use a separate structuring model** - Pass a `model` to `structuredOutput` to use a second LLM for structuring
+3. **Use `prepareStep`** - Handle tools and structured output in separate steps
+
+Each approach is detailed in the sections below.
+
+## LLM structured output support
+
+Structured output support varies across LLMs due to differences in their APIs. The sections below cover workarounds for models that don't fully support structured output or combining it with tools.
 
 ### `jsonPromptInjection`
 
@@ -179,7 +195,11 @@ console.log(response.object);
 
 > **Gemini 2.5 with tools**
 
-Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error `Function calling with a response mime type: 'application/json' is unsupported`.
+Gemini 2.5 models do not support combining `response_format` (structured output) with function calling (tools) in the same API call. If your agent has tools and you're using `structuredOutput` with a Gemini 2.5 model, you must set `jsonPromptInjection: true` to avoid the error:
+
+```
+Function calling with a response mime type: 'application/json' is unsupported
+```
 
 ```typescript
 const response = await agentWithTools.generate("Your prompt", {

package/dist/docs/agents/06-processors.md

@@ -277,6 +277,70 @@ export class CustomOutputProcessor implements Processor {
 }
 ```
 
+#### Adding metadata in output processors
+
+You can add custom metadata to messages in `processOutputResult`. This metadata is accessible via the response object:
+
+```typescript title="src/mastra/processors/metadata-processor.ts"
+import type { Processor, MastraDBMessage } from "@mastra/core";
+
+export class MetadataProcessor implements Processor {
+  id = "metadata-processor";
+
+  async processOutputResult({
+    messages,
+  }: {
+    messages: MastraDBMessage[];
+  }): Promise<MastraDBMessage[]> {
+    return messages.map((msg) => {
+      if (msg.role === "assistant") {
+        return {
+          ...msg,
+          content: {
+            ...msg.content,
+            metadata: {
+              ...msg.content.metadata,
+              processedAt: new Date().toISOString(),
+              customData: "your data here",
+            },
+          },
+        };
+      }
+      return msg;
+    });
+  }
+}
+```
+
+Access the metadata with `generate()`:
+
+```typescript
+const result = await agent.generate("Hello");
+
+// The response includes uiMessages with processor-added metadata
+const assistantMessage = result.response?.uiMessages?.find((m) => m.role === "assistant");
+console.log(assistantMessage?.metadata?.customData);
+```
+
+Access the metadata when streaming:
+
+```typescript
+const stream = await agent.stream("Hello");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "finish") {
+    // Access response with processor-added metadata from the finish chunk
+    const uiMessages = chunk.payload.response?.uiMessages;
+    const assistantMessage = uiMessages?.find((m) => m.role === "assistant");
+    console.log(assistantMessage?.metadata?.customData);
+  }
+}
+
+// Or via the response promise after consuming the stream
+const response = await stream.response;
+console.log(response.uiMessages);
+```
+
 ## Built-in Utility Processors
 
 Mastra provides utility processors for common tasks:
@@ -377,7 +441,7 @@ const agent = new Agent({
 });
 ```
 
-When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the playground.
+When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the [Studio](https://mastra.ai/docs/v1/getting-started/studio).
 
 ## Retry mechanism
 

package/dist/docs/agents/08-agent-approval.md

@@ -85,8 +85,8 @@ export const testTool = createTool({
   resumeSchema: z.object({
     approved: z.boolean()
   }),
-  execute: async ({ location }) => {
-    const response = await fetch(`https://wttr.in/${location}?format=3`);
+  execute: async (inputData) => {
+    const response = await fetch(`https://wttr.in/${inputData.location}?format=3`);
     const weather = await response.text();
 
     return { weather };
@@ -121,7 +121,6 @@ const handleResume = async () => {
 With this approach, neither the agent nor the tool uses `requireApproval`. Instead, the tool implementation calls `suspend` to pause execution and return context or confirmation prompts to the user.
 
 ```typescript
-
 export const testToolB = createTool({
   id: "test-tool-b",
   description: "Fetches weather for a location",
@@ -137,14 +136,14 @@ export const testToolB = createTool({
   suspendSchema: z.object({
     reason: z.string()
   }),
-  execute: async ({ location }, { agent } = {}) => {
-    const { resumeData: { approved } = {}, suspend } = agent ?? {};
+  execute: async (inputData, context) => {
+    const { resumeData: { approved } = {}, suspend } = context?.agent ?? {};
 
     if (!approved) {
       return suspend?.({ reason: "Approval required." });
     }
 
-    const response = await fetch(`https://wttr.in/${location}?format=3`);
+    const response = await fetch(`https://wttr.in/${inputData.location}?format=3`);
     const weather = await response.text();
 
     return { weather };

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

@@ -0,0 +1,274 @@
+> Learn how to require approvals, suspend execution, and resume suspended networks while keeping humans in control of agent network workflows.
+
+# Network Approval
+
+Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/v1/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.
+
+## Storage
+
+Network approval uses snapshots to capture execution state. Ensure you've enabled a storage provider in your Mastra instance. If storage isn't enabled you'll see an error relating to snapshot not found.
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core/mastra";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: "mastra-storage",
+    url: ":memory:"
+  })
+});
+```
+
+## Approving network tool calls
+
+When a tool within a network has `requireApproval: true`, the network stream emits an `agent-execution-approval` chunk and pauses. To allow the tool to execute, call `approveNetworkToolCall` with the `runId`.
+
+```typescript
+const stream = await routingAgent.network("Process this query", {
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+let runId: string;
+
+for await (const chunk of stream) {
+  runId = stream.runId;
+  // if the requirApproval is in a tool inside a subAgent or the subAgent has requireToolApproval set to true
+  if (chunk.type === "agent-execution-approval") { 
+    console.log("Tool requires approval:", chunk.payload);
+  }
+
+  // if the requirApproval is in a tool directly in the network agent
+  if (chunk.type === "tool-execution-approval") {
+    console.log("Tool requires approval:", chunk.payload);
+  }
+}
+
+// Approve and resume execution
+const approvedStream = await routingAgent.approveNetworkToolCall({
+  runId,
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+for await (const chunk of approvedStream) {
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+## Declining network tool calls
+
+To decline a pending tool call and prevent execution, call `declineNetworkToolCall`. The network continues without executing the tool.
+
+```typescript
+const declinedStream = await routingAgent.declineNetworkToolCall({
+  runId,
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+for await (const chunk of declinedStream) {
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+## Resuming suspended networks
+
+When a primitive in the network calls `suspend()`, the stream emits an `agent-execution-suspended`/`tool-execution-suspended`/`workflow-execution-suspended` chunk with a `suspendPayload` containing context from the primitive. Use `resumeNetwork` to provide the data requested by the primitive and continue execution.
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+const confirmationTool = createTool({
+  id: "confirmation-tool",
+  description: "Requests user confirmation before proceeding",
+  inputSchema: z.object({
+    action: z.string()
+  }),
+  outputSchema: z.object({
+    confirmed: z.boolean(),
+    action: z.string()
+  }),
+  suspendSchema: z.object({
+    message: z.string(),
+    action: z.string()
+  }),
+  resumeSchema: z.object({
+    confirmed: z.boolean()
+  }),
+  execute: async (inputData, context) => {
+    const { resumeData, suspend } = context?.agent ?? {};
+
+    if (!resumeData?.confirmed) {
+      return suspend?.({
+        message: `Please confirm: ${inputData.action}`,
+        action: inputData.action
+      });
+    }
+
+    return { confirmed: true, action: inputData.action };
+  }
+});
+```
+
+Handle the suspension and resume with user-provided data:
+
+```typescript
+const stream = await routingAgent.network("Delete the old records", {
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === "workflow-execution-suspended") {
+    console.log(chunk.payload.suspendPayload);
+    // { message: "Please confirm: delete old records", action: "delete old records" }
+  }
+}
+
+// Resume with user confirmation
+const resumedStream = await routingAgent.resumeNetwork(
+  { confirmed: true },
+  {
+    runId: stream.runId,
+    memory: {
+      thread: "user-123",
+      resource: "my-app"
+    }
+  }
+);
+
+for await (const chunk of resumedStream) {
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+## Automatic primitive resumption
+
+When using primitives that call `suspend()`, you can enable automatic resumption so the network resumes suspended primitives based on the user's next message. This creates a conversational flow where users provide the required information naturally.
+
+### Enabling auto-resume
+
+Set `autoResumeSuspendedTools` to `true` in the agent's `defaultNetworkOptions` or when calling `network()`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+// Option 1: In agent configuration
+const routingAgent = new Agent({
+  id: "routing-agent",
+  name: "Routing Agent",
+  instructions: "You coordinate tasks across multiple agents",
+  model: "openai/gpt-4o-mini",
+  tools: { confirmationTool },
+  memory: new Memory(),
+  defaultNetworkOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+// Option 2: Per-request
+const stream = await routingAgent.network("Process this request", {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+```
+
+### How it works
+
+When `autoResumeSuspendedTools` is enabled:
+
+1. A primitive suspends execution by calling `suspend()` with a payload
+2. The suspension is persisted to memory along with the conversation
+3. When the user sends their next message on the same thread, the network:
+   - Detects the suspended primitive from message history
+   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
+   - Automatically resumes the primitive with the extracted data
+
+### Example
+
+```typescript
+const stream = await routingAgent.network("Delete the old records", {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+for await (const chunk of stream) {
+  if (chunk.type === "workflow-execution-suspended") {
+    console.log(chunk.payload.suspendPayload);
+    // { message: "Please confirm: delete old records", action: "delete old records" }
+  }
+}
+
+// User provides confirmation in their next message
+const resumedStream = await routingAgent.network("Yes, confirmed", {
+  autoResumeSuspendedTools: true,
+  memory: {
+    thread: "user-123",
+    resource: "my-app"
+  }
+});
+
+for await (const chunk of resumedStream) {
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+**Conversation flow:**
+
+```
+User: "Delete the old records"
+Agent: "Please confirm: delete old records"
+
+User: "Yes, confirmed"
+Agent: "Records deleted successfully"
+```
+
+### Requirements
+
+For automatic tool resumption to work:
+
+- **Memory configured**: The agent needs memory to track suspended tools across messages
+- **Same thread**: The follow-up message must use the same memory thread and resource identifiers
+- **`resumeSchema` defined**: The tool (either directly in the network agent or in a subAgent) / workflow (step that gets suspended) must define a `resumeSchema` so the agent knows what data to extract from the user's message
+
+### Manual vs automatic resumption
+
+| Approach | Use case |
+|----------|----------|
+| Manual (`resumeNetwork()`) | Programmatic control, webhooks, button clicks, external triggers |
+| Automatic (`autoResumeSuspendedTools`) | Conversational flows where users provide resume data in natural language |
+
+Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
+
+## Related
+
+- [Agent Networks](./networks)
+- [Agent Approval](./agent-approval)
+- [Human-in-the-Loop](https://mastra.ai/docs/v1/workflows/human-in-the-loop)
+- [Agent Memory](./agent-memory)

package/dist/docs/agents/{10-reference.md → 11-reference.md}

@@ -189,7 +189,7 @@ await agent.generateLegacy("message for agent");
 
 > **Note:**
 
-The new `.generate()` method offers enhanced capabilities including AI SDK v5 compatibility, better structured output handling, and improved streaming support. See the [migration guide](https://mastra.ai/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
+The new `.generate()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved streaming support. See the [migration guide](https://mastra.ai/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 ### Quick Migration Example
 

package/dist/docs/ai-sdk/01-reference.md

@@ -423,7 +423,7 @@ Use [`handleWorkflowStream()`](https://mastra.ai/reference/v1/ai-sdk/handle-work
 
 When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
 
-See [Workflow Streaming](https://mastra.ai/docs/v1/streaming/workflow-streaming#streaming-agent-text-chunks-to-ui) for more details.
+See [Workflow Streaming](https://mastra.ai/docs/v1/streaming/workflow-streaming) for more details.
 
 ## Usage example
 

package/dist/docs/cli/01-reference.md

@@ -23,7 +23,7 @@ The command accepts [common flags][common-flags] and the following additional fl
 
 #### `--https`
 
-Enable local HTTPS support. [Learn more](https://mastra.ai/docs/v1/getting-started/studio#local-https).
+Enable local HTTPS support. [Learn more](https://mastra.ai/reference/v1/configuration#serverhttps).
 
 #### `--inspect`
 

package/dist/docs/client-js/01-reference.md

@@ -67,12 +67,14 @@ const response = await agent.generate(
 );
 ```
 
-You can also use the simplified string format:
+You can also use the simplified string format with memory options:
 
 ```typescript
 const response = await agent.generate("Hello, how are you?", {
-  threadId: "thread-1",
-  resourceId: "resource-1",
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
 });
 ```
 
@@ -91,11 +93,14 @@ response.processDataStream({
 });
 ```
 
-You can also use the simplified string format:
+You can also use the simplified string format with memory options:
 
 ```typescript
 const response = await agent.stream("Tell me a story", {
-  threadId: "thread-1",
+  memory: {
+    thread: "thread-1",
+    resource: "resource-1",
+  },
   clientTools: { colorChangeTool },
 });