@mastra/mcp-docs-server 1.0.0-beta.4 → 1.0.0-beta.6

package/.docs/raw/agents/guardrails.mdx

@@ -22,8 +22,7 @@ Use processors for content moderation, prompt injection prevention, response san
 
 Import and instantiate the relevant processor class, and pass it to your agent’s configuration using either the `inputProcessors` or `outputProcessors` option:
 
-```typescript {3,9-17} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {2,8-16} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 import { ModerationProcessor } from "@mastra/core/processors";
 
@@ -31,10 +30,10 @@ export const moderatedAgent = new Agent({
   id: "moderated-agent",
   name: "Moderated Agent",
   instructions: "You are a helpful assistant",
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   inputProcessors: [
     new ModerationProcessor({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       categories: ["hate", "harassment", "violence"],
       threshold: 0.7,
       strategy: "block",
@@ -52,7 +51,7 @@ Input processors are applied before user messages reach the language model. They
 
 The `UnicodeNormalizer` is an input processor that cleans and normalizes user input by unifying Unicode characters, standardizing whitespace, and removing problematic symbols, allowing the LLM to better understand user messages.
 
-```typescript {6-9} title="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
+```typescript {8-11} title="src/mastra/agents/normalized-agent.ts" showLineNumbers copy
 import { UnicodeNormalizer } from "@mastra/core/processors";
 
 export const normalizedAgent = new Agent({
@@ -74,7 +73,7 @@ export const normalizedAgent = new Agent({
 
 The `PromptInjectionDetector` is an input processor that scans user messages for prompt injection, jailbreak attempts, and system override patterns. It uses an LLM to classify risky input and can block or rewrite it before it reaches the model.
 
-```typescript {6-11} title="src/mastra/agents/secure-agent.ts" showLineNumbers copy
+```typescript {8-13} title="src/mastra/agents/secure-agent.ts" showLineNumbers copy
 import { PromptInjectionDetector } from "@mastra/core/processors";
 
 export const secureAgent = new Agent({
@@ -83,7 +82,7 @@ export const secureAgent = new Agent({
   // ...
   inputProcessors: [
     new PromptInjectionDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.8,
       strategy: "rewrite",
       detectionTypes: ["injection", "jailbreak", "system-override"],
@@ -98,7 +97,7 @@ export const secureAgent = new Agent({
 
 The `LanguageDetector` is an input processor that detects and translates user messages into a target language, enabling multilingual support while maintaining consistent interaction. It uses an LLM to identify the language and perform the translation.
 
-```typescript {6-11} title="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
+```typescript {8-13} title="src/mastra/agents/multilingual-agent.ts" showLineNumbers copy
 import { LanguageDetector } from "@mastra/core/processors";
 
 export const multilingualAgent = new Agent({
@@ -107,7 +106,7 @@ export const multilingualAgent = new Agent({
   // ...
   inputProcessors: [
     new LanguageDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       targetLanguages: ["English", "en"],
       strategy: "translate",
       threshold: 0.8,
@@ -126,7 +125,7 @@ Output processors are applied after the language model generates a response, but
 
 The `BatchPartsProcessor` is an output processor that combines multiple stream parts before emitting them to the client. This reduces network overhead and improves the user experience by consolidating small chunks into larger batches.
 
-```typescript {6-10} title="src/mastra/agents/batched-agent.ts" showLineNumbers copy
+```typescript {8-12} title="src/mastra/agents/batched-agent.ts" showLineNumbers copy
 import { BatchPartsProcessor } from "@mastra/core/processors";
 
 export const batchedAgent = new Agent({
@@ -149,7 +148,7 @@ export const batchedAgent = new Agent({
 
 The `TokenLimiterProcessor` is an output processor that limits the number of tokens in model responses. It helps manage cost and performance by truncating or blocking messages when the limit is exceeded.
 
-```typescript {6-10, 13-15} title="src/mastra/agents/limited-agent.ts" showLineNumbers copy
+```typescript {8-12} title="src/mastra/agents/limited-agent.ts" showLineNumbers copy
 import { TokenLimiterProcessor } from "@mastra/core/processors";
 
 export const limitedAgent = new Agent({
@@ -172,7 +171,7 @@ export const limitedAgent = new Agent({
 
 The `SystemPromptScrubber` is an output processor that detects and redacts system prompts or other internal instructions from model responses. It helps prevent unintended disclosure of prompt content or configuration details that could introduce security risks. It uses an LLM to identify and redact sensitive content based on configured detection types.
 
-```typescript {5-13} title="src/mastra/agents/scrubbed-agent.ts" copy showLineNumbers
+```typescript {7-16} title="src/mastra/agents/scrubbed-agent.ts" copy showLineNumbers
 import { SystemPromptScrubber } from "@mastra/core/processors";
 
 const scrubbedAgent = new Agent({
@@ -180,7 +179,7 @@ const scrubbedAgent = new Agent({
   name: "Scrubbed Agent",
   outputProcessors: [
     new SystemPromptScrubber({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       strategy: "redact",
       customPatterns: ["system prompt", "internal instructions"],
       includeDetections: true,
@@ -195,6 +194,10 @@ const scrubbedAgent = new Agent({
 
 > See [SystemPromptScrubber](/reference/v1/processors/system-prompt-scrubber) for a full list of configuration options.
 
+:::note
+When streaming responses over HTTP, Mastra redacts sensitive request data (system prompts, tool definitions, API keys) from stream chunks at the server level by default. See [Stream data redaction](/docs/v1/server-db/mastra-server#stream-data-redaction) for details.
+:::
+
 ## Hybrid processors
 
 Hybrid processors can be applied either before messages are sent to the language model or before responses are returned to the user. They are useful for tasks like content moderation and PII redaction.
@@ -203,7 +206,7 @@ Hybrid processors can be applied either before messages are sent to the language
 
 The `ModerationProcessor` is a hybrid processor that detects inappropriate or harmful content across categories like hate, harassment, and violence. It can be used to moderate either user input or model output, depending on where it's applied. It uses an LLM to classify the message and can block or rewrite it based on your configuration.
 
-```typescript {6-11, 14-16} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+```typescript {8-13,16-18} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
 import { ModerationProcessor } from "@mastra/core/processors";
 
 export const moderatedAgent = new Agent({
@@ -212,7 +215,7 @@ export const moderatedAgent = new Agent({
   // ...
   inputProcessors: [
     new ModerationProcessor({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.7,
       strategy: "block",
       categories: ["hate", "harassment", "violence"],
@@ -232,7 +235,7 @@ export const moderatedAgent = new Agent({
 
 The `PIIDetector` is a hybrid processor that detects and removes personally identifiable information such as emails, phone numbers, and credit cards. It can redact either user input or model output, depending on where it's applied. It uses an LLM to identify sensitive content based on configured detection types.
 
-```typescript {6-13, 16-18} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
+```typescript {8-15,18-20} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
 import { PIIDetector } from "@mastra/core/processors";
 
 export const privateAgent = new Agent({
@@ -241,7 +244,7 @@ export const privateAgent = new Agent({
   // ...
   inputProcessors: [
     new PIIDetector({
-      model: openai("gpt-4.1-nano"),
+      model: "openrouter/openai/gpt-oss-safeguard-20b",
       threshold: 0.6,
       strategy: "redact",
       redactionMethod: "mask",
@@ -306,7 +309,7 @@ Many of the built-in processors support a `strategy` parameter that controls how
 
 Most strategies allow the request to continue without interruption. When `block` is used, the processor calls its internal `abort()` function, which immediately stops the request and prevents any subsequent processors from running.
 
-```typescript {8} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
+```typescript {10} title="src/mastra/agents/private-agent.ts" showLineNumbers copy
 import { PIIDetector } from "@mastra/core/processors";
 
 export const privateAgent = new Agent({
@@ -330,7 +333,7 @@ For example, if an agent uses the `PIIDetector` with `strategy: "block"` and the
 
 #### `.generate()` example
 
-```typescript {3-4, } showLineNumbers
+```typescript showLineNumbers
 const result = await agent.generate(
   "Is this credit card number valid?: 4543 1374 5089 4332",
 );
@@ -341,7 +344,7 @@ console.error(result.tripwireReason);
 
 #### `.stream()` example
 
-```typescript {4-5} showLineNumbers
+```typescript showLineNumbers
 const stream = await agent.stream(
   "Is this credit card number valid?: 4543 1374 5089 4332",
 );
@@ -365,6 +368,6 @@ If the built-in processors don’t cover your needs, you can create your own by
 
 Available examples:
 
-- [Message Length Limiter](/examples/v1/processors/message-length-limiter)
-- [Response Length Limiter](/examples/v1/processors/response-length-limiter)
-- [Response Validator](/examples/v1/processors/response-validator)
+- [Message Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-message-length-limiter)
+- [Response Length Limiter](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-length-limiter)
+- [Response Validator](https://github.com/mastra-ai/mastra/tree/main/examples/processors-response-validator)

package/.docs/raw/agents/networks.mdx

@@ -24,7 +24,6 @@ Mastra agent networks operate using these principles:
 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.
 
 ```typescript {22-23,26,29} title="src/mastra/agents/routing-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
 import { Agent } from "@mastra/core/agent";
 import { Memory } from "@mastra/memory";
 import { LibSQLStore } from "@mastra/libsql";
