@mastra/mcp-docs-server 0.0.0-studio-deploy-20260404182525 → 0.0.0-studio-cli-20260504022012

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

@@ -167,6 +167,22 @@ const stream = await supervisor.stream('Research AI trends', {
 
 The callback receives `messages` (the full conversation history), `primitiveId` (the subagent ID), and `prompt` (the delegation prompt). Return the filtered array of messages.
 
+## Subagent result context
+
+When a subagent completes, the supervisor model receives the subagent's text response in later iterations. Nested tool calls and subagent metadata, such as thread and resource IDs, are not added to the supervisor model context.
+
+Application code and UI integrations can still inspect the raw delegation result, including `subAgentToolResults`, from the tool result payload. This keeps debugging and display data available without sending nested tool arguments or outputs back into the supervisor's next model call.
+
+Set `includeSubAgentToolResultsInModelContext` to include the full subagent result, including nested tool results and subagent metadata, in the supervisor model context.
+
+```typescript
+await supervisor.generate('Research AI trends', {
+  delegation: {
+    includeSubAgentToolResultsInModelContext: true,
+  },
+})
+```
+
 ## Iteration monitoring
 
 `onIterationComplete` is called after each iteration of the supervisor loop. Use it to log progress, inject feedback, or stop execution early.
@@ -300,10 +316,59 @@ Success criteria:
 })
 ```
 
+## Running subagents in the background
+
+Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
+
+Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the supervisor:
+
+```typescript
+const supervisor = new Agent({
+  id: 'supervisor',
+  instructions: 'Coordinate research and writing using the available agents.',
+  model: 'openai/gpt-5.4',
+  agents: { researchAgent, writingAgent },
+  backgroundTasks: {
+    tools: {
+      researchAgent: { enabled: true, timeoutMs: 900_000 },
+      writingAgent: { enabled: true, timeoutMs: 900_000 },
+    },
+  },
+})
+
+const stream = await supervisor.streamUntilIdle('Research AI in education and write an article', {
+  memory: { thread: 't1', resource: 'u1' },
+})
+```
+
+Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the supervisor has had a chance to respond to their results.
+
+If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/agents/background-tasks) for details.
+
+## Subagent versioning
+
+When using the [editor](https://mastra.ai/docs/editor/overview), you can control which stored version of each subagent the supervisor uses at runtime. Set version overrides on the Mastra instance or per invocation:
+
+```typescript
+const result = await supervisor.generate('Research and write about AI safety', {
+  versions: {
+    agents: {
+      'research-agent': { status: 'published' },
+      'writing-agent': { versionId: 'draft-456' },
+    },
+  },
+})
+```
+
+Version overrides propagate automatically through delegation. See [Subagent versioning](https://mastra.ai/docs/editor/overview) for details on resolution order and server API usage.
+
 ## Related
 
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Subagent versioning](https://mastra.ai/docs/editor/overview)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.streamUntilIdle() reference](https://mastra.ai/reference/streaming/agents/streamUntilIdle)
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
 - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)

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

@@ -57,6 +57,78 @@ export const weatherAgent = new Agent({
 })
 ```
 
