@mastra/mcp-docs-server 0.13.31 → 0.13.32-alpha.1

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

@@ -3,46 +3,57 @@ title: "Agent Memory | Agents | Mastra Docs"
 description: Learn how to add memory to agents to store conversation history and maintain context across interactions.
 ---
 
-import { Callout } from "nextra/components";
+import { Steps } from "nextra/components";
 
-# Agent Memory
+## Agent memory
 
-Agents can use memory to store conversation history, recall relevant information, and maintain context across interactions. This enables more natural, stateful conversations throughout a user’s session.
+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.
 
-## When to use memory
-
-Use memory when an agent needs to retain information across multiple user interactions. This includes recalling user-specific details, facts, or tool calls and their results. Without memory, the agent handles each request in isolation, with no awareness of previous messages or responses.
-
-For more information about the different ways memory works in Mastra see the following pages.
+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.
 
-- [Working Memory](../memory/working-memory.mdx)
-- [Semantic Recall](../memory/semantic-recall.mdx)
+## When to use memory
 
-## Prerequisites
+Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
 
-Memory requires a storage provider to persist conversation history, including user messages and agent responses. You can use **shared storage** to define a single provider for all agents, or **dedicated storage** to configure separate providers for individual agents.
+## Setting up memory
 
-Install `@mastra/memory` and a storage provider.
+To enable memory in Mastra, install the `@mastra/memory` package along with a storage provider.
 
 ```bash npm2yarn copy
 npm install @mastra/memory@latest @mastra/libsql@latest
 ```
 
-### Storage providers
+## 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](../server-db/storage.mdx) documentation.
+
+## Configuring memory
+
+<Steps>
+
+### Agent memory
+
+Enable memory by creating a `Memory` instance and passing it to the agent’s `memory` option.
 
-Mastra supports multiple storage providers. Popular options include:
+```typescript {6-9} filename="src/mastra/agents/memory-agent.ts" showLineNumbers copy
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
 
-- [LibSQL](../../reference/storage/libsql.mdx)
-- [PostgreSQL](../../reference/storage/postgresql.mdx)
-- [Cloudflare D1](../../reference/storage/cloudflare-d1.mdx)
+export const memoryAgent = new Agent({
+  // ...
+  memory: new Memory({
+    options: {
+      lastMessages: 20
+    }
+  })
+});
+```
 
-<Callout type="warning">
-`LibSQLStore` works well for local development and when deploying to [Mastra Cloud](../mastra-cloud/overview.mdx), but may not be supported by some [serverless platforms](../deployment/serverless-platforms) or [cloud providers](../deployment/cloud-providers).
-</Callout>
+> See the [Memory Class](../../reference/memory/Memory.mdx) for a full list of configuration options.
 
-### Shared storage
+### Mastra storage
 
-Use shared storage for a simple, centralized setup across agents. Add the storage adapter to your main Mastra instance to make it available to all agents by default.
+Add a storage provider to your main Mastra instance to enable memory across all configured agents.
 
 ```typescript {6-8} filename="src/mastra/index.ts" showLineNumbers copy
 import { Mastra } from "@mastra/core/mastra";
@@ -56,9 +67,11 @@ export const mastra = new Mastra({
 });
 ```
 
-### Dedicated storage
+> See the [LibSQL Storage](../../reference/storage/libsql.mdx) for a full list of configuration options.
+
+</Steps>
 
-Use dedicated storage when agents need to keep data separate, use different providers, or tailor storage requirements for specific users. Add the storage adapter directly to the agent’s `memory` configuration option.
+Alternatively, add storage directly to an agent’s memory to keep data separate or use different providers per agent.
 
 ```typescript {7-10} filename="src/mastra/agents/memory-agent.ts" showLineNumbers copy
 import { Agent } from "@mastra/core/agent";
@@ -69,20 +82,20 @@ export const memoryAgent = new Agent({
   // ...
   memory: new Memory({
     storage: new LibSQLStore({
-      url: "file:../../memory-agent.db"
+      url: ":memory:"
     })
   })
 });
 ```
 
-## Memory in agent calls
+## Conversation history
 
-When calling `.generate()` or `.stream()`, include a `memory` object with both `resource` and `thread` to enable memory.
+Include a `memory` object with both `resource` and `thread` to track conversation 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 interactions.
+These fields tell the agent where to store and retrieve context, enabling persistent, thread-aware memory across a conversation.
 
 ```typescript {3-4}
 const response = await memoryAgent.generate("Remember my favorite color is blue.", {
@@ -93,7 +106,7 @@ const response = await memoryAgent.generate("Remember my favorite color is blue.
 });
 ```
 