@@ -44,7 +43,7 @@ export const routingAgent = new Agent({
       Always respond with a complete report—no bullet points.
       Write in full paragraphs, like a blog post.
       Do not answer with incomplete or uncertain information.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   agents: {
     researchAgent,
     writingAgent,
@@ -241,3 +240,4 @@ network-execution-event-step-finish
 - [Agent Memory](./agent-memory)
 - [Workflows Overview](../workflows/overview)
 - [Request Context](/docs/v1/server-db/request-context)
+- [Supervisor example](https://github.com/mastra-ai/mastra/tree/main/examples/supervisor-agent)

package/.docs/raw/agents/overview.mdx

@@ -21,10 +21,9 @@ An introduction to agents, and how they compare to workflows on [YouTube (7 minu
 :::
 
 ## Setting up agents
+### Installation
 
-<Tabs>
-  <TabItem value="mastra-model-router" label="Model router">
-    <Steps>
+<Steps>
 
 <StepItem>
 
@@ -63,63 +62,13 @@ export const testAgent = new Agent({
   id: "test-agent",
   name: "Test Agent",
   instructions: "You are a helpful assistant.",
-  model: "openai/gpt-4o-mini",
+  model: "openai/gpt-5.1",
 });
 ```
 
 </StepItem>
 
 </Steps>
-  </TabItem>
-  <TabItem value="vercel-ai-sdk" label="Vercel AI SDK">
-    <Steps>
-
-<StepItem>
-
-Include the Mastra core package alongside the Vercel AI SDK provider you want to use:
-
-```bash
-npm install @mastra/core@beta @ai-sdk/openai
-```
-
-</StepItem>
-
-<StepItem>
-
-Set the corresponding environment variable for your provider. For OpenAI via the AI SDK:
-
-```bash title=".env" copy
-OPENAI_API_KEY=<your-api-key>
-```
-
-:::note
-
-See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs for additional configuration options.
-
-:::
-
-</StepItem>
-
-<StepItem>
-
-To create an agent in Mastra, use the `Agent` class. Every agent must include `instructions` to define its behavior, and a `model` parameter to specify the LLM provider and model. When using the Vercel AI SDK, provide the client to your agent's `model` field:
-
-```typescript title="src/mastra/agents/test-agent.ts" copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-
-export const testAgent = new Agent({
-  id: "test-agent",
-  name: "Test Agent",
-  instructions: "You are a helpful assistant.",
-  model: openai("gpt-4o-mini"),
-});
-```
-
-</StepItem>
-    </Steps>
-  </TabItem>
-</Tabs>
 
 ### Instruction formats
 
@@ -296,9 +245,9 @@ const response = await testAgent.generate(
 console.log(response.object);
 ```
 
-### With Tool Calling
+### Structuring sub agent
 
-Use the `model` property to ensure that your agent can execute multi-step LLM calls with tool calling.
+Use the `model` property to have a separate agent generate the structured output for you.
 
 ```typescript showLineNumbers copy
 import { z } from "zod";
@@ -320,7 +269,7 @@ const response = await testAgentWithTools.generate(
         summary: z.string(),
         keywords: z.array(z.string()),
       }),
-      model: "openai/gpt-4o",
+      model: "openai/gpt-5.1",
     },
   },
 );
@@ -361,7 +310,22 @@ const response = await testAgentThatDoesntSupportStructuredOutput.generate(
 console.log(response.object);
 ```
 
-## Working with images
+:::info[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`.
+
+```typescript
+const response = await agentWithTools.generate("Your prompt", {
+  structuredOutput: {
+    schema: yourSchema,
+    jsonPromptInjection: true, // Required for Gemini 2.5 when tools are present
+  },
+});
+```
+
+:::
+
+## Analyzing images
 
 Agents can analyze and describe images by processing both the visual content and any text within them. To enable image analysis, pass an object with `type: 'image'` and the image URL in the `content` array. You can combine image content with text prompts to guide the agent's analysis.
 
@@ -386,7 +350,8 @@ const response = await testAgent.generate([
 console.log(response.text);
 ```
 
-### Using `maxSteps`
+
+## Using `maxSteps`
 
 The `maxSteps` parameter controls the maximum number of sequential LLM calls an agent can make. Each step includes generating a response, executing any tool calls, and processing the result. Limiting steps helps prevent infinite loops, reduce latency, and control token usage for agents that use tools. The default is 1, but can be increased:
 
@@ -398,7 +363,7 @@ const response = await testAgent.generate("Help me organize my day", {
 console.log(response.text);
 ```
 
-### Using `onStepFinish`
+## Using `onStepFinish`
 
 You can monitor the progress of multi-step operations using the `onStepFinish` callback. This is useful for debugging or providing progress updates to users.
 
@@ -444,8 +409,8 @@ export const testAgent = new Agent({
     const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
 
     return userTier === "enterprise"
-      ? openai("gpt-4o-mini")
-      : openai("gpt-4.1-nano");
+      ? "openai/gpt-5"
+      : "openai/gpt-4.1-nano";
   },
 });
 ```

package/.docs/raw/agents/processors.mdx

@@ -0,0 +1,279 @@
+---
+title: "Processors | Agents | Mastra Docs"
+description: "Learn how to use input and output processors to transform, validate, and control messages in Mastra agents."
+---
+
+# Processors
+
+Processors transform, validate, or control messages as they pass through an agent. They run at specific points in the agent's execution pipeline, allowing you to modify inputs before they reach the language model or outputs before they're returned to users.
+
+Processors are configured as:
+
+- **`inputProcessors`**: Run before messages reach the language model.
+- **`outputProcessors`**: Run after the language model generates a response, but before it's returned to users.
+
+Some processors implement both input and output logic and can be used in either array depending on where the transformation should occur.
+
+## When to use processors
+
+Use processors to:
+
+- Normalize or validate user input
+- Add guardrails to your agent
+- Detect and prevent prompt injection or jailbreak attempts
+- Moderate content for safety or compliance
+- Transform messages (e.g., translate languages, filter tool calls)
+- Limit token usage or message history length
+- Redact sensitive information (PII)
+- Apply custom business logic to messages
+
+Mastra includes several processors for common use cases. You can also create custom processors for application-specific requirements.
+
+## Adding processors to an agent
+
+Import and instantiate the processor, then pass it to the agent's `inputProcessors` or `outputProcessors` array:
+
+```typescript {3,9-15} title="src/mastra/agents/moderated-agent.ts" showLineNumbers copy
+import { openai } from "@ai-sdk/openai";
+import { Agent } from "@mastra/core/agent";
+import { ModerationProcessor } from "@mastra/core/processors";
+
+export const moderatedAgent = new Agent({
+  name: "moderated-agent",
+  instructions: "You are a helpful assistant",
+  model: openai("gpt-4o-mini"),
+  inputProcessors: [
+    new ModerationProcessor({
+      model: openai("gpt-4.1-nano"),
+      categories: ["hate", "harassment", "violence"],
+      threshold: 0.7,
+      strategy: "block",
+    }),
+  ],
+});
+```
+
+## Execution order
+
+Processors run in the order they appear in the array:
+
+```typescript
+inputProcessors: [
+  new UnicodeNormalizer(),
+  new PromptInjectionDetector(),
+  new ModerationProcessor(),
+];
+```
+
+For output processors, the order determines the sequence of transformations applied to the model's response.
+
+### With memory enabled
+
+When memory is enabled on an agent, memory processors are automatically added to the pipeline:
+
+**Input processors:**
+```
+[Memory Processors] → [Your inputProcessors]
+```
+Memory loads conversation history first, then your processors run.
+
+**Output processors:**
+```
+[Your outputProcessors] → [Memory Processors]
+```
+Your processors run first, then memory persists messages.
+
+This ordering ensures that if your output guardrail calls `abort()`, memory processors are skipped and no messages are saved. See [Memory Processors](/docs/v1/memory/memory-processors#processor-execution-order) for details.
+
+## Creating custom processors
+
+Custom processors implement the `Processor` interface:
+
+### Custom input processor
+
+```typescript title="src/mastra/processors/custom-input.ts" showLineNumbers copy
+import type {
+  Processor,
+  MastraDBMessage,
+  RequestContext,
+} from "@mastra/core";
+
+export class CustomInputProcessor implements Processor {
+  id = "custom-input";
+
+  async processInput({
+    messages,
+    systemMessages,
+    context,
+  }: {
+    messages: MastraDBMessage[];
+    systemMessages: CoreMessage[];
+    context: RequestContext;
+  }): Promise<MastraDBMessage[]> {
+    // Transform messages before they reach the LLM
+    return messages.map((msg) => ({
+      ...msg,
+      content: {
+        ...msg.content,
+        content: msg.content.content.toLowerCase(),
+      },
+    }));
+  }
+}
+```
+
+The `processInput` method receives:
+- `messages`: User and assistant messages (not system messages)
+- `systemMessages`: All system messages (agent instructions, memory context, user-provided system prompts)
+- `messageList`: The full MessageList instance for advanced use cases
+- `abort`: Function to stop processing and return early
+- `requestContext`: Execution metadata like `threadId` and `resourceId`
+
+The method can return:
+- `MastraDBMessage[]` — Transformed messages array (backward compatible)
+- `{ messages: MastraDBMessage[]; systemMessages: CoreMessage[] }` — Both messages and modified system messages
+
+The framework handles both return formats, so modifying system messages is optional and existing processors continue to work.
+
+### Modifying system messages
+
+To modify system messages (e.g., trim verbose prompts for smaller models), return an object with both `messages` and `systemMessages`:
+
+```typescript title="src/mastra/processors/system-trimmer.ts" showLineNumbers copy
+import type { Processor, CoreMessage, MastraDBMessage } from "@mastra/core";
+
+export class SystemTrimmer implements Processor {
+  id = "system-trimmer";
+
+  async processInput({
+    messages,
+    systemMessages,
+  }): Promise<{ messages: MastraDBMessage[]; systemMessages: CoreMessage[] }> {
+    // Trim system messages for smaller models
+    const trimmedSystemMessages = systemMessages.map((msg) => ({
+      ...msg,
+      content:
+        typeof msg.content === "string"
+          ? msg.content.substring(0, 500)
+          : msg.content,
+    }));
+
+    return { messages, systemMessages: trimmedSystemMessages };
+  }
+}
+```
+
+This is useful for:
+- Trimming verbose system prompts for models with smaller context windows
+- Filtering or modifying semantic recall content to prevent "prompt too long" errors
+- Dynamically adjusting system instructions based on the conversation
+
+### Custom output processor
+
+```typescript title="src/mastra/processors/custom-output.ts" showLineNumbers copy
+import type {
+  Processor,
+  MastraDBMessage,
+  RequestContext,
+} from "@mastra/core";
+
+export class CustomOutputProcessor implements Processor {
+  id = "custom-output";
+
+  async processOutputResult({
+    messages,
+    context,
+  }: {
+    messages: MastraDBMessage[];
+    context: RequestContext;
+  }): Promise<MastraDBMessage[]> {
+    // Transform messages after the LLM generates them
+    return messages.filter((msg) => msg.role !== "system");
+  }
+
+  async processOutputStream({
+    stream,
+    context,
+  }: {
+    stream: ReadableStream;
+    context: RequestContext;
+  }): Promise<ReadableStream> {
+    // Transform streaming responses
+    return stream;
+  }
+}
+```
+
+## Built-in Utility Processors
+
+Mastra provides utility processors for common tasks:
+
+**For security and validation processors**, see the [Guardrails](/docs/v1/agents/guardrails) page for input/output guardrails and moderation processors.
+**For memory-specific processors**, see the [Memory Processors](/docs/v1/memory/memory-processors) page for processors that handle message history, semantic recall, and working memory.
+
+### TokenLimiter
+
+Prevents context window overflow by removing older messages when the total token count exceeds a specified limit.
+
+```typescript copy showLineNumbers {9-12}
+import { Agent } from "@mastra/core/agent";
+import { TokenLimiter } from "@mastra/core/processors";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  name: "my-agent",
+  model: openai("gpt-4o"),
+  inputProcessors: [
+    // Ensure the total tokens don't exceed ~127k
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+The `TokenLimiter` uses the `o200k_base` encoding by default (suitable for GPT-4o). You can specify other encodings for different models:
+
+```typescript copy showLineNumbers {6-9}
+import cl100k_base from "js-tiktoken/ranks/cl100k_base";
+
+const agent = new Agent({
+  name: "my-agent",
+  inputProcessors: [
+    new TokenLimiter({
+      limit: 16000, // Example limit for a 16k context model
+      encoding: cl100k_base,
+    }),
+  ],
+});
+```
+
+### ToolCallFilter
+
+Removes tool calls from messages sent to the LLM, saving tokens by excluding potentially verbose tool interactions.
+
+```typescript copy showLineNumbers {5-14}
+import { Agent } from "@mastra/core/agent";
+import { ToolCallFilter, TokenLimiter } from "@mastra/core/processors";
+import { openai } from "@ai-sdk/openai";
+
+const agent = new Agent({
+  name: "my-agent",
+  model: openai("gpt-4o"),
+  inputProcessors: [
+    // Example 1: Remove all tool calls/results
+    new ToolCallFilter(),
+
+    // Example 2: Remove only specific tool calls
+    new ToolCallFilter({ exclude: ["generateImageTool"] }),
+
+    // Always place TokenLimiter last
+    new TokenLimiter(127000),
+  ],
+});
+```
+
+> **Note:** The example above filters tool calls and limits tokens for the LLM, but these filtered messages will still be saved to memory. To also filter messages before they're saved to memory, manually add memory processors before utility processors. See [Memory Processors](/docs/v1/memory/memory-processors#manual-control-and-deduplication) for details.
+
+## Related documentation
+
+- [Guardrails](/docs/v1/agents/guardrails) - Security and validation processors
+- [Memory Processors](/docs/v1/memory/memory-processors) - Memory-specific processors and automatic integration

package/.docs/raw/agents/using-tools.mdx

@@ -47,8 +47,7 @@ To make a tool available to an agent, add it to `tools`. Mentioning available to
 
 An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
 
-```typescript {9,11} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
+```typescript {8,10} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
 import { weatherTool } from "../tools/weather-tool";
 
@@ -58,7 +57,7 @@ export const weatherAgent = new Agent({
   instructions: `
       You are a helpful weather assistant.
       Use the weatherTool to fetch current weather data.`,
-  model: openai("gpt-4o-mini"),
+  model: "openai/gpt-5.1",
   tools: { weatherTool },
 });
 ```
@@ -67,7 +66,7 @@ export const weatherAgent = new 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 {5} title="src/test-tool.ts" showLineNumbers copy
+```typescript title="src/test-tool.ts" showLineNumbers copy
 import { mastra } from "./mastra";
 
 const agent = mastra.getAgent("weatherAgent");
@@ -79,7 +78,7 @@ const result = await agent.generate("What's the weather in London?");
 
 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 {6} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
+```typescript {8} title="src/mastra/agents/weather-agent.ts" showLineNumbers copy
 import { weatherTool } from "../tools/weather-tool";
 import { activitiesTool } from "../tools/activities-tool";