@mastra/mcp-docs-server 1.2.4-alpha.1 → 1.2.4-alpha.6

package/.docs/docs/agent-builder/access-control.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Access control
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/browser.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Browser
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/channels.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Channels
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/configuration.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Configuration
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/deploying.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Deploying
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/integrations.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Tool providers
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/memory.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Memory
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/model-policy.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Model policy
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent Builder overview
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/skill-registries.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Skill registries
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-builder/workspace.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Workspace
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.

package/.docs/docs/agent-controller/modes.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Modes
 
 Modes define the different behaviors an AgentController can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The AgentController keeps exactly one mode active at a time, carries the thread and state across switches, and handles the transition between them.

package/.docs/docs/agent-controller/overview.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # AgentController overview
 
 > **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
@@ -54,6 +56,7 @@ import { AgentController } from '@mastra/core/agent-controller'
 import { LibSQLStore } from '@mastra/libsql'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user plan and complete tasks.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agent-controller/session.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Session
 
 A [`Session`](https://mastra.ai/reference/agent-controller/session) holds the live state of an AgentController: who the session is for, which thread is active, the selected mode and model, permission grants, queued follow-ups, token usage, application state, and the display snapshot. You reach it through `agentController.session`.

package/.docs/docs/agent-controller/subagents.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Subagents
 
 Subagents let a parent agent delegate focused tasks to child agents with constrained tools and instructions. The AgentController auto-generates a `subagent` built-in tool that the parent model can call to spawn any configured subagent type. Reach for a subagent when a task needs a different toolset or instruction set than the parent agent, when you want to isolate a subtask's messages from the parent thread, or when the parent should delegate to a cheaper or faster model for specific work.
@@ -11,6 +13,7 @@ import { Agent } from '@mastra/core/agent'
 import { AgentController } from '@mastra/core/agent-controller'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Use subagents when a focused task needs a narrower toolset.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agent-controller/threads-and-state.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Threads and state
 
 Threads and state are how an AgentController conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation — its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation — values like model preferences, feature flags, or progress — that agents and your UI read and write as the conversation runs.
@@ -84,6 +86,7 @@ import { AgentController } from '@mastra/core/agent-controller'
 import { z } from 'zod'
 
 const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'Help the user manage a stateful session.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agent-controller/tool-approvals.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Tool approvals and permissions
 
 The AgentController provides a permission system that controls which tools require user approval before execution. You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools. This gives agents with access to destructive or sensitive tools — file writes, command execution, API calls — a human-in-the-loop checkpoint before those tools run.

package/.docs/docs/agents/a2a.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # A2A (Agent-to-Agent)
 
 Mastra supports the [Agent-to-Agent (A2A) protocol](https://a2a-protocol.org/latest/) for cross-platform multi-agent systems. Use A2A to expose Mastra agents as remote agents, consume remote A2A agents as Mastra subagents, or call A2A endpoints with the JavaScript client SDK.

package/.docs/docs/agents/acp.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent Client Protocol
 
 Mastra supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/overview/introduction) for running ACP-compatible coding agents from a Mastra agent. Use `@mastra/acp` to wrap a coding agent process as a Mastra tool or as a subagent.

package/.docs/docs/agents/adding-voice.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Voice
 
 Mastra agents can be enhanced with voice capabilities, allowing them to speak responses and listen to user input. You can configure an agent to use either a single voice provider or combine multiple providers for different operations.

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent approval
 
 Agents sometimes require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in workflows when calling tools that handle sensitive operations, like deleting resources or running long processes. With agent approval you can suspend a tool call before it executes so a human can approve or decline it, or let tools suspend themselves to request additional context from the user.

package/.docs/docs/agents/background-tasks.md

@@ -1,8 +1,10 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Background tasks
 
 **Added in:** `@mastra/core@1.29.0`
 
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/agents/agent) option the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
 
 ## When to use background tasks
 
@@ -166,7 +168,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/agents/agent) for the full API.
+> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 
@@ -372,7 +374,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 ## Related
 
