@mastra/mcp-docs-server 1.1.41 → 1.1.42-alpha.11

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

@@ -0,0 +1,97 @@
+# 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.
+
+The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
+
+- [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
+- [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
+- [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
+- [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
+- [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
+- [**Skill registries**](https://mastra.ai/docs/agent-builder/skill-registries): Browse and install community skills from opt-in registries.
+- [**Deploying**](https://mastra.ai/docs/agent-builder/deploying): Swap local primitives for cloud-backed storage, filesystems, and sandboxes.
+
+For building agents entirely in code, see the [Agents overview](https://mastra.ai/docs/agents/overview). For editing code-defined agents through Studio, see the [Editor overview](https://mastra.ai/docs/editor/overview).
+
+## Get started
+
+Install `@mastra/editor` alongside a storage adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/editor @mastra/libsql
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/editor @mastra/libsql
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/editor @mastra/libsql
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/editor @mastra/libsql
+```
+
+Wire the Agent Builder onto a `Mastra` instance:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { MastraEditor } from '@mastra/editor'
+import { createBuilderAgent } from '@mastra/editor/ee'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  agents: { builderAgent: createBuilderAgent() },
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          memory: { observationalMemory: true },
+        },
+      },
+    },
+  }),
+})
+```
+
+Start the dev server:
+
+```bash
+npx mastra dev
+```
+
+The Agent Builder is mounted at `http://localhost:4111/agent-builder`.
+
+## Prerequisites
+
+The Agent Builder requires:
+
+- **Storage**: An `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
+- **The Builder agent**: Register a Builder agent created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
+- **`OPENAI_API_KEY`**: The Builder agent created by `createBuilderAgent()` runs on an OpenAI model, so an `OPENAI_API_KEY` environment variable is required.
+
+## Disabling the Builder
+
+Set `enabled: false` to keep the config in place but turn the surface off:
+
+```typescript
+new MastraEditor({
+  builder: {
+    enabled: false,
+  },
+})
+```
+
+Omitting the `builder` field has the same effect.

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

@@ -0,0 +1,31 @@
+# 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.
+
+Registries let the Agent Builder browse and install community skills directly from the UI. All registries are opt-in. When no registry is enabled, the Builder hides registry browse UI entirely.
+
+## Quickstart
+
+Enable the [skills.sh](https://skills.sh) registry:
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent.
+
+> **Note:** See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
+
+## Related
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire registries alongside the rest of the Builder config.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — every field on `builder`.

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

@@ -0,0 +1,60 @@
+# 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.
+
+A [workspace](https://mastra.ai/docs/workspace/overview) gives agents filesystem access, command execution, and skill loading. The Agent Builder pins a default workspace onto every new agent through `builder.configuration.agent.workspace`. End users can still override the workspace per agent through the Builder UI.
+
+## Quickstart
+
+Pin an inline workspace snapshot as the Builder default:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          workspace: {
+            type: 'inline',
+            config: {
+              name: 'project-workspace',
+              filesystem: {
+                provider: 'local',
+                config: { basePath: './workspace' },
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+})
+```
+
+The Builder derives a deterministic id from the inline config and persists the snapshot, so identical inline configs are deduplicated across agents.
+
+## Workspace references
+
+`configuration.agent.workspace` accepts a `StorageWorkspaceRef`:
+
+- **`{ type: 'inline', config }`** — embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
+- **`{ type: 'id', workspaceId }`** — references a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
+
+See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
+
+## Filesystem and sandbox
+
+A workspace combines a `filesystem` (file tools) and an optional `sandbox` (command execution). For local development, point both at the same directory so files written through the filesystem are immediately visible to commands in the sandbox.
+
+For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed providers (e.g., S3, E2B). See [Deploying](https://mastra.ai/docs/agent-builder/deploying) for the cloud-swap pattern.
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview) — the underlying workspace model.
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox) — the building blocks.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `workspace` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `workspace` alongside the rest of the Builder config.

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

@@ -81,7 +81,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'Answer user questions and delegate weather questions when needed.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     remoteWeatherAgent,
   },

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

@@ -84,7 +84,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Delegate code editing tasks to the code-agent subagent.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     codeAgent,
   },
@@ -113,7 +113,7 @@ export const codeSupervisor = new Agent({
   id: 'code-supervisor',
   name: 'Code Supervisor',
   instructions: 'Use the code-agent tool when a task requires repository inspection or code edits.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     codeAgentTool,
   },
@@ -178,14 +178,14 @@ export const codeAgent = new AcpAgent({
   description: 'An ACP-compatible coding agent',
   command: 'claude',
   args: ['--acp'],
-  model: '__AI_SDK_ANTHROPIC_MODEL_SONNET__',
+  model: 'claude-sonnet-4-6',
 })
 ```
 
 You can also change the model at runtime with `setModel()`:
 
 ```typescript
-await codeAgent.setModel('__AI_SDK_ANTHROPIC_MODEL_SONNET__')
+await codeAgent.setModel('claude-sonnet-4-6')
 ```
 
 If the ACP agent advertises available models and your model ID doesn't match any of them, Mastra throws an error listing the valid options:

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

@@ -20,7 +20,7 @@ export const agent = new Agent({
   id: 'voice-agent',
   name: 'Voice Agent',
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   voice,
 })
 
@@ -109,7 +109,7 @@ export const agent = new Agent({
   id: 'speech-to-speech-agent',
   name: 'Speech-to-Speech Agent',
   instructions: `You are a helpful assistant with speech-to-speech capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     // Tools configured on Agent are passed to voice provider
     search,
@@ -132,6 +132,37 @@ agent.voice.send(microphoneStream)
 agent.voice.close()
 ```
 
+### Per-session voice for concurrent sessions
+
+A static `voice` instance is shared across every request. For one-shot text-to-speech this is fine, but realtime and speech-to-speech providers store one WebSocket, one set of tools, and one request context per instance. If you deploy a single agent that handles several live sessions at once, a shared instance lets one session overwrite another session's tools, instructions, and request context.
+
+To give each session its own voice, provide `voice` as a resolver. Mastra runs the resolver on every `getVoice()` call and returns a fresh, session-owned instance:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
+
+export const agent = new Agent({
+  id: 'support-line',
+  name: 'Support Line',
+  instructions: ({ requestContext }) => `Help user ${requestContext.get('user')}.`,
+  model: 'openai/gpt-5.5',
+  voice: ({ requestContext }) => new OpenAIRealtimeVoice({ apiKey: requestContext.get('apiKey') }),
+})
+
+// Each concurrent session resolves its own voice instance
+const voice = await agent.getVoice({ requestContext })
+await voice.connect()
+```
+
+When you use a resolver:
+
+- Each call to `getVoice()` returns a new instance, so concurrent sessions never share state.
+- Mastra does not add tools or instructions to a resolver instance. Configure those inside the resolver or on the provider.
+- You own the lifecycle of the returned instance, so call `disconnect()` or `close()` when the session ends.
+
+The `agent.voice` getter has no request context, so it throws when `voice` is a resolver. Use `agent.getVoice({ requestContext })` instead.
+
 ### Event System
 
 The realtime voice provider emits several events you can listen for:
@@ -209,7 +240,7 @@ export const convertToText = async (input: string | NodeJS.ReadableStream): Prom
 export const hybridVoiceAgent = new Agent({
   id: 'hybrid-voice-agent',
   name: 'Hybrid Voice Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   instructions: 'You can speak and listen using different providers.',
   voice: new CompositeVoice({
     input: new OpenAIVoice(),
@@ -221,7 +252,7 @@ export const unifiedVoiceAgent = new Agent({
   id: 'unified-voice-agent',
   name: 'Unified Voice Agent',
   instructions: 'You are an agent with both STT and TTS capabilities.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   voice: new OpenAIVoice(),
 })
 
@@ -263,7 +294,7 @@ export const agent = new Agent({
   id: 'voice-agent',
   name: 'Voice Agent',
   instructions: `You are a helpful assistant with both STT and TTS capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 
   // Create a composite voice using OpenAI for listening and PlayAI for speaking
   voice: new CompositeVoice({
@@ -288,7 +319,7 @@ export const agent = new Agent({
   id: 'aisdk-voice-agent',
   name: 'AI SDK Voice Agent',
   instructions: `You are a helpful assistant with voice capabilities.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 
   // Pass AI SDK models directly to CompositeVoice
   voice: new CompositeVoice({

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

@@ -86,6 +86,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Conditional approval with a function
+
+Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval dynamically — for example, only for tools whose name matches a pattern:
+
+```typescript
+const stream = await agent.stream('Clean up old records', {
+  requireToolApproval: ({ toolName }) => /^delete_/.test(toolName),
+})
+```
+
+A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above does not override it. If the function throws, the call requires approval (fail-safe).
+
+> **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
+
 ### Runtime suspension with `suspend()`
 
 A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.
@@ -398,7 +412,7 @@ const supervisorAgent = new Agent({
   name: 'Supervisor Agent',
   instructions: `You coordinate data retrieval tasks.
     Delegate to data-agent for user lookups.`,
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { dataAgent },
   memory: new Memory(),
 })

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

@@ -80,7 +80,7 @@ import { Agent } from '@mastra/core/agent'
 export const researcher = new Agent({
   id: 'researcher',
   instructions: 'You research topics and answer questions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: { researchTool, summarizeTool },
   backgroundTasks: {
     tools: {
@@ -175,7 +175,7 @@ import { Agent } from '@mastra/core/agent'
 const supervisor = new Agent({
   id: 'supervisor',
   instructions: 'Coordinate research and writing using the available agents.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   agents: { researchAgent, writingAgent },
   backgroundTasks: {
     tools: {

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

@@ -23,7 +23,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support Agent',
   instructions: 'You are a helpful support assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   channels: {
     adapters: {
       slack: createSlackAdapter(),
@@ -88,6 +88,8 @@ When a user mentions the agent mid-conversation in a channel thread, the agent m
 
 Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-DM threads.
 
+Mastra also adds a short system message telling the agent which channel and platform the request came from (DM vs public channel, platform name, bot display name). Set `threadContext: { addSystemMessage: false }` to skip it.
+
 ## Tool approval
 
 Tools with `requireApproval: true` render as interactive cards with Approve and Deny buttons:

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

@@ -0,0 +1,163 @@
+# Code mode
+
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
+Code mode gives an agent a single tool that runs a short TypeScript program in a sandbox. Instead of calling tools one at a time, the model writes a program that orchestrates your existing tools as `external_*` functions, batching calls with `Promise.all`, aggregating with `reduce`, branching, and doing math in a real runtime, then returns a single result.
+
+`createCodeMode` returns this tool with the default id `execute_typescript`. The id is configurable, so an agent can have several code mode tools at once, each scoped to a different set of tools (see [Scoping tools across multiple code tools](#scoping-tools-across-multiple-code-tools)).
+
+## When to use code mode
+
+Use code mode when a task touches several tools at once or needs real computation between calls:
+
+- Fewer round-trips: a task that touches several tools runs in one tool call instead of one model turn per tool.
+- Correct math: sums, averages, and other arithmetic run as JavaScript, not as token prediction.
+- Planning up front: filtering, aggregation, and branching happen inside the program rather than across separate turns.
+
+## How it works
+
+Your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, so dangerous tools, approvals, and validation behave exactly as they do for normal tool calls.
+
+The program runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the program as a host `node` process with host privileges, so only use it for trusted or local development.
+
+## Quickstart
+
+`createCodeMode` returns the tool plus generated instructions. With no `id`, the tool is named `execute_typescript`. Add both to your agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createCodeMode, createTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+import { z } from 'zod'
+
+const getTopProducts = createTool({
+  id: 'getTopProducts',
+  description: 'Get top selling products',
+  inputSchema: z.object({ limit: z.number() }),
+  outputSchema: z.object({
+    products: z.array(z.object({ id: z.string(), name: z.string(), totalSales: z.number() })),
+  }),
+  execute: async ({ limit }) => fetchTopProducts(limit),
+})
+
+const getProductRatings = createTool({
+  id: 'getProductRatings',
+  description: 'Get ratings for a product',
+  inputSchema: z.object({ productId: z.string() }),
+  outputSchema: z.object({ ratings: z.array(z.object({ score: z.number() })) }),
+  execute: async ({ productId }) => fetchRatings(productId),
+})
+
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(), // required; runs on the host — see "How it works"
+})
+
+const agent = new Agent({
+  name: 'shop-assistant',
+  instructions: ['You are a helpful shopping assistant.', instructions],
+  model: 'openai/gpt-5.5',
+  tools: { execute_typescript: tool },
+})
+```
+
+Asked "What are the top 5 products and the average rating for each?", the model emits one `execute_typescript` call instead of many separate tool calls:
+
+```typescript
+const top = await external_getTopProducts({ limit: 5 })
+const ratings = await Promise.all(
+  top.products.map(p => external_getProductRatings({ productId: p.id })),
+)
+return top.products.map((product, i) => {
+  const scores = ratings[i].ratings.map(r => r.score)
+  const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length
+  return {
+    name: product.name,
+    sales: product.totalSales,
+    averageRating: Math.round(avg * 100) / 100,
+  }
+})
+```
+
+All five rating lookups run in parallel, the averages are computed in JavaScript, and the agent receives one structured result.
+
+## Configuration
+
+```typescript
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings }, // exposed as external_*; only these can be called
+  sandbox, // required WorkspaceSandbox, unless the agent runs in a workspace that provides one
+  timeout: 30_000, // optional execution timeout in ms (default 30000)
+  id: 'execute_typescript', // optional tool id (default "execute_typescript")
+})
+```
+
+| Option    | Type               | Description                                                                                                                                   |
+| --------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tools`   | `ToolsInput`       | Tools exposed to the program as `external_<id>`. Only these may be called.                                                                    |
+| `sandbox` | `WorkspaceSandbox` | Sandbox to run the program in. Required unless the agent runs in a workspace that provides one. Pass `new LocalSandbox()` to run on the host. |
+| `timeout` | `number`           | Execution timeout in milliseconds. Default `30000`.                                                                                           |
+| `id`      | `string`           | The generated tool's id. Default `execute_typescript`.                                                                                        |
+
+## Result
+
+The tool returns a `CodeModeToolResult`:
+
+```typescript
+type CodeModeToolResult = {
+  success: boolean
+  result?: unknown // value returned by the program
+  logs?: string[] // captured console output
+  error?: { message: string; name?: string; line?: number }
+}
+```
+
+## Inspecting the instructions
+
+The generated `instructions` contain the usage contract and a typed `external_*` declaration for each tool, derived from your tool schemas. Print them to see exactly what the model receives:
+
+```typescript
+import { createCodeModeInstructions } from '@mastra/core/tools'
+
+console.log(createCodeModeInstructions({ tools: { getTopProducts, getProductRatings } }))
+```
+
+## Scoping tools across multiple code tools
+
+`createCodeMode` captures its own allow-list. Call it more than once to give an agent several code tools, each scoped to a different subset of tools. A program can only call the `external_*` functions for the tools passed to its own `createCodeMode` call, so the subsets stay isolated.
+
+Give each tool a distinct `id` so their ids do not collide, and add each tool's instructions to the agent:
+
+```typescript
+const sales = createCodeMode({
+  id: 'sales_code',
+  tools: { listRecentOrders, getCustomer },
+  sandbox,
+})
+
+const inventory = createCodeMode({
+  id: 'inventory_code',
+  tools: { listProducts, getSupplier },
+  sandbox,
+})
+
+const agent = new Agent({
+  name: 'ops-assistant',
+  instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
+  model: 'openai/gpt-5.5',
+  tools: { sales_code: sales.tool, inventory_code: inventory.tool },
+})
+```
+
+A program run by `sales_code` cannot call an inventory tool, and the reverse holds too. Use this for least-privilege scoping and to keep each tool's prompt surface small.
+
+## Tips
+
+- Keep tools focused, so each does one thing well and the model composes them in code.
+- Code mode helps most when calls can be parallelized with `Promise.all`.
+- Use `console.log` for debugging. Logs are captured in the result.
+
+## Related
+
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

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

@@ -246,7 +246,7 @@ costGuard.onViolation = ({ processorId, message, detail }) => {
 
 // Log moderation violations
 const moderation = new ModerationProcessor({
-  model: '__OPENAI_MODEL_NANO__',
+  model: 'openai/gpt-5-nano',
   strategy: 'block',
 })
 
@@ -360,7 +360,7 @@ See [workflows as processors](https://mastra.ai/docs/agents/processors) for more
 Guardrail processors don't need your primary model. Use a small, fast model for classification tasks:
 
 ```typescript
-const GUARDRAIL_MODEL = '__OPENAI_MODEL_NANO__'
+const GUARDRAIL_MODEL = 'openai/gpt-5-nano'
 
 new ModerationProcessor({ model: GUARDRAIL_MODEL })
 new PIIDetector({ model: GUARDRAIL_MODEL })

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

@@ -27,7 +27,7 @@ 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-5.4',
+  model: 'openai/gpt-5.5',
   agents: {
     researchAgent,
     writingAgent,

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

@@ -19,7 +19,7 @@ export const testAgent = new Agent({
   id: 'test-agent',
   name: 'Test Agent',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 ```
 

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

@@ -382,7 +382,7 @@ import { TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
   name: 'my-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [new TokenLimiter(127000)],
 })
 ```
@@ -647,7 +647,7 @@ const moderationWorkflow = createWorkflow({
 const agent = new Agent({
   id: 'moderated-agent',
   name: 'Moderated Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [moderationWorkflow],
 })
 ```
@@ -686,7 +686,7 @@ export class QualityChecker implements Processor {
 const agent = new Agent({
   id: 'quality-agent',
   name: 'Quality Agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   outputProcessors: [new QualityChecker()],
   maxProcessorRetries: 3, // Maximum retry attempts. If unset, retries are disabled (unless errorProcessors are configured, in which case it defaults to 10).
 })

package/.docs/docs/agents/response-caching.md

@@ -1,6 +1,6 @@
 # Response Caching
 
-> **Experimental:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.