@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

package/.docs/raw/agents/agent-approval.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Agent Approval | Agents"
-description: Learn how to require approvals and suspend tool execution while keeping humans in control of agent workflows.
+description: Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/memory"
 ---
 
 # Agent Approval
@@ -20,7 +24,6 @@ import { Mastra } from "@mastra/core/mastra";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
-  // ...
   storage: new LibSQLStore({
     id: "mastra-storage",
     url: ":memory:"
@@ -33,7 +36,7 @@ export const mastra = new Mastra({
 
 When calling an agent using `.stream()` set `requireToolApproval` to `true` which will prevent the agent from calling any of the tools defined in its configuration.
 
-```typescript showLineNumbers
+```typescript
 const stream = await agent.stream("What's the weather in London?", {
   requireToolApproval: true
 });
@@ -43,7 +46,7 @@ const stream = await agent.stream("What's the weather in London?", {
 
 To approve a tool call, access `approveToolCall` from the `agent`, passing in the `runId` of the stream. This will let the agent know its now OK to call its tools.
 
-```typescript showLineNumbers
+```typescript
 const handleApproval = async () => {
   const approvedStream = await agent.approveToolCall({ runId: stream.runId });
 
@@ -58,7 +61,7 @@ const handleApproval = async () => {
 
 To decline a tool call, access the `declineToolCall` from the `agent`. You will see the streamed response from the agent, but it won't call its tools.
 
-```typescript showLineNumbers
+```typescript
 const handleDecline = async () => {
   const declinedStream = await agent.declineToolCall({ runId: stream.runId });
 
@@ -69,6 +72,67 @@ const handleDecline = async () => {
 };
 ```
 
+## Tool approval with generate()
+
+Tool approval also works with the `generate()` method for non-streaming use cases. When using `generate()` with `requireToolApproval: true`, the method returns immediately when a tool requires approval instead of executing it.
+
+### How it works
+
+When a tool requires approval during a `generate()` call, the response includes:
+
+- `finishReason: 'suspended'` - indicates the agent is waiting for approval
+- `suspendPayload` - contains tool call details (`toolCallId`, `toolName`, `args`)
+- `runId` - needed to approve or decline the tool call
+
+### Approving tool calls
+
+To approve a tool call with `generate()`, use the `approveToolCallGenerate` method:
+
+```typescript
+const output = await agent.generate("Find user John", {
+  requireToolApproval: true,
+});
+
+if (output.finishReason === "suspended") {
+  console.log("Tool requires approval:", output.suspendPayload.toolName);
+  console.log("Arguments:", output.suspendPayload.args);
+
+  // Approve the tool call and get the final result
+  const result = await agent.approveToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  console.log("Final result:", result.text);
+}
+```
+
+### Declining tool calls
+
+To decline a tool call, use the `declineToolCallGenerate` method:
+
+```typescript
+if (output.finishReason === "suspended") {
+  const result = await agent.declineToolCallGenerate({
+    runId: output.runId,
+    toolCallId: output.suspendPayload.toolCallId,
+  });
+
+  // Agent will respond acknowledging the declined tool
+  console.log(result.text);
+}
+```
+
+### Stream vs Generate comparison
+
+| Aspect | `stream()` | `generate()` |
+|--------|-----------|--------------|
+| Response type | Streaming chunks | Complete response |
+| Approval detection | `tool-call-approval` chunk | `finishReason: 'suspended'` |
+| Approve method | `approveToolCall({ runId })` | `approveToolCallGenerate({ runId, toolCallId })` |
+| Decline method | `declineToolCall({ runId })` | `declineToolCallGenerate({ runId, toolCallId })` |
+| Result | Stream to iterate | Full output object |
+
 ## Tool-level approval
 
 There are two types of tool call approval. The first uses `requireApproval`, which is a property on the tool definition, while `requireToolApproval` is a parameter passed to `agent.stream()`. The second uses `suspend` and lets the agent provide context or confirmation prompts so the user can decide whether the tool call should continue.
@@ -90,8 +154,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 };
@@ -127,7 +191,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",
@@ -143,14 +206,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 };
@@ -180,10 +243,144 @@ const handleResume = async () => {
 
 ```
 
+## Automatic tool resumption
+
+When using tools that call `suspend()`, you can enable automatic resumption so the agent resumes suspended tools based on the user's next message. This creates a conversational flow where users provide the required information naturally, without your application needing to call `resumeStream()` explicitly.
+
+### Enabling auto-resume
+
+Set `autoResumeSuspendedTools` to `true` in the agent's default options or when calling `stream()`:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+// Option 1: In agent configuration
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+// Option 2: Per-request
+const stream = await agent.stream("What's the weather?", {
+  autoResumeSuspendedTools: true,
+});
+```
+
+### How it works
+
+When `autoResumeSuspendedTools` is enabled:
+
+1. A tool suspends execution by calling `suspend()` with a payload (e.g., requesting more information)
+2. The suspension is persisted to memory along with the conversation
+3. When the user sends their next message on the same thread, the agent:
+   - Detects the suspended tool from message history
+   - Extracts `resumeData` from the user's message based on the tool's `resumeSchema`
+   - Automatically resumes the tool with the extracted data
+
+### Example
+
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const weatherTool = createTool({
+  id: "weather-info",
+  description: "Fetches weather information for a city",
+  suspendSchema: z.object({
+    message: z.string(),
+  }),
+  resumeSchema: z.object({
+    city: z.string(),
+  }),
+  execute: async (_inputData, context) => {
+    // Check if this is a resume with data
+    if (!context?.agent?.resumeData) {
+      // First call - suspend and ask for the city
+      return context?.agent?.suspend({
+        message: "What city do you want to know the weather for?",
+      });
+    }
+
+    // Resume call - city was extracted from user's message
+    const { city } = context.agent.resumeData;
+    const response = await fetch(`https://wttr.in/${city}?format=3`);
+    const weather = await response.text();
+
+    return { city, weather };
+  },
+});
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "openai/gpt-4o-mini",
+  tools: { weatherTool },
+  memory: new Memory(),
+  defaultOptions: {
+    autoResumeSuspendedTools: true,
+  },
+});
+
+const stream = await agent.stream("What's the weather like?");
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === "tool-call-suspended") {
+    console.log(chunk.payload.suspendPayload);
+  }
+}
+
+const handleResume = async () => {
+  const resumedStream = await agent.stream("San Francisco");
+
+  for await (const chunk of resumedStream.textStream) {
+    process.stdout.write(chunk);
+  }
+  process.stdout.write("\n");
+};
+```
+
+**Conversation flow:**
+
+```
+User: "What's the weather like?"
+Agent: "What city do you want to know the weather for?"
+
+User: "San Francisco"
+Agent: "The weather in San Francisco is: San Francisco: ☀️ +72°F"
+```
+
+The second message automatically resumes the suspended tool - the agent extracts `{ city: "San Francisco" }` from the user's message and passes it as `resumeData`.
+
+### 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 must define a `resumeSchema` so the agent knows what data structure to extract from the user's message
+
+### Manual vs automatic resumption
+
+| Approach | Use case |
+|----------|----------|
+| Manual (`resumeStream()`) | 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
 
 - [Using Tools](./using-tools)
 - [Agent Overview](./overview)
 - [Tools Overview](../mcp/overview)
 - [Agent Memory](./agent-memory)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/agents/agent-memory.mdx

@@ -1,6 +1,10 @@
 ---
 title: "Agent Memory | Agents"
-description: Learn how to add memory to agents to store conversation history and maintain context across interactions.
+description: Learn how to add memory to agents to store message history and maintain context across interactions.
+packages:
+  - "@mastra/core"
+  - "@mastra/libsql"
+  - "@mastra/memory"
 ---
 
 import Steps from "@site/src/components/Steps";
@@ -8,9 +12,9 @@ import StepItem from "@site/src/components/StepItem";
 
 # Agent memory
 
-Agents use memory to maintain context across interactions. LLMs are stateless and don't retain information between calls, so agents need memory to track conversation history and recall relevant information.
+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 conversation history, with optional [working memory](../memory/working-memory) to maintain recent context or [semantic recall](../memory/semantic-recall) to retrieve past messages based on meaning.
+Mastra agents can be configured to store message history, with optional [working memory](../memory/working-memory) to maintain recent context or [semantic recall](../memory/semantic-recall) to retrieve past messages based on meaning.
 
 ## When to use memory
 
@@ -20,13 +24,13 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 To enable memory in Mastra, install the `@mastra/memory` package along with a storage provider.
 
-```bash npm2yarn copy
+```bash npm2yarn
 npm install @mastra/memory@beta @mastra/libsql@beta
 ```
 
 ## Storage providers
 
-Memory requires a storage provider to persist conversation history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/server-db/storage) documentation.
+Memory requires a storage provider to persist message history, including user messages and agent responses. For more details on available providers and how storage works in Mastra, see the [Storage](/docs/v1/memory/storage) documentation.
 
 ## Configuring memory
 
@@ -35,14 +39,13 @@ Memory requires a storage provider to persist conversation history, including us
 
 Enable memory by creating a `Memory` instance and passing it to the agent’s `memory` option.
 
-```typescript {6-9} title="src/mastra/agents/memory-agent.ts" copy
+```typescript {7-11} title="src/mastra/agents/memory-agent.ts"
 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: {
       lastMessages: 20,
@@ -51,9 +54,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
-:::note
+:::info
 
-See the [Memory Class](/reference/v1/memory/memory-class) docs for a full list of configuration options.
+Visit [Memory Class](/reference/v1/memory/memory-class) for a full list of configuration options.
 
 :::
 
@@ -63,12 +66,11 @@ See the [Memory Class](/reference/v1/memory/memory-class) docs for a full list o
 
 Add a storage provider to your main Mastra instance to enable memory across all configured agents.
 
-```typescript {6-8} title="src/mastra/index.ts" copy
+```typescript {5-8} title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 export const mastra = new Mastra({
-  // ..
   storage: new LibSQLStore({
     id: 'mastra-storage',
     url: ":memory:",
@@ -76,9 +78,9 @@ export const mastra = new Mastra({
 });
 ```
 
-:::note
+:::info
 
-See the [LibSQL Storage](/reference/v1/storage/libsql) docs for a full list of configuration options.
+Visit [libSQL Storage](/reference/v1/storage/libsql) for a full list of configuration options.
 
 :::
 
@@ -87,7 +89,7 @@ See the [LibSQL Storage](/reference/v1/storage/libsql) docs for a full list of c
 
 Alternatively, add storage directly to an agent’s memory to keep data separate or use different providers per agent.
 
-```typescript {7-10} title="src/mastra/agents/memory-agent.ts" copy
+```typescript {9-12} title="src/mastra/agents/memory-agent.ts"
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -95,7 +97,6 @@ import { LibSQLStore } from "@mastra/libsql";
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
-  // ...
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'mastra-storage',
@@ -105,16 +106,20 @@ export const memoryAgent = new Agent({
 });
 ```
 
-## Conversation history
+:::warning[Mastra Cloud Store limitation]
+Agent-level storage is not supported when using [Mastra Cloud Store](/docs/v1/mastra-cloud/deployment#using-mastra-cloud-store). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+:::
+
+## Message history
 
-Include a `memory` object with both `resource` and `thread` to track conversation history during agent calls.
+Include a `memory` object with both `resource` and `thread` to track message history during agent calls.
 
 - `resource`: A stable identifier for the user or entity.
 - `thread`: An ID that isolates a specific conversation or session.
 
 These fields tell the agent where to store and retrieve context, enabling persistent, thread-aware memory across a conversation.
 
-```typescript {5-6}
+```typescript {4-7}
 const response = await memoryAgent.generate(
   "Remember my favorite color is blue.",
   {
@@ -128,7 +133,7 @@ const response = await memoryAgent.generate(
 
 To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
 
-```typescript {3-4}
+```typescript {2-5}
 const response = await memoryAgent.generate("What's my favorite color?", {
   memory: {
     resource: "user-123",
@@ -137,29 +142,28 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 });
 ```
 
+:::warning
+Each thread has an owner (`resourceId`) that cannot be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+:::
+
 To learn more about memory see the [Memory](../memory/overview) documentation.
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+Use [RequestContext](/docs/v1/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.
 
-```typescript title="src/mastra/agents/memory-agent.ts" showLineNumbers
+```typescript title="src/mastra/agents/memory-agent.ts"
 export type UserTier = {
   "user-tier": "enterprise" | "pro";
 };
 
-const premiumMemory = new Memory({
-  // ...
-});
+const premiumMemory = new Memory();
 
-const standardMemory = new Memory({
-  // ...
-});
+const standardMemory = new Memory();
 
 export const memoryAgent = new Agent({
   id: 'memory-agent',
   name: 'Memory Agent',
-  // ...
   memory: ({ requestContext }) => {
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
@@ -168,9 +172,9 @@ export const memoryAgent = new Agent({
 });
 ```
 
-:::note
+:::info
 
-See [Request Context](/docs/v1/server-db/request-context) docs for more information.
+Visit [Request Context](/docs/v1/server/request-context) for more information.
 
 :::
 
@@ -178,5 +182,5 @@ See [Request Context](/docs/v1/server-db/request-context) docs for more informat
 
 - [Working Memory](../memory/working-memory)
 - [Semantic Recall](../memory/semantic-recall)
-- [Threads and Resources](../memory/threads-and-resources)
-- [Request Context](/docs/v1/server-db/request-context)
+- [Storage](../memory/storage)
+- [Request Context](/docs/v1/server/request-context)