-- [`Agent.stream()` reference](https://mastra.ai/reference/agents/agent)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Durable agents](https://mastra.ai/docs/agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)

package/.docs/docs/agents/channels.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Channels
 
 **Added in:** `@mastra/core@1.22.0`
@@ -135,6 +137,7 @@ import { createDiscordAdapter } from '@chat-adapter/discord'
 import { google } from '@ai-sdk/google'
 
 export const visionAgent = new Agent({
+  id: 'vision-agent',
   name: 'Vision Agent',
   instructions: 'You can see images, watch videos, and listen to audio.',
   model: google('gemini-3.1-flash-image-preview'),
@@ -175,10 +178,12 @@ A channel webhook returns a `200` response right away, then the agent runs in th
 On Vercel, pass `waitUntil` from `@vercel/functions`:
 
 ```typescript
+import { Agent } from '@mastra/core/agent'
+import { createSlackAdapter } from '@chat-adapter/slack'
 import { waitUntil } from '@vercel/functions'
 
 export const agent = new Agent({
-  // ...
+  id: 'agent',
   channels: {
     adapters: {
       slack: createSlackAdapter(),

package/.docs/docs/agents/code-mode.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Code mode
 
 **Added in:** `@mastra/core@1.38.0`
@@ -59,6 +61,7 @@ const { tool, instructions } = createCodeMode({
 })
 
 const agent = new Agent({
+  id: 'shop-assistant',
   name: 'shop-assistant',
   instructions: ['You are a helpful shopping assistant.', instructions],
   model: 'openai/gpt-5.5',
@@ -113,6 +116,7 @@ const inventory = createCodeMode({
 })
 
 const agent = new Agent({
+  id: 'ops-assistant',
   name: 'ops-assistant',
   instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
   model: 'openai/gpt-5.5',

package/.docs/docs/agents/durable-agents.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Durable agents
 
 **Added in:** `@mastra/core@1.45.0`
@@ -172,7 +174,7 @@ export const durableAgent = createDurableAgent({
 
 ## Streaming with background tasks
 
-Durable agents support the same [`untilIdle`](https://mastra.ai/reference/agents/durable-agent) option as regular agents. When `untilIdle` is set, `stream()` keeps the connection open across background-task continuations until the agent is idle:
+Durable agents support the same [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option as regular agents. When `untilIdle` is set, `stream()` keeps the connection open across background-task continuations until the agent is idle:
 
 ```typescript
 const { output, cleanup } = await durableAgent.stream('Research and summarize the topic', {

package/.docs/docs/agents/file-based-agents.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # File-based agents
 
 **Added in:** `@mastra/core@1.48.0`
@@ -223,7 +225,16 @@ export default agentConfig({
 
 Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
 
-Subagents are one level deep. A `subagents/` directory nested inside a subagent is ignored with a warning.
+Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory deeper than that is ignored with a warning.
+
+```text
+src/mastra/agents/
+  supervisor/            # depth 0
+    subagents/
+      researcher/        # depth 1
+        subagents/
+          summarizer/    # depth 2
+```
 
 Naming rules:
 
@@ -237,7 +248,7 @@ Naming rules:
 File-based and code-based agents coexist with deterministic rules:
 
 - **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
-- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
+- **A folder can hold a code agent:** If `config.ts` exports a configured `new Agent({ id: 'file-based-agent', ... })`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
 - **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
 - **Model:** A missing `model` fails the build and names the agent directory.
 - **Tools:** Tools from `tools/*.ts` merge with `config.tools`. On a key collision, `config.tools` wins and a warning is logged. If `config.tools` is a function, discovered tools are ignored with a warning.

package/.docs/docs/agents/goals.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Goals
 
 **Added in:** `@mastra/core@1.42.0`
@@ -26,6 +28,7 @@ Goals require a configured [storage](https://mastra.ai/docs/memory/storage) back
 import { Agent } from '@mastra/core/agent'
 
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',
@@ -66,6 +69,7 @@ By default the step uses a built-in LLM-as-judge scorer that returns `1` when th
 
 ```typescript
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',

package/.docs/docs/agents/guardrails.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Guardrails
 
 Mastra provides built-in processors that add security and safety controls to your agent. These processors detect, transform, or block harmful content before it reaches the language model or the user.

package/.docs/docs/agents/heartbeats.md

@@ -1,8 +1,10 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Heartbeats
 
 **Added in:** `@mastra/core@1.46.0`
 
-> **Beta:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
 
 A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 

package/.docs/docs/agents/networks.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent networks
 
 > **Deprecated — Use supervisor agents:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.

package/.docs/docs/agents/overview.md

@@ -1,7 +1,119 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agents overview
 
 Agents use LLMs and tools to solve open-ended tasks. They reason about goals, decide which tools to use, retain conversation memory, and iterate internally until the model emits a final answer or an optional stop condition is met. Agents produce structured responses you can render in your UI or process programmatically. Use agents directly or compose them into workflows or multi-agent systems.
 
+**For AI agents:** If you're tasked to build a Mastra project from scratch, follow the condensed instructions until the next heading. Adjust the example code for the agent & tool to your needs.
+
+Create a `package.json` file with `{ "type": "module" }`. Install the required dependencies: `npm install @mastra/core@latest zod@latest typescript@latest @types/node@latest mastra@latest`
+
+Create a tsconfig.json file:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+If you need to add a tool to the agent, create a new file and use `import { createTool } from "@mastra/core/tools"`. Plain object tool definitions silently fail to execute; tools MUST be defined via `createTool()` with `id`, `description`, `inputSchema` (zod), `execute()`. `execute()` receives two parameters: the validated input data based on inputSchema (first parameter) and an optional execution context object (second parameter) containing `requestContext`, `tracingContext`, `abortSignal`, and other execution metadata.
+
+Example:
+
+```ts
+// src/mastra/tools/weather-tool.ts
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'get-weather',
+  description: 'Get current weather for a location',
+  inputSchema: z.object({
+    location: z.string().describe('City name'),
+  }),
+  outputSchema: z.object({
+    output: z.string(),
+  }),
+  execute: async ({ location }) => {
+    return {
+      output: `The weather in ${location} is sunny`,
+    }
+  },
+})
+```
+
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). It's a bundled model gateway. Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+
+Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
+
+Example:
+
+```ts
+// src/mastra/agents/weather-agent.ts
+import { Agent } from '@mastra/core/agent'
+import { weatherTool } from '../tools/weather-tool.ts'
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: `
+      You are a helpful weather assistant that provides accurate weather information.
+
+      Your primary function is to help users get weather details for specific locations. When responding:
+      - Include relevant details like humidity, wind conditions, and precipitation
+      - Keep responses concise but informative
+
+      Use the weatherTool to fetch current weather data.
+`,
+  model: 'openai/gpt-5.5',
+  tools: { weatherTool },
+})
+```
+
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Short list of known model IDs are:
+
+- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
+- `google/gemini-2.5-flash`
+
+Go to <https://mastra.ai/models> for a full list of supported models.
+
+Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { weatherAgent } from './agents/weather-agent.ts'
+
+export const mastra = new Mastra({
+  agents: { weatherAgent },
+})
+```
+
+You're now able to run the agent directly. For this, import the Mastra instance and call the agent.generate() after retrieving the agent by its id. Node.js 22.18.0 and later are able to run TypeScript files directly. Make sure to add file extensions when importing local files. Example:
+
+```ts
+// run.mjs
+import { mastra } from './src/mastra/index.ts'
+
+const agent = mastra.getAgentById('weather-agent')
+const response = await agent.generate('Weather in SF')
+console.log(response.text)
+```
+
 ## When to use agents
 
 Use agents when the task is open-ended and the steps aren't known in advance. An agent decides which tools to call, how many times to loop, and when to stop. You provide the goal and constraints instead of defining each step. For predetermined, multi-step processes with explicit control flow, use [workflows](https://mastra.ai/docs/workflows/overview) instead.

package/.docs/docs/agents/processors.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # 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.
@@ -37,6 +39,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModerationProcessor } from '@mastra/core/processors'
 
 export const moderatedAgent = new Agent({
+  id: 'moderated-agent',
   name: 'moderated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5-mini',
@@ -92,6 +95,7 @@ import { Agent } from '@mastra/core/agent'
 import { PrefillErrorHandler, TokenLimiter, ModerationProcessor } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   model: 'openai/gpt-5',
   instructions: '...',
@@ -112,7 +116,7 @@ Each array also accepts a function that returns an array, so processors can be b
 
 ```typescript
 new Agent({
-  // ...
+  id: 'processors-agent',
   inputProcessors: ({ requestContext }) => {
     const limit = requestContext.get('tokenLimit') ?? 4000
     return [new TokenLimiter(limit)]
@@ -381,6 +385,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5.5',
   inputProcessors: [new TokenLimiter(127000)],
@@ -449,6 +454,7 @@ import { ResponseCache } from '@mastra/core/processors'
 const cache = new InMemoryServerCache()
 
 export const searchAgent = new Agent({
+  id: 'search-agent',
   name: 'Search Agent',
   instructions: 'You answer questions concisely.',
   model: 'openai/gpt-5',
@@ -494,7 +500,7 @@ Override explicitly when you need a different scope:
 
 ```typescript
 new Agent({
-  // ...
+  id: 'processors-agent',
   inputProcessors: [
     new ResponseCache({
       cache,
@@ -518,6 +524,7 @@ import { RedisCache } from '@mastra/redis'
 const cache = new RedisCache({ url: process.env.REDIS_URL })
 
 export const agent = new Agent({
+  id: 'cached-agent',
   name: 'Cached Agent',
   instructions: '...',
   model: 'openai/gpt-5',
@@ -617,6 +624,7 @@ import { EnsureFinalResponseProcessor } from '../processors/ensure-final-respons
 const MAX_STEPS = 5
 
 const agent = new Agent({
+  id: 'agent',
   instructions: `You are a helpful assistant.
 
 Some messages you receive may contain <system-reminder>...</system-reminder> tags.

package/.docs/docs/agents/sdk-agents.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # SDK agents
 
 SDK agents let you use other agent SDK frameworks inside Mastra. Use them to register SDK-backed agents in a Mastra project while the provider SDK keeps its own runtime, tools, permissions, and agent loop.

package/.docs/docs/agents/signal-providers.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Signal providers
 
 **Added in:** `@mastra/core@1.39.0`

package/.docs/docs/agents/signals.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Signals
 
 **Added in:** `@mastra/core@1.39.0`

package/.docs/docs/agents/skills.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Agent skills
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Structured output
 
 Structured output lets an agent return an object that matches the shape defined by a schema instead of returning text. The schema tells the model what fields to produce, and the model ensures the final result fits that shape.

package/.docs/docs/agents/supervisor-agents.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Supervisor agents
 
 **Added in:** `@mastra/core@1.8.0`
@@ -351,6 +353,7 @@ Each subagent should have a clear `description` that explains what it does, what
 
 ```typescript
 const supervisor = new Agent({
+  id: 'supervisor',
   instructions: `You coordinate research and writing tasks.
 
 Available resources:

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

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # Tools
 
 Agents use tools to call APIs, query databases, or run custom functions from your codebase. Tools give agents capabilities beyond language generation by providing structured access to data and performing clearly defined operations. You can also load tools from remote [MCP servers](https://mastra.ai/docs/mcp/overview) to expand an agent's capabilities.
@@ -242,6 +244,7 @@ Use `hooks` to run custom logic before and after every tool call an agent makes.
 import { Agent } from '@mastra/core/agent'
 
 export const supportAgent = new Agent({
+  id: 'support-agent',
   name: 'support-agent',
   instructions: 'Help users with their questions.',
   model: 'openai/gpt-5.5',
@@ -260,6 +263,7 @@ export const supportAgent = new Agent({
 
 ```typescript
 const guardedAgent = new Agent({
+  id: 'guarded-agent',
   name: 'guarded-agent',
   instructions: 'Run shell commands for the user.',
   model: 'openai/gpt-5.5',
@@ -392,6 +396,7 @@ Subagents and workflows follow the same pattern. They're converted to tools with
 
 ```typescript
 const orchestrator = new Agent({
+  id: 'orchestrator',
   agents: {
     weather: weatherAgent, // toolName: "agent-weather"
   },

package/.docs/docs/browser/agent-browser.md

@@ -1,3 +1,5 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
 # AgentBrowser
 
 The `@mastra/agent-browser` package provides browser automation using Playwright with accessibility-first element targeting. Elements are identified by refs from the page's accessibility tree, making interactions reliable across different page layouts.