+## Define schemas
+
+You can define the tool's `inputSchema` and `outputSchema` with any library that supports [Standard JSON Schema](https://standardschema.dev/json-schema). This includes libraries like [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), and [ArkType](https://arktype.io/).
+
+**Zod**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+  outputSchema: z.object({
+    weather: z.string(),
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**Valibot**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import * as v from 'valibot'
+import { toStandardJsonSchema } from '@valibot/to-json-schema'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: toStandardJsonSchema(
+    v.object({
+      location: v.string(),
+    }),
+  ),
+  outputSchema: toStandardJsonSchema(
+    v.object({
+      weather: v.string(),
+    }),
+  ),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
+**ArkType**:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { type } from 'arktype'
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  description: 'Fetches weather for a location',
+  inputSchema: type({
+    location: 'string',
+  }),
+  outputSchema: type({
+    weather: 'string',
+  }),
+  execute: async inputData => {
+    // Fetch weather data
+  },
+})
+```
+
 ## Multiple tools
 
 An agent can use multiple tools to handle more complex tasks by delegating specific parts to individual tools. The agent decides which tools to use based on the user's message, the agent's instructions, and the tool descriptions and schemas.
@@ -218,6 +290,7 @@ Note that for subagents, you'll see two different identifiers in stream response
 
 - [`createTool` reference](https://mastra.ai/reference/tools/create-tool)
 - [`Agent.generate()` reference](https://mastra.ai/reference/agents/generate): Runtime options for tool selection, steps, and callbacks
+- [Background tasks](https://mastra.ai/docs/agents/background-tasks): Run long-running tools without blocking the agent loop
 - [MCP overview](https://mastra.ai/docs/mcp/overview)
 - [Dynamic tool search](https://mastra.ai/reference/processors/tool-search-processor): Load tools on demand for agents with large tool libraries
 - [Tools with structured output](https://mastra.ai/docs/agents/structured-output): Model compatibility when combining tools and structured output

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

@@ -0,0 +1,78 @@
+# 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.
+
+## When to use AgentBrowser
+
+Use AgentBrowser when you need:
+
+- Reliable element targeting through accessibility refs
+- Fine-grained control over browser actions
+- Playwright's robust automation capabilities
+- Support for keyboard shortcuts and complex interactions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/agent-browser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agent-browser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agent-browser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agent-browser
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  headless: false,
+})
+
+export const browserAgent = new Agent({
+  id: 'browser-agent',
+  name: 'Browser Agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions: `You are a web automation assistant.
+
+When interacting with pages:
+1. Use browser_snapshot to get the current page state and element refs
+2. Use the refs (like @e1, @e2) to target elements for clicks and typing
+3. After actions, take another snapshot to verify the result`,
+})
+```
+
+> **Note:** For local launches (the default), AgentBrowser requires a Chromium binary installed via Playwright. This is normally downloaded automatically when you install `@mastra/agent-browser`. If launching the browser fails with `"browser executable is missing"`, run `npx playwright install chromium`. If you connect to a remote browser using the [`cdpUrl`](https://mastra.ai/reference/browser/agent-browser) option, no local Chromium is needed.
+
+## Element refs
+
+AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.
+
+> **Note:** See [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser) for all configuration options and tool details.
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [AgentBrowser reference](https://mastra.ai/reference/browser/agent-browser)

package/.docs/docs/browser/browser-viewer.md

@@ -0,0 +1,144 @@
+# BrowserViewer
+
+The `@mastra/browser-viewer` package provides browser automation for CLI-based tools like [agent-browser](https://www.npmjs.com/package/agent-browser), [browser-use](https://pypi.org/project/browser-use/), and [browse](https://www.npmjs.com/package/@browserbasehq/browse-cli). BrowserViewer launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through [workspace tools](https://mastra.ai/docs/workspace/overview).
+
+## When to use BrowserViewer
+
+Use BrowserViewer when your agent drives a browser through a CLI tool rather than an SDK. BrowserViewer handles:
+
+- Launching and managing Chrome for CLI tools to connect to
+- Automatic CDP URL injection into `workspace_execute_command` calls
+- Live screencast streaming to Studio
+- Thread-scoped browser isolation
+
+For SDK-based browser automation, use [AgentBrowser](https://mastra.ai/docs/browser/agent-browser) or [Stagehand](https://mastra.ai/docs/browser/stagehand) instead.
+
+## Quickstart
+
+Install `@mastra/browser-viewer` and the CLI tool your agent will use. BrowserViewer manages Chrome, but the CLI tool itself must be installed separately.
+
+**npm**:
+
+```bash
+npm install @mastra/browser-viewer
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/browser-viewer
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/browser-viewer
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/browser-viewer
+```
+
+Install the CLI tool in your workspace environment. This example uses `browser-use`:
+
+```bash
+pip install browser-use
+```
+
+Install the corresponding [skill](https://mastra.ai/docs/workspace/skills) so the agent knows how to use the CLI:
+
+```bash
+npx skills add browser-use/browser-use --skill browser-use
+```
+
+Create a workspace with BrowserViewer and assign it to an agent:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { Agent } from '@mastra/core/agent'
+import { Workspace, LocalSandbox } from '@mastra/core/workspace'
+import { BrowserViewer } from '@mastra/browser-viewer'
+
+const workspace = new Workspace({
+  sandbox: new LocalSandbox({
+    workingDirectory: './workspace',
+  }),
+  browser: new BrowserViewer({
+    cli: 'browser-use',
+    headless: false,
+  }),
+})
+
+const browserAgent = new Agent({
+  id: 'browser-agent',
+  model: 'openai/gpt-5.4',
+  workspace,
+  instructions: `You are a web automation assistant.
+Use browser-use commands to navigate and interact with websites.`,
+})
+
+export const mastra = new Mastra({
+  agents: { browserAgent },
+})
+```
+
+When the agent runs a CLI command like `browser-use open https://example.com`, Mastra automatically launches Chrome, injects the CDP connection, and starts streaming the screencast to Studio.
+
+## How it works
+
+1. The agent calls `workspace_execute_command` with a browser CLI command.
+2. Mastra detects the CLI command and launches Chrome via Playwright (if not already running).
+3. The CDP URL is injected into the command so the CLI connects to the managed browser.
+4. Screencast frames stream from page-level CDP sessions to Studio.
+
+## Supported CLIs
+
+BrowserViewer supports three CLI providers. Each CLI must be installed separately in your workspace environment. Each CLI also publishes a [skill](https://mastra.ai/docs/workspace/skills) that teaches the agent its commands and workflows.
+
+### agent-browser
+
+```bash
+npm install -g agent-browser
+npx skills add vercel-labs/agent-browser
+```
+
+CDP flag: `--cdp`
+
+### browser-use
+
+```bash
+pip install browser-use
+npx skills add browser-use/browser-use --skill browser-use
+```
+
+CDP flag: `--cdp-url`
+
+### browse-cli
+
+```bash
+npm install -g @browserbasehq/browse-cli
+npx skills add browserbase/skills
+```
+
+CDP flag: `--ws`
+
+Set the `cli` option to match the CLI your agent uses:
+
+```typescript
+const viewer = new BrowserViewer({
+  cli: 'browser-use',
+  headless: false,
+})
+```
+
+> **Note:** See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Workspace skills](https://mastra.ai/docs/workspace/skills)

package/.docs/docs/browser/overview.md

@@ -0,0 +1,168 @@
+# Browser overview
+
+Browser support enables agents to navigate websites, interact with page elements, fill forms, and extract data. Mastra provides browser capabilities through SDK providers that wrap browser automation libraries and a CLI provider for agents that drive browsers through command-line tools.
+
+Mastra supports two SDK providers and one CLI provider:
+
+- [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
+- [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+- [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
+
+## When to use browser
+
+Use browser when your agent needs to:
+
+- Navigate websites and interact with page elements
+- Fill out forms and submit data
+- Extract structured data from web pages
+- Automate multi-step web workflows
+- Take actions that require a real browser (JavaScript rendering, authentication flows)
+
+## How it works
+
+When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser: navigating to URLs, selecting elements, typing text, and reading page content.
+
+Each provider offers a different set of tools optimized for its approach.
+
+## Quickstart
+
+Install your provider of choice, for this example you'll use the AgentBrowser provider.
+
+**npm**:
+
+```bash
+npm install @mastra/agent-browser
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/agent-browser
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/agent-browser
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/agent-browser
+```
+
+Create a new browser instance:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+export const browser = new AgentBrowser({
+  headless: false,
+})
+```
+
+Assign the browser to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { browser } from '../browsers'
+
+export const webAgent = new Agent({
+  id: 'web-agent',
+  name: 'Web Agent',
+  description: 'A web automation assistant that can navigate websites and complete tasks.',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions:
+    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
+})
+```
+
+The agent automatically receives all browser tools from the provider.
+
+## Cloud providers
+
+Both SDK providers support connecting to cloud browser services instead of launching a local browser.
+
+### Browserbase (Stagehand native)
+
+Stagehand has native Browserbase integration:
+
+```typescript
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+})
+```
+
+### CDP URL (any provider)
+
+Connect to any browser exposing a Chrome DevTools Protocol (CDP) endpoint:
+
+```typescript
+import { AgentBrowser } from '@mastra/agent-browser'
+
+const browser = new AgentBrowser({
+  cdpUrl: process.env.BROWSER_CDP_URL,
+  headless: true,
+})
+```
+
+This works with any [CDP-compatible](https://chromedevtools.github.io/devtools-protocol/) browser service.
+
+## Screencast
+
+Browser providers stream a live video feed of the browser to the Mastra Studio UI. This lets you watch the agent interact with pages in real-time.
+
+Screencast requires WebSocket support. Install these packages in your project:
+
+**npm**:
+
+```bash
+npm install ws @hono/node-ws
+```
+
+**pnpm**:
+
+```bash
+pnpm add ws @hono/node-ws
+```
+
+**Yarn**:
+
+```bash
+yarn add ws @hono/node-ws
+```
+
+**Bun**:
+
+```bash
+bun add ws @hono/node-ws
+```
+
+> **Note:** These packages are not included by default because they are incompatible with serverless environments like Cloudflare Workers. If they are not installed, screencast is disabled but all other browser functionality works normally.
+
+Screencast is enabled by default and can be configured:
+
+```typescript
+const browser = new AgentBrowser({
+  screencast: {
+    enabled: true,
+    format: 'jpeg',
+    quality: 80,
+    maxWidth: 1280,
+    maxHeight: 720,
+  },
+})
+```
+
+## Next steps
+
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
+- [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)

package/.docs/docs/browser/stagehand.md

@@ -0,0 +1,129 @@
+# Stagehand
+
+The `@mastra/stagehand` package provides browser automation using the [Stagehand SDK](https://docs.browserbase.com/stagehand/introduction) from Browserbase. Stagehand uses AI to understand page context and locate elements, enabling natural language descriptions instead of explicit selectors.
+
+## When to use Stagehand
+
+Use Stagehand when you need:
+
+- Natural language element targeting ("select the login button")
+- AI-powered data extraction from pages
+- Native Browserbase cloud integration
+- Simpler tool interface for common actions
+
+## Quickstart
+
+Install the package:
+
+**npm**:
+
+```bash
+npm install @mastra/stagehand
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/stagehand
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/stagehand
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/stagehand
+```
+
+Create a browser instance and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { StagehandBrowser } from '@mastra/stagehand'
+
+const browser = new StagehandBrowser({
+  headless: false,
+  model: 'openai/gpt-5.4',
+})
+
+export const stagehandAgent = new Agent({
+  id: 'stagehand-agent',
+  name: 'Stagehand Agent',
+  model: 'openai/gpt-5.4',
+  browser,
+  instructions: `You are a web automation assistant.
+
+Use stagehand tools to interact with pages:
+- stagehand_navigate to go to URLs
+- stagehand_act to perform actions described in natural language
+- stagehand_extract to get structured data from the page
+- stagehand_observe to find available actions on the page`,
+})
+```
+
+## Natural language actions
+
+When the agent uses the `stagehand_act` tool, it accepts natural language descriptions of actions:
+
+- "Press the Sign In button"
+- "Type `'[user@example.com](mailto:user@example.com)'` in the email field"
+- "Select 'United States' from the country dropdown"
+
+Stagehand's AI interprets the action and finds the appropriate element on the page.
+
+## Data extraction
+
+When the agent uses the `stagehand_extract` tool, it can pull structured data from pages.
+
+Example instruction: "Extract the product name, price, and availability"
+
+The tool returns structured data based on page content:
+
+```json
+{
+  "name": "Widget Pro",
+  "price": "$29.99",
+  "availability": "In Stock"
+}
+```
+
+## Observing actions
+
+When the agent uses the `stagehand_observe` tool, it analyzes the current page and returns possible actions.
+
+Example instruction: "What actions can I take on this login form?"
+
+Returns a list of available actions:
+
+```json
+[
+  { "action": "Press 'Sign In' button", "element": "button" },
+  { "action": "Type in 'Email' field", "element": "input" },
+  { "action": "Open 'Forgot Password' link", "element": "a" }
+]
+```
+
+## Browserbase
+
+Stagehand has native Browserbase integration for cloud browser infrastructure:
+
+```typescript
+const browser = new StagehandBrowser({
+  env: 'BROWSERBASE',
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+  model: 'openai/gpt-5.4',
+})
+```
+
+> **Note:** See [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser) for all configuration options.
+
+## Related
+
+- [Browser overview](https://mastra.ai/docs/browser/overview)
+- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
+- [StagehandBrowser reference](https://mastra.ai/reference/browser/stagehand-browser)

package/.docs/docs/deployment/cloud-providers.md

@@ -2,7 +2,11 @@
 
 Mastra applications can be deployed to cloud providers and serverless platforms. Mastra includes optional built-in deployers for Vercel, Netlify, and Cloudflare to automate the deployment process.
 
-## Supported cloud providers
+## Mastra platform
+
+Mastra provides a platform to deploy your server to the cloud. Read the [Mastra platform deployment guide](https://mastra.ai/guides/deployment/mastra-platform) to learn more.
+
+## Cloud providers
 
 The following guides show how to deploy Mastra to specific cloud providers: