@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.11

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

@@ -1,5 +1,5 @@
 ---
-title: "Using Agents | Agents | Mastra Docs"
+title: "Using Agents | Agents"
 description: Overview of agents in Mastra, detailing their capabilities and how they interact with tools, workflows, and external systems.
 ---
 
@@ -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
 
@@ -187,13 +136,11 @@ You can call agents from workflow steps, tools, the Mastra Client, or the comman
 const testAgent = mastra.getAgent("testAgent");
 ```
 
-:::info
+::::info
 
 `mastra.getAgent()` is preferred over a direct import, since it provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores).
 
-See [Calling agents](/examples/v1/agents/calling-agents) for more information.
-
-:::
+::::
 
 ## Generating responses
 
@@ -265,105 +212,11 @@ for await (const chunk of stream.textStream) {
 
 ## Structured output
 
-Agents can return structured, type-safe data by defining the expected output using either [Zod](https://zod.dev/) or [JSON Schema](https://json-schema.org/). We recommend Zod for better TypeScript support and developer experience. The parsed result is available on `response.object`, allowing you to work directly with validated and typed data.
-
-### Using Zod
-
-Define the `output` shape using [Zod](https://zod.dev/):
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgent.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Monkey, Ice Cream, Boat",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string()),
-      }),
-    },
-  },
-);
+Agents can return structured, type-safe data using Zod or JSON Schema. The parsed result is available on `response.object`.
 
-console.log(response.object);
-```
-
-### With Tool Calling
-
-Use the `model` property to ensure that your agent can execute multi-step LLM calls with tool calling.
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgentWithTools.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Please use your test tool and let me know the results",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string()),
-      }),
-      model: "openai/gpt-4o",
-    },
-  },
-);
-
-console.log(response.object);
-console.log(response.toolResults);
-```
-
-### Response format
-
-By default `structuredOutput` will use `response_format` to pass the schema to the model provider. If the model provider does not natively support `response_format` it's possible that this will error or not give the desired results. To keep using the same model use `jsonPromptInjection` to bypass response format and inject a system prompt message to coerce the model to return structured output.
-
-```typescript showLineNumbers copy
-import { z } from "zod";
-
-const response = await testAgentThatDoesntSupportStructuredOutput.generate(
-  [
-    {
-      role: "system",
-      content: "Provide a summary and keywords for the following text:",
-    },
-    {
-      role: "user",
-      content: "Monkey, Ice Cream, Boat",
-    },
-  ],
-  {
-    structuredOutput: {
-      schema: z.object({
-        summary: z.string(),
-        keywords: z.array(z.string()),
-      }),
-      jsonPromptInjection: true,
-    },
-  },
-);
-
-console.log(response.object);
-```
+> See [Structured Output](/docs/v1/agents/structured-output) for more information.
 
-## Working with images
+## 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.
 
@@ -388,21 +241,20 @@ const response = await testAgent.generate([
 console.log(response.text);
 ```
 
-For a detailed guide to creating and configuring tools, see the [Tools Overview](../tools-mcp/overview) page.
 
-### 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:
 
 ```typescript showLineNumbers copy
 const response = await testAgent.generate("Help me organize my day", {
-  maxSteps: 5,
+  maxSteps: 10,
 });
 
 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.
 
@@ -429,7 +281,7 @@ export const testAgent = new Agent({
 });
 ```
 
-> See [Using Tools](./using-tools) for more information.
+> See [Using Tools](/docs/v1/agents/using-tools) for more information.
 
 ## Using `RequestContext`
 
@@ -448,8 +300,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";
   },
 });
 ```
@@ -462,7 +314,6 @@ Use [Studio](/docs/v1/getting-started/studio) to test agents with different mess
 
 ## Related
 
-- [Using Tools](./using-tools)
-- [Agent Memory](./agent-memory)
-- [Request Context](/examples/v1/agents/request-context)
-- [Calling Agents](/examples/v1/agents/calling-agents)
+- [Using Tools](/docs/v1/agents/using-tools)
+- [Agent Memory](/docs/v1/agents/agent-memory)
+- [Request Context](/docs/v1/server-db/request-context)

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

@@ -0,0 +1,430 @@
+---
+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.
+
+You can use individual `Processor` objects or compose them into workflows using Mastra's workflow primitives. Workflows give you advanced control over processor execution order, parallel processing, and conditional logic.
+
+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
+
+### Per-step processing with processInputStep
+
+While `processInput` runs once at the start of agent execution, `processInputStep` runs at **each step** of the agentic loop (including tool call continuations). This enables per-step configuration changes like dynamic model switching or tool choice modifications.
+
+```typescript title="src/mastra/processors/step-processor.ts" showLineNumbers copy
+import type { Processor, ProcessInputStepArgs, ProcessInputStepResult } from "@mastra/core";
+
+export class DynamicModelProcessor implements Processor {
+  id = "dynamic-model";
+
+  async processInputStep({
+    stepNumber,
+    model,
+    toolChoice,
+    messageList,
+  }: ProcessInputStepArgs): Promise<ProcessInputStepResult> {
+    // Use a fast model for initial response
+    if (stepNumber === 0) {
+      return { model: "openai/gpt-4o-mini" };
+    }
+
+    // Disable tools after 5 steps to force completion
+    if (stepNumber > 5) {
+      return { toolChoice: "none" };
+    }
+
+    // No changes for other steps
+    return {};
+  }
+}
+```
+
+The `processInputStep` method receives:
+- `stepNumber`: Current step in the agentic loop (0-indexed)
+- `steps`: Results from previous steps
+- `messages`: Current messages snapshot (read-only)
+- `systemMessages`: Current system messages (read-only)
+- `messageList`: The full MessageList instance for mutations
+- `model`: Current model being used
+- `tools`: Current tools available for this step
+- `toolChoice`: Current tool choice setting
+- `activeTools`: Currently active tools
+- `providerOptions`: Provider-specific options
+- `modelSettings`: Model settings like temperature
+- `structuredOutput`: Structured output configuration
+
+The method can return any combination of:
+- `model`: Change the model for this step
+- `tools`: Replace or add tools (use spread to merge: `{ tools: { ...tools, newTool } }`)
+- `toolChoice`: Change tool selection behavior
+- `activeTools`: Filter which tools are available
+- `messages`: Replace messages (applied to messageList)
+- `systemMessages`: Replace all system messages
+- `providerOptions`: Modify provider options
+- `modelSettings`: Modify model settings
+- `structuredOutput`: Modify structured output configuration
+
+#### Using prepareStep callback
+
+For simpler per-step logic, you can use the `prepareStep` callback on `generate()` or `stream()` instead of creating a full processor:
+
+```typescript
+await agent.generate({
+  prompt: "Complex task",
+  prepareStep: async ({ stepNumber, model }) => {
+    if (stepNumber === 0) {
+      return { model: "openai/gpt-4o-mini" };
+    }
+    if (stepNumber > 5) {
+      return { toolChoice: "none" };
+    }
+  },
+});
+```
+
+### 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.
+
+## Using workflows as processors
+
+You can use Mastra workflows as processors to create complex processing pipelines with parallel execution, conditional branching, and error handling:
+
+```typescript title="src/mastra/processors/moderation-workflow.ts" showLineNumbers copy
+import { createWorkflow, createStep } from "@mastra/core/workflows";
+import { ProcessorStepSchema } from "@mastra/core/processors";
+import { Agent } from "@mastra/core/agent";
+
+// Create a workflow that runs multiple checks in parallel
+const moderationWorkflow = createWorkflow({
+  id: "moderation-pipeline",
+  inputSchema: ProcessorStepSchema,
+  outputSchema: ProcessorStepSchema,
+})
+  .then(createStep(new LengthValidator({ maxLength: 10000 })))
+  .parallel([
+    createStep(new PIIDetector({ strategy: "redact" })),
+    createStep(new ToxicityChecker({ threshold: 0.8 })),
+  ])
+  .commit();
+
+// Use the workflow as an input processor
+const agent = new Agent({
+  id: "moderated-agent",
+  name: "Moderated Agent",
+  model: "openai/gpt-4o",
+  inputProcessors: [moderationWorkflow],
+});
+```
+
+When an agent is registered with Mastra, processor workflows are automatically registered as workflows, allowing you to view and debug them in the playground.
+
+## Retry mechanism
+
+Processors can request that the LLM retry its response with feedback. This is useful for implementing quality checks, output validation, or iterative refinement:
+
+```typescript title="src/mastra/processors/quality-checker.ts" showLineNumbers copy
+import type { Processor } from "@mastra/core";
+
+export class QualityChecker implements Processor {
+  id = "quality-checker";
+
+  async processOutputStep({ text, abort, retryCount }) {
+    const qualityScore = await evaluateQuality(text);
+
+    if (qualityScore < 0.7 && retryCount < 3) {
+      // Request a retry with feedback for the LLM
+      abort("Response quality score too low. Please provide a more detailed answer.", {
+        retry: true,
+        metadata: { score: qualityScore },
+      });
+    }
+
+    return [];
+  }
+}
+
+const agent = new Agent({
+  id: "quality-agent",
+  name: "Quality Agent",
+  model: "openai/gpt-4o",
+  outputProcessors: [new QualityChecker()],
+  maxProcessorRetries: 3, // Maximum retry attempts (default: 3)
+});
+```
+
+The retry mechanism:
+- Only works in `processOutputStep` and `processInputStep` methods
+- Replays the step with the abort reason added as context for the LLM
+- Tracks retry count via the `retryCount` parameter
+- Respects `maxProcessorRetries` limit on the agent
+
+## Related documentation
+
+- [Guardrails](/docs/v1/agents/guardrails) - Security and validation processors
+- [Memory Processors](/docs/v1/memory/memory-processors) - Memory-specific processors and automatic integration
+- [Processor Interface](/reference/v1/processors/processor-interface) - Full API reference for processors