-To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original interaction.
+To recall information stored in memory, call the agent with the same `resource` and `thread` values used in the original conversation.
 
 ```typescript {3-4}
 const response = await memoryAgent.generate("What's my favorite color?", {
@@ -104,9 +117,11 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 });
 ```
 
+To learn more about memory see the [Memory](../memory/overview.mdx) documentation.
+
 ## Using `RuntimeContext`
 
-Use `RuntimeContext` to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
+Use [RuntimeContext](../server-db/runtime-context.mdx) to access request-specific values. This lets you conditionally select different memory or storage configurations based on the context of the request.
 
 ```typescript filename="src/mastra/agents/memory-agent.ts" showLineNumbers
 export type UserTier = {
@@ -133,6 +148,8 @@ export const memoryAgent = new Agent({
 });
 ```
 
+> See [Runtime Context](../server-db/runtime-context.mdx) for more information.
+
 ## Related
 
 - [Working Memory](../memory/working-memory.mdx)

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

@@ -325,11 +325,18 @@ for await (const chunk of stream.fullStream) {
   }
 }
 ```
-
 In this case, the `tripwireReason` indicates that a credit card number was detected:
 
 ```text
 PII detected. Types: credit-card
 ```
 
+## Custom processors
+
+If the built-in processors don’t cover your needs, you can create your own by extending the `Processor` class.
+
+Available examples:
 
+- [Message Length Limiter](../../examples/processors/message-length-limiter)
+- [Response Length Limiter](../../examples/rocessors/response-length-limiter)
+- [Response Validator](../../examples/processors/response-validator)

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

@@ -1,166 +1,235 @@
 ---
-title: "Handling Complex LLM Operations | Networks | Mastra"
-description: "Networks in Mastra help you execute individual or multiple Mastra primitives in a non-deterministic way using a single API."
+title: "Agent Networks | Agents | Mastra Docs"
+description: Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 ---
 
-# Agent.network()
+# Agent Networks
 
-`Agent.network()` introduces a flexible, composable and non-deterministic way to orchestrate multiple specialized agents and workflows, enabling complex, reasoning and task completion.
+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.
 
-There are two main problem areas that this system is designed to solve:
+## When to use networks
 
-- Scenarios where a single agent is insufficient, and tasks require collaboration, routing, or sequential/parallel execution across multiple agents and workflows.
-- Scenarios where the task is not fully defined and is initiated with unstructured input. A network allows your Agent to figure out which primitive to call and turn unstructured input into a structured task.
+Use networks for complex tasks that require coordination across multiple primitives. Unlike workflows, which follow a predefined sequence, networks rely on LLM reasoning to interpret the request and decide what to run.
 
-## Differences from Workflows
+## Core principles
 
-- Workflows are linear or branched sequences of steps. This creates a deterministic flow of execution.
-- `Agent.network()` adds a layer of non-deterministic LLM-based orchestration, allowing dynamic, multi-agent collaboration and routing. This creates a non-deterministic flow of execution.
+Mastra agent networks operate using these principles:
 
-## Important details
+- Memory is required when using `.network()` and is used to store task history and determine when a task is complete.
+- Primitives are selected based on their descriptions. Clear, specific descriptions improve routing. For workflows and tools, the input schema helps determine the right inputs at runtime.
+- If multiple primitives have overlapping functionality, the agent favors the more specific one, using a combination of schema and descriptions to decide which to run.
 
-- Providing memory to the Agent when using `network()` is _not_ optional, as it is required to store the task history. Memory is the core primitive used for any decisions on which primitives to run, as well as determine task completion.
-- Any available primitives (agents, workflows) are used based on their descriptions. The better the description, the better the routing agent will be able to select the right primitive. For workflows, the input schema is also used to determine which inputs to use when calling the workflow. More descriptive naming yields better results.
-- When primitives with overlapping capabilities are available, the agent will use the most specific primitive. For example, if both an agent and a workflow can do research, it will use the input schema of the workflow to determine which primitive to select.
+## Creating an agent network
 
-## Turning an Agent into a 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.
 
-As an example, we have an Agent with 3 primitives at its disposal:
+```typescript {22-23,26,29} filename="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";
 
-- `agent1`: A general research agent that can do research on a given topic.
-- `agent2`: A general writing agent that can write a full report based on the researched material.
-- `workflow1`: A workflow that can research a given city and write a full report based on the researched material (using both agent1 and agent2).
+  import { researchAgent } from "./research-agent";
+  import { writingAgent } from "./writing-agent";
 
-We use the `network` method to create a task that requires multiple primitives. The Agent will, using memory, figure out which primitives to call and in which order, as well as when the task is complete.
+  import { cityWorkflow } from "../workflows/city-workflow";
+  import { weatherTool } from "../tools/weather-tool";
 
+  export const routingAgent = new Agent({
+    name: "routing-agent",
+    instructions: `
+      You are a network of writers and researchers.
+      The user will ask you to research a topic.
+      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"),
+    agents: {
+      researchAgent,
+      writingAgent
+    },
+    workflows: {
+      cityWorkflow
+    },
+    tools: {
+      weatherTool
+    },
+    memory: new Memory({
+      storage: new LibSQLStore({
+        url: "file:../mastra.db"
+      })
+    })
+  });
+  ```
 
-```typescript
-import { Agent } from '@mastra/core/agent';
-import { createStep, createWorkflow } from '@mastra/core/workflows';
-import { RuntimeContext } from '@mastra/core/runtime-context';
-import { Memory } from '@mastra/memory';
-import { openai } from '@ai-sdk/openai';
-import { LibSQLStore } from '@mastra/libsql';
-import { z } from 'zod';
+### Writing descriptions for network primitives
 
-const memory = new Memory({
-  storage: new LibSQLStore({
-    url: 'file:../mastra.db', // Or your database URL
-  }),
-});
+When configuring a Mastra agent network, each primitive (agent, workflow, or tool) needs a clear description to help the routing agent decide which to use. The routing agent uses each primitive's description and schema to determine what it does and how to use it. Clear descriptions and well-defined input and output schemas improve routing accuracy.
 
-const agentStep1 = createStep({
-  id: 'agent-step',
-  description: 'This step is used to do research and text synthesis.',
-  inputSchema: z.object({
-    city: z.string().describe('The city to research'),
-  }),
-  outputSchema: z.object({
-    text: z.string(),
-  }),
-  execute: async ({ inputData }) => {
-    const resp = await agent1.generate(inputData.city, {
-      structuredOutput: {
-        schema: z.object({
-          text: z.string(),
-        })
-      },
-    });
-
-    return { text: resp.object.text };
-  },
+#### Agent descriptions
+
+Each agent in a network should include a clear `description` that explains what the agent does.
+
+```typescript filename="src/mastra/agents/research-agent.ts" showLineNumbers
+export const researchAgent = new Agent({
+  name: "research-agent",
+  description: `This agent gathers concise research insights in bullet-point form.
+    It's designed to extract key facts without generating full
+    responses or narrative content.`,
+  // ...
 });
+```
+```typescript filename="src/mastra/agents/writing-agent.ts" showLineNumbers
+export const writingAgent = new Agent({
+  name: "writing-agent",
+  description: `This agent turns researched material into well-structured
+    written content. It produces full-paragraph reports with no bullet points,
+    suitable for use in articles, summaries, or blog posts.`,
+  // ...
+});
+```
 
-const agentStep2 = createStep({
-  id: 'agent-step-two',
-  description: 'This step is used to do research and text synthesis.',
+#### Workflow descriptions
+
+Workflows in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
+
+```typescript filename="src/mastra/workflows/city-workflow.ts" showLineNumbers
+export const cityWorkflow = createWorkflow({
+  id: "city-workflow",
+  description: `This workflow handles city-specific research tasks.
+    It first gathers factual information about the city, then synthesizes
+    that research into a full written report. Use it when the user input
+    includes a city to be researched.`,
   inputSchema: z.object({
-    text: z.string().describe('The city to research'),
+    city: z.string()
   }),
   outputSchema: z.object({
-    text: z.string(),
-  }),
-  execute: async ({ inputData }) => {
-    const resp = await agent2.generate(inputData.text, {
-      structuredOutput: {
-        schema: z.object({
-          text: z.string(),
-        })
-      },
-    });
-
-    return { text: resp.object.text };
-  },
-});
+    text: z.string()
+  })
+  //...
+})
+```
 
-const workflow1 = createWorkflow({
-  id: 'workflow1',
-  description:
-    'This workflow is perfect for researching a specific city. It should be used when you have a city in mind to research.',
-  steps: [],
+#### Tool descriptions
+
+Tools in a network should include a `description` to explain their purpose, along with `inputSchema` and `outputSchema` to describe the expected data.
+
+```typescript filename="src/mastra/tools/weather-tool.ts" showLineNumbers
+export const weatherTool = createTool({
+  id: "weather-tool",
+  description: ` Retrieves current weather information using the wttr.in API.
+    Accepts a city or location name as input and returns a short weather summary.
+    Use this tool whenever up-to-date weather data is requested.
+  `,
   inputSchema: z.object({
-    city: z.string(),
+    location: z.string()
   }),
   outputSchema: z.object({
-    text: z.string(),
+    weather: z.string()
   }),
-})
-  .then(agentStep1)
-  .then(agentStep2)
-  .commit();
-
-const agent1 = new Agent({
-  name: 'agent1',
-  instructions:
-    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
-  description:
-    'This agent is used to do research, but not create full responses. Answer in bullet points only and be concise.',
-  model: openai('gpt-4o'),
+  // ...
 });
+```
 
-const agent2 = new Agent({
-  name: 'agent2',
-  description:
-    'This agent is used to do text synthesis on researched material. Write a full report based on the researched material. Writes reports in full paragraphs. Should be used to synthesize text from different sources together as a final report.',
-  instructions:
-    'This agent is used to do text synthesis on researched material. Write a full report based on the researched material. Do not use bullet points. Write full paragraphs. There should not be a single bullet point in the final report.',
-  model: openai('gpt-4o'),
-});
+## Calling agent networks
 
-const routingAgent = new Agent({
-  id: 'test-network',
-  name: 'Test Network',
-  instructions:
-    'You are a network of writers and researchers. The user will ask you to research a topic. You always need to answer with a full report. Bullet points are NOT a full report. WRITE FULL PARAGRAPHS like this is a blog post or something similar. You should not rely on partial information.',
-  model: openai('gpt-4o'),
-  agents: {
-    agent1,
-    agent2,
-  },
-  workflows: {
-    workflow1,
-  },
-  memory: memory,
-});
+Call a Mastra agent network using `.network()` with a user message. The method returns a stream of events that you can iterate over to track execution progress and retrieve the final result.
+
+### Agent example
+
+In this example, the network interprets the message and would route the request to both the `researchAgent` and `writingAgent` to generate a complete response.
+
+```typescript showLineNumbers copy
+const result = await routingAgent.network("Tell me three cool ways to use Mastra");
+
+for await (const chunk of result) {
+  console.log(chunk.type);
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+#### Agent output
+
+The following `chunk.type` events are emitted during this request:
+
+```text
+routing-agent-start
+routing-agent-end
+agent-execution-start
+agent-execution-event-start
+agent-execution-event-step-start
+agent-execution-event-text-start
+agent-execution-event-text-delta
+agent-execution-event-text-end
+agent-execution-event-step-finish
+agent-execution-event-finish
+agent-execution-end
+network-execution-event-step-finish
+```
+
+## Workflow example
+
+In this example, the routing agent recognizes the city name in the message and runs the `cityWorkflow`. The workflow defines steps that call the `researchAgent` to gather facts, then the `writingAgent` to generate the final text.
+
+```typescript showLineNumbers copy
+const result = await routingAgent.network("Tell me some historical facts about London");
 
-const runtimeContext = new RuntimeContext();
+for await (const chunk of result) {
+  console.log(chunk.type);
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+#### Workflow output
+
+The following `chunk.type` events are emitted during this request:
 
-console.log(
-  // specifying the task, note that there is a mention here about using an agent for synthesis. This is because the routing agent can actually do some synthesis on results on its own, so this will force it to use agent2 instead
-  await routingAgent.network(
-    'What are the biggest cities in France? Give me 3. How are they like? Find cities, then do thorough research on each city, and give me a final full report synthesizing all that information. Make sure to use an agent for synthesis.',
-    { runtimeContext },
-  ),
-);
+```text
+routing-agent-end
+workflow-execution-start
+workflow-execution-event-workflow-start
+workflow-execution-event-workflow-step-start
+workflow-execution-event-workflow-step-result
+workflow-execution-event-workflow-finish
+workflow-execution-end
+routing-agent-start
+network-execution-event-step-finish
 ```
 
-For the given task (research 3 biggest cities in France and write a full report), the AgentNetwork will call the following primitives:
+### Tool example
+
+In this example, the routing agent skips the `researchAgent`, `writingAgent`, and `cityWorkflow`, and calls the `weatherTool` directly to complete the task.
+
+```typescript showLineNumbers copy
+const result = await routingAgent.network("What's the weather in London?");
+
+for await (const chunk of result) {
+  console.log(chunk.type);
+  if (chunk.type === "network-execution-event-step-finish") {
+    console.log(chunk.payload.result);
+  }
+}
+```
+
+#### Tool output
+
+The following `chunk.type` events are emitted during this request:
+
+```text
+routing-agent-start
+routing-agent-end
+tool-execution-start
+tool-execution-end
+network-execution-event-step-finish
+```
 
-1. `agent1` to find the 3 biggest cities in France.
-2. `workflow1` to research each city one by one. The workflow uses `memory` to figure out which cities have already been researched and makes sure it has researched all of them before proceeding.
-3. `agent2` to synthesize the final report.
+## Related
 
-### How It Works
+- [Agent Memory](./agent-memory.mdx)
+- [Workflows Overview](../workflows/overview.mdx)
+- [Runtime Context](../server-db/runtime-context.mdx)
 
-- The underlying engine is a Mastra workflow that wraps the single call `generate` workflow.
-- The workflow will repeatedly call the network execution workflow with a `dountil` structure, until the routing model determines the task is complete. This check is used as the `dountil` condition.

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

@@ -13,12 +13,12 @@ Agents use LLMs and tools to solve open-ended tasks. They reason about goals, de
 
 > **📹 Watch**:  → An introduction to agents, and how they compare to workflows [YouTube (7 minutes)](https://youtu.be/0jg2g3sNvgw)
 
-## Getting started
+## Setting up agents
 
 <Tabs items={["Mastra model router", "Vercel AI SDK"]}>
   <Tabs.Tab>
     <Steps>
-### Install dependencies
+### Install dependencies [#install-dependencies-mastra-router]
 
 Add the Mastra core package to your project:
 
@@ -26,7 +26,7 @@ Add the Mastra core package to your project:
 npm install @mastra/core
 ```
 
-### Set your API key
+### Set your API key [#set-api-key-mastra-router]
 
 Mastra's model router auto-detects environment variables for your chosen provider. For OpenAI, set `OPENAI_API_KEY`:
 
@@ -36,7 +36,7 @@ OPENAI_API_KEY=<your-api-key>
 
 > Mastra supports more than 600 models. Choose from the full list [here](/models).
 
-### Create an agent
+### Creating an agent [#creating-an-agent-mastra-router]
 
 Create an agent by instantiating the `Agent` class with system `instructions` and a `model`:
 
@@ -53,7 +53,8 @@ export const testAgent = new Agent({
   </Tabs.Tab>
   <Tabs.Tab>
     <Steps>
-### Install dependencies
+
+### Install dependencies [#install-dependencies-ai-sdk]
 
 Include the Mastra core package alongside the Vercel AI SDK provider you want to use:
 
@@ -61,7 +62,7 @@ Include the Mastra core package alongside the Vercel AI SDK provider you want to
 npm install @mastra/core @ai-sdk/openai
 ```
 
-### Set your API key
+### Set your API key [#set-api-key-ai-sdk]
 
 Set the corresponding environment variable for your provider. For OpenAI via the AI SDK:
 
@@ -71,7 +72,7 @@ OPENAI_API_KEY=<your-api-key>
 
 > See the [AI SDK Providers](https://ai-sdk.dev/providers/ai-sdk-providers) in the Vercel AI SDK docs for additional configuration options.
 
-### Create an agent
+### Creating an agent [#creating-an-agent-ai-sdk]
 
 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:
 
@@ -125,8 +126,8 @@ instructions: {
   content:
     "You are an expert code reviewer. Analyze code for bugs, performance issues, and best practices.",
   providerOptions: {
-    openai: { reasoning_effort: "high" },        // OpenAI's reasoning models
-    anthropic: { cache_control: { type: "ephemeral" } }  // Anthropic's prompt caching
+    openai: { reasoningEffort: "high" },        // OpenAI's reasoning models
+    anthropic: { cacheControl: { type: "ephemeral" } }  // Anthropic's prompt caching
   }
 }
 ```