Mastra

https://mastra.ai/docs
Admin
Mastra is a TypeScript framework for building AI-powered applications and agents with built-in...
Tokens:492,545
Snippets:3,846
Trust Score:9.4
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install @mastra/editor and @mastra/libsql with Bun

Source: https://mastra.ai/docs/studio/editor

Install the Editor and LibSQL packages using Bun. This is part of the quickstart setup.

```bash
bun add @mastra/editor @mastra/libsql
```

--------------------------------

### Install @mastra/editor and @mastra/libsql with npm

Source: https://mastra.ai/docs/studio/editor

Install the Editor and LibSQL packages using npm. This is part of the quickstart setup.

```bash
npm install @mastra/editor @mastra/libsql
```

--------------------------------

### Install @mastra/editor and @mastra/libsql with pnpm

Source: https://mastra.ai/docs/studio/editor

Install the Editor and LibSQL packages using pnpm. This is part of the quickstart setup.

```bash
pnpm add @mastra/editor @mastra/libsql
```

--------------------------------

### Install @mastra/editor and @mastra/libsql with Yarn

Source: https://mastra.ai/docs/studio/editor

Install the Editor and LibSQL packages using Yarn. This is part of the quickstart setup.

```bash
yarn add @mastra/editor @mastra/libsql
```

--------------------------------

### Install @mastra/tanstack-start with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the TanStack Start adapter and the hono package using Bun.

```bash
bun add @mastra/tanstack-start@latest hono
```

--------------------------------

### Install @mastra/tanstack-start with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the TanStack Start adapter and the hono package using npm.

```bash
npm install @mastra/tanstack-start@latest hono
```

--------------------------------

### Install @mastra/tanstack-start with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the TanStack Start adapter and the hono package using pnpm.

```bash
pnpm add @mastra/tanstack-start@latest hono
```

--------------------------------

### Install @mastra/tanstack-start with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the TanStack Start adapter and the hono package using Yarn.

```bash
yarn add @mastra/tanstack-start@latest hono
```

--------------------------------

### Install @mastra/deployer-sandbox and @mastra/vercel with npm

Source: https://mastra.ai/docs/deployment/sandbox

Install the deployer and Vercel sandbox provider using npm. This is the first step in the quickstart.

```bash
npm install @mastra/deployer-sandbox @mastra/vercel
```

--------------------------------

### Install mastra CLI globally with npm

Source: https://mastra.ai/docs/mastra-platform/studio

Install the mastra CLI globally using npm. This is the first step in the quickstart to deploy Studio.

```bash
npm install -g mastra
```

--------------------------------

### Install mastra CLI globally with Bun

Source: https://mastra.ai/docs/mastra-platform/studio

Install the mastra CLI globally using Bun. This is an alternative to npm for the quickstart.

```bash
bun add --global mastra
```

--------------------------------

### Install @mastra/memory with npm

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/memory package using npm. This is the first step in the quickstart.

```bash
npm install @mastra/memory@latest
```

--------------------------------

### Install mastra CLI globally with pnpm

Source: https://mastra.ai/docs/mastra-platform/studio

Install the mastra CLI globally using pnpm. This is an alternative to npm for the quickstart.

```bash
pnpm add -g mastra
```

--------------------------------

### Install @mastra/fastify with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Fastify adapter using Bun.

```bash
bun add @mastra/fastify@latest
```

--------------------------------

### dataset.startExperiment with lifecycle hooks

Source: https://mastra.ai/docs/evals/experiments

Example of starting an experiment with lifecycle hooks to prepare and clean up state around the target run.

```APIDOC
## dataset.startExperiment

### Description
Starts an experiment with lifecycle hooks to prepare state before the target runs and clean up afterward. Hooks run at two levels: beforeAll/afterAll run once per experiment, and beforeEach/afterEach run once per item.

### Method
startExperiment

### Endpoint
dataset.startExperiment

### Parameters

#### Request Body
- **targetType** (string) - Required - The type of target (e.g., 'agent').
- **targetId** (string) - Required - The identifier of the target.
- **scorers** (array) - Required - List of scorer identifiers.
- **beforeAll** (function) - Optional - Async hook that runs once before all items. Receives an object with `experimentId`.
- **beforeEach** (function) - Optional - Async hook that runs before each item. Receives an object with `item`.
- **afterEach** (function) - Optional - Async hook that runs after each item. Receives an object with `item` and `result`.
- **afterAll** (function) - Optional - Async hook that runs once after all items. Receives an object with `summary`.

### Hook Parameters

All hooks receive an object containing:
- **experimentId** (string) - The experiment identifier.
- **mastra** (Mastra instance) - The Mastra instance.
- **signal** (AbortSignal) - Run-level signal for cancellation.

Per-item hooks (`beforeEach`, `afterEach`) also receive:
- **item** (object) - Contains `id`, `input`, `groundTruth`, and `metadata`. Execution-control fields (tool mocks, scorer selection) are not exposed.

Teardown hooks receive:
- **afterEach** receives `result` including scores.
- **afterAll** receives `summary` that is about to be returned.

### Request Example
```typescript
const summary = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'document-agent',
  scorers: ['accuracy'],
  beforeAll: async ({ experimentId }) => {
    await createWorkspace(experimentId)
  },
  beforeEach: async ({ item }) => {
    await copyFixture(item.metadata?.fixture)
  },
  afterEach: async ({ item, result }) => {
    await clearWorkspaceFiles(item.id)
  },
  afterAll: async ({ summary }) => {
    await deleteWorkspace(summary.experimentId)
  },
})
```

### Response
Returns a summary object containing at least `experimentId`.

### Hook Failure Behavior

| Hook | On failure |
| --- | --- |
| `beforeAll` | Fails the experiment. No items run. |
| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
| `afterEach` | Logged. The item's recorded outcome doesn't change. |
| `afterAll` | Logged. The returned summary doesn't change. |

When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.

When `beforeEach` fails, the target and its scorers are skipped for that item, and `afterEach` is also skipped for that item.

Teardown failures are logged rather than propagated.

`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an event observer fails. It runs at most once per experiment.
```

--------------------------------

### Install @mastra/libsql with Bun

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/libsql storage provider using Bun.

```bash
bun add @mastra/libsql@latest
```

--------------------------------

### Install mastra CLI globally with Yarn

Source: https://mastra.ai/docs/mastra-platform/studio

Install the mastra CLI globally using Yarn. This is an alternative to npm for the quickstart.

```bash
yarn global add mastra
```

--------------------------------

### startExperiment with persistence

Source: https://mastra.ai/docs/evals/experiments

Example of starting an experiment with persistence disabled for both experiments and scores.

```APIDOC
## startExperiment

### Description
Starts an experiment run with configurable persistence settings to skip storage writes for experiment records and score records.

### Method
startExperiment

### Endpoint
N/A (SDK method)

### Parameters
#### Request Body
- **targetType** (string) - Required - The type of target, e.g., 'agent'.
- **targetId** (string) - Required - The identifier of the target, e.g., 'translation-agent'.
- **scorers** (array) - Required - List of scorer identifiers, e.g., ['accuracy'].
- **persistence** (object) - Optional - Persistence settings for the run.
  - **experiments** (string) - Optional - Set to 'none' to skip experiment record persistence. Defaults to 'default'.
  - **scores** (string) - Optional - Set to 'none' to skip score record persistence. Defaults to 'default'.

### Request Example
```typescript
const summary = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'translation-agent',
  scorers: ['accuracy'],
  persistence: {
    experiments: 'none',
    scores: 'none',
  },
})
```

### Response
#### Success Response
- **summary** (object) - Contains item results and scores from the run.

#### Response Example
```typescript
const summary = await dataset.startExperiment({
  targetType: 'agent',
  targetId: 'translation-agent',
  scorers: ['accuracy'],
  persistence: {
    experiments: 'none',
    scores: 'none',
  },
})
```
```

--------------------------------

### Quickstart: subscribe to a thread and send a message

Source: https://mastra.ai/docs/harness/signals

Creates an agent, subscribes to a thread, and sends a message. The subscription receives the active stream when the message wakes the agent or enters a running loop. When the thread is idle, Mastra starts a stream with the message as the first input.

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'support-agent',
  name: 'Support Agent',
  instructions: 'Help the user compare options.',
  model: 'openai/gpt-5.6-sol',
})

const thread = {
  resourceId: 'user_123',
  threadId: 'thread_456',
}

const subscription = await agent.subscribeToThread(thread)

await agent.sendMessage('Compare that with the previous option.', thread)

for await (const chunk of subscription.stream) {
  console.log(chunk)
}
```

--------------------------------

### Install @mastra/platform-workspace with Bun

Source: https://mastra.ai/docs/mastra-platform/workspaces

Install the provider package using Bun.

```bash
bun add @mastra/platform-workspace
```

--------------------------------

### Install @mastra/fastify with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Fastify adapter using npm.

```bash
npm install @mastra/fastify@latest
```

--------------------------------

### Install @mastra/client-js with Bun

Source: https://mastra.ai/docs/server/mastra-client

Install the Mastra Client SDK using Bun.

```bash
bun add @mastra/client-js@latest
```

--------------------------------

### Install @mastra/fastify with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Fastify adapter using pnpm.

```bash
pnpm add @mastra/fastify@latest
```

--------------------------------

### Install @mastra/client-js with npm

Source: https://mastra.ai/docs/server/mastra-client

Install the Mastra Client SDK using npm.

```bash
npm install @mastra/client-js@latest
```

--------------------------------

### Install @mastra/nestjs with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the NestJS adapter using Bun.

```bash
bun add @mastra/nestjs@latest
```

--------------------------------

### Install @mastra/libsql with pnpm

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/libsql storage provider using pnpm.

```bash
pnpm add @mastra/libsql@latest
```

--------------------------------

### Install @mastra/express with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Express adapter using Bun.

```bash
bun add @mastra/express@latest
```

--------------------------------

### Install @mastra/libsql with Yarn

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/libsql storage provider using Yarn.

```bash
yarn add @mastra/libsql@latest
```

--------------------------------

### Install @mastra/hono with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Hono adapter using Bun.

```bash
bun add @mastra/hono@latest
```

--------------------------------

### Install @mastra/connect with Bun

Source: https://mastra.ai/docs/mastra-platform/connect/overview

Install the @mastra/connect package using Bun.

```bash
bun add @mastra/connect
```

--------------------------------

### Install @mastra/koa with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Koa adapter using Bun.

```bash
bun add @mastra/koa@latest
```

--------------------------------

### Install @mastra/fastify with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the Fastify adapter using Yarn.

```bash
yarn add @mastra/fastify@latest
```

--------------------------------

### Install @mastra/platform-workspace with Yarn

Source: https://mastra.ai/docs/mastra-platform/workspaces

Install the provider package using Yarn.

```bash
yarn add @mastra/platform-workspace
```

--------------------------------

### Quickstart: Register a tool and run a dynamic workflow

Source: https://mastra.ai/docs/workflows/dynamic-workflows

Registers a greeting tool, adds a dynamic workflow with JSON Schema input/output, and runs it. Requires LibSQLStore for persistence. Outputs 'Hello, Ada!' on success.

```typescript
import { Mastra } from '@mastra/core/mastra'
import { createTool } from '@mastra/core/tools'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const greetingTool = createTool({
  id: 'create-greeting',
  description: 'Create a greeting for a name',
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    message: z.string(),
  }),
  execute: async ({ name }) => ({
    message: `Hello, ${name}!`,
  }),
})

const mastra = new Mastra({
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  tools: { 'create-greeting': greetingTool },
})

await mastra.addDynamicWorkflow({
  id: 'greeting-workflow',
  description: 'Create a greeting for the supplied name',
  inputSchema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
    },
    required: ['name'],
  },
  outputSchema: {
    type: 'object',
    properties: {
      message: { type: 'string' },
    },
    required: ['message'],
  },
  graph: [
    {
      type: 'tool',
      id: 'greet',
      toolId: 'create-greeting',
    },
  ],
})

const workflow = mastra.getWorkflow('greeting-workflow')
const run = await workflow.createRun()
const result = await run.start({
  inputData: { name: 'Ada' },
})

if (result.status === 'success') {
  console.log(result.result.message)
}
```

--------------------------------

### Install @mastra/next with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Next.js adapter and the hono package using Bun.

```bash
bun add @mastra/next@latest hono
```

--------------------------------

### Install @mastra/platform-workspace with npm

Source: https://mastra.ai/docs/mastra-platform/workspaces

Install the provider package using npm.

```bash
npm install @mastra/platform-workspace
```

--------------------------------

### Install @mastra/platform-workspace with pnpm

Source: https://mastra.ai/docs/mastra-platform/workspaces

Install the provider package using pnpm.

```bash
pnpm add @mastra/platform-workspace
```

--------------------------------

### Install @mastra/hono with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Hono adapter using npm.

```bash
npm install @mastra/hono@latest
```

--------------------------------

### Install @mastra/express with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Express adapter using npm.

```bash
npm install @mastra/express@latest
```

--------------------------------

### Start Studio with npm

Source: https://mastra.ai/docs/studio/overview

Run the development server for Studio using npm. This starts the Studio UI at localhost:4111 and the Swagger UI at localhost:4111/swagger-ui.

```bash
npm run dev
```

--------------------------------

### Install @mastra/next with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Next.js adapter and the hono package using npm.

```bash
npm install @mastra/next@latest hono
```

--------------------------------

### Install @mastra/koa with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Koa adapter using npm.

```bash
npm install @mastra/koa@latest
```

--------------------------------

### Quickstart: Instantiate ModerationProcessor and pass to agent

Source: https://mastra.ai/docs/agents/processors

Import Agent and ModerationProcessor, then create an agent with inputProcessors containing a ModerationProcessor configured with model, categories, threshold, and strategy.

```typescript
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',
  inputProcessors: [
    new ModerationProcessor({
      model: 'openai/gpt-5-mini',
      categories: ['hate', 'harassment', 'violence'],
      threshold: 0.7,
      strategy: 'block',
    }),
  ],
})
```

--------------------------------

### Install @mastra/client-js with pnpm

Source: https://mastra.ai/docs/server/mastra-client

Install the Mastra Client SDK using pnpm.

```bash
pnpm add @mastra/client-js@latest
```

--------------------------------

### Install @mastra/memory with Bun

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/memory package using Bun.

```bash
bun add @mastra/memory@latest
```

--------------------------------

### Install @mastra/hono with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the Hono adapter using Yarn.

```bash
yarn add @mastra/hono@latest
```

--------------------------------

### Install @mastra/express with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the Express adapter using Yarn.

```bash
yarn add @mastra/express@latest
```

--------------------------------

### Install @mastra/client-js with Yarn

Source: https://mastra.ai/docs/server/mastra-client

Install the Mastra Client SDK using Yarn.

```bash
yarn add @mastra/client-js@latest
```

--------------------------------

### Start Studio with Bun

Source: https://mastra.ai/docs/studio/overview

Run the development server for Studio using Bun. This starts the Studio UI at localhost:4111 and the Swagger UI at localhost:4111/swagger-ui.

```bash
bun run dev
```

--------------------------------

### Install @mastra/express with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Express adapter using pnpm.

```bash
pnpm add @mastra/express@latest
```

--------------------------------

### Install @mastra/evals with Bun

Source: https://mastra.ai/docs/evals/overview

Install the @mastra/evals package using Bun. Use @latest to get the most recent version.

```bash
bun add @mastra/evals@latest
```

--------------------------------

### Initialize Node.js project with npm

Source: https://mastra.ai/docs/studio/deployment

Creates a new folder and initializes a Node.js project using npm.

```bash
mkdir studio-spa
cd studio-spa
npm init
```

--------------------------------

### Install @mastra/evals with Yarn

Source: https://mastra.ai/docs/evals/overview

Install the @mastra/evals package using Yarn. Use @latest to get the most recent version.

```bash
yarn add @mastra/evals@latest
```

--------------------------------

### Install @mastra/connect with npm

Source: https://mastra.ai/docs/mastra-platform/connect/overview

Install the @mastra/connect package using npm.

```bash
npm install @mastra/connect
```

--------------------------------

### Install @mastra/agent-browser with Bun

Source: https://mastra.ai/docs/browser

Install the AgentBrowser provider package using Bun.

```bash
bun add @mastra/agent-browser
```

--------------------------------

### Install @mastra/evals with pnpm

Source: https://mastra.ai/docs/evals/overview

Install the @mastra/evals package using pnpm. Use @latest to get the most recent version.

```bash
pnpm add @mastra/evals@latest
```

--------------------------------

### Install @mastra/evals with npm

Source: https://mastra.ai/docs/evals/overview

Install the @mastra/evals package using npm. Use @latest to get the most recent version.

```bash
npm install @mastra/evals@latest
```

--------------------------------

### Install @mastra/connect with Yarn

Source: https://mastra.ai/docs/mastra-platform/connect/overview

Install the @mastra/connect package using Yarn.

```bash
yarn add @mastra/connect
```

--------------------------------

### Initialize Node.js project with Bun

Source: https://mastra.ai/docs/studio/deployment

Creates a new folder and initializes a Node.js project using Bun.

```bash
mkdir studio-spa
cd studio-spa
bun init
```

--------------------------------

### Install @mastra/elysia with Bun

Source: https://mastra.ai/docs/server/server-adapters

Installs the Elysia adapter and the elysia package using Bun.

```bash
bun add @mastra/elysia@latest elysia
```

--------------------------------

### Start Studio with pnpm

Source: https://mastra.ai/docs/studio/overview

Run the development server for Studio using pnpm. This starts the Studio UI at localhost:4111 and the Swagger UI at localhost:4111/swagger-ui.

```bash
pnpm run dev
```

--------------------------------

### Start Mastra server with Studio path

Source: https://mastra.ai/docs/studio/deployment

Set the MASTRA_STUDIO_PATH environment variable to the built Studio assets and start the Mastra server. This serves the Studio UI alongside your API.

```bash
MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs
```

--------------------------------

### Install @mastra/elysia with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Elysia adapter and the elysia package using npm.

```bash
npm install @mastra/elysia@latest elysia
```

--------------------------------

### Install @mastra/observability and storage backends with Bun

Source: https://mastra.ai/docs/observability/overview

Install the required packages for observability and storage backends using Bun.

```bash
bun add @mastra/observability @mastra/libsql @mastra/duckdb
```

--------------------------------

### Install @mastra/next with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the Next.js adapter and the hono package using Yarn.

```bash
yarn add @mastra/next@latest hono
```

--------------------------------

### Install test suite with Bun

Source: https://mastra.ai/docs/server/custom-adapters

Installs @mastra/server-adapters-test-suite and its peer dependencies as dev dependencies using Bun.

```bash
bun add --dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
```

--------------------------------

### run.stream()

Source: https://mastra.ai/docs/workflows/overview

Starts a workflow run and emits events during execution, allowing you to monitor progress and get the final result.

```APIDOC
## run.stream()

### Description
Starts a workflow run and emits events during execution, allowing you to monitor progress and get the final result.

### Method
stream

### Parameters
#### inputData
- **inputData** (object) - Required - The input data matching the workflow's `inputSchema`.

### Request Example
```typescript
const run = await testWorkflow.createRun()

const stream = run.stream({
  inputData: {
    message: 'Hello world',
  },
})

for await (const chunk of stream.fullStream) {
  console.log(chunk)
}

// Get the final result (same type as run.start())
const result = await stream.result

if (result.status === 'success') {
  console.log(result.result)
}
```

### Response
#### Success Response (200)
- **fullStream** (async iterable) - An async iterable of events emitted during execution.
- **result** (Promise) - A promise that resolves to the final workflow result (same type as `run.start()`).

#### Response Example
```json
{
  "status": "success",
  "steps": {
    "step-1": {
      "status": "success",
      "payload": {
        "message": "Hello world"
      },
      "output": {
        "formatted": "HELLO WORLD"
      }
    },
    "step-2": {
      "status": "success",
      "payload": {
        "formatted": "HELLO WORLD"
      },
      "output": {
        "emphasized": "HELLO WORLD!!!"
      }
    }
  },
  "input": {
    "message": "Hello world"
  },
  "result": {
    "emphasized": "HELLO WORLD!!!"
  }
}
```
```

--------------------------------

### Example deployment output with API and Studio URLs

Source: https://mastra.ai/docs/deployment/sandbox

Example output from `mastra build` showing the API and Studio URLs. The manifest includes `expiresAt` when the provider reports an expiration time.

```text
API:    https://<sandbox-id>-4111.vercel.run/api
Studio: https://<sandbox-id>-4111.vercel.run
```

--------------------------------

### Install Mastra skills with Bun

Source: https://mastra.ai/docs/develop

Install the Mastra skills using Bun. Equivalent to the npm command.

```bash
bun x skills add mastra-ai/skills
```

--------------------------------

### Retrieve trace ID from workflow run and stream

Source: https://mastra.ai/docs/observability/tracing/overview

Shows how to get the trace ID from a workflow execution using `createRun`, `start`, and `stream`. The trace ID is available in the result of `start` and in the final state obtained from `getWorkflowState`.

```TypeScript
// Create a workflow run
const run = await mastra.getWorkflow('myWorkflow').createRun()

// Start the workflow
const result = await run.start({
  inputData: { data: 'process this' },
})

console.log('Trace ID:', result.traceId)

// Or stream the workflow
const { stream, getWorkflowState } = run.stream({
  inputData: { data: 'process this' },
})

// Get the final state which includes the trace ID
const finalState = await getWorkflowState()
console.log('Trace ID:', finalState.traceId)
```

--------------------------------

### Install @mastra/next with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Next.js adapter and the hono package using pnpm.

```bash
pnpm add @mastra/next@latest hono
```

--------------------------------

### Install @mastra/libsql with npm

Source: https://mastra.ai/docs/memory/overview

Install the @mastra/libsql storage provider using npm. Memory requires a storage provider.

```bash
npm install @mastra/libsql@latest
```

--------------------------------

### Start background workers with MastraServer and Express

Source: https://mastra.ai/docs/server/server-adapters

Call `mastra.startWorkers()` after the server starts listening to enable scheduled workflows, agent schedules, and event listeners. The example uses Express and `MastraServer` from `@mastra/express`. `startWorkers()` is idempotent; `mastra.shutdown()` drains in-flight runs within `drainTimeout` (default 5 seconds).

```typescript
import express from 'express'
import { MastraServer } from '@mastra/express'
import { mastra } from './mastra'

const app = express()
app.use(express.json())

const server = new MastraServer({ app, mastra })
await server.init()

const httpServer = app.listen(4111, async () => {
  try {
    await mastra.startWorkers()
  } catch (error) {
    console.error('Failed to start background workers', error)
    httpServer.close(() => process.exit(1))
  }
})

process.on('SIGTERM', async () => {
  await mastra.shutdown()
  process.exit(0)
})
```

--------------------------------

### Start experiment with scorer instances

Source: https://mastra.ai/docs/evals/experiments

Pass scorer instances to the scorers option. This example creates an answer relevancy scorer using a specific model and passes it to the experiment.

```typescript
import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'

const relevancy = createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' })

const summary = await dataset.startExperiment({
  name: 'with-scorer-instances',
  targetType: 'agent',
  targetId: 'translation-agent',
  scorers: [relevancy],
})
```

--------------------------------

### Install @mastra/deployer-sandbox and @mastra/vercel with Bun

Source: https://mastra.ai/docs/deployment/sandbox

Install the deployer and Vercel sandbox provider using Bun. Alternative to npm.

```bash
bun add @mastra/deployer-sandbox @mastra/vercel
```

--------------------------------

### Configure MastraJwtAuth in Mastra server

Source: https://mastra.ai/docs/auth/jwt

Example of configuring MastraJwtAuth with a secret from environment variables in the Mastra server setup. The secret should match the one used to sign JWTs.

```typescript
import { Mastra } from '@mastra/core'
import { MastraJwtAuth } from '@mastra/auth'

export const mastra = new Mastra({
  server: {
    auth: new MastraJwtAuth({
      secret: process.env.MASTRA_JWT_SECRET,
    }),
  },
})
```

--------------------------------

### Get experiment details

Source: https://mastra.ai/docs/evals/experiments

Fetches a single experiment by its ID. Throws an error if the experiment is not found. Logs the experiment's status, start time, and completion time.

```typescript
const experiment = await dataset.getExperiment({
  experimentId: 'exp-abc-123',
})
if (!experiment) throw new Error('Experiment not found')

console.log(experiment.status)
console.log(experiment.startedAt)
console.log(experiment.completedAt)
```

--------------------------------

### Install @mastra/observability and storage backends with npm

Source: https://mastra.ai/docs/observability/overview

Install the required packages for observability and storage backends using npm.

```bash
npm install @mastra/observability @mastra/libsql @mastra/duckdb
```

--------------------------------

### Configure LSP - lsp object example

Source: https://mastra.ai/docs/sandbox/lsp

Example `lsp` configuration object. Set `lsp: true` for defaults, or use an object to control root, server discovery, timeouts, and retained clients. `binaryOverrides` maps server IDs to startup commands, and `searchPaths` adds package roots. `diagnosticTimeout` controls direct API wait times; the agent inspection tool waits up to five seconds.

```typescript
lsp: {
  root: projectPath,
  diagnosticTimeout: 4_000,
  initTimeout: 8_000,
  maxOpenClients: 4,
  disableServers: ['eslint'],
  binaryOverrides: {
    typescript: '/opt/mastra-tools/typescript-language-server --stdio',
  },
  searchPaths: ['/opt/mastra-tools'],
},
```

--------------------------------

### Provide function for tool approval decision

Source: https://mastra.ai/docs/connections/mcp

Provides a function that decides tool approval based on the tool name, arguments, or annotations. The example checks if the tool name starts with 'delete_'.

```typescript
requireToolApproval: ({ toolName }) => toolName.startsWith('delete_')
```

--------------------------------

### CompositeAuth error handling example

Source: https://mastra.ai/docs/auth/composite-auth

Shows that if clerkAuth throws an error, apiKeyAuth still gets tried because CompositeAuth silently catches errors from individual providers and moves to the next one.

```typescript
// If clerkAuth throws an error, apiKeyAuth still gets tried
new CompositeAuth([clerkAuth, apiKeyAuth])
```

--------------------------------

### Stream agent response with Agent.stream()

Source: https://mastra.ai/docs/guides/streaming

Use Agent.stream() to get a stream and iterate over textStream with a for await loop to process chunks as they are generated. The example passes an array of message objects with role and content.

```typescript
const testAgent = mastra.getAgent('testAgent')

const stream = await testAgent.stream([{ role: 'user', content: 'Help me organize my day' }])

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk)
}
```

--------------------------------

### Stream agent response in a server action

Source: https://mastra.ai/docs/server/mastra-client

Use MastraClient in a server-side action to get an agent and stream a response. The example returns a new Response with the stream body, which may need to be recreated for your client.

```typescript
export async function action() {
  const agent = mastraClient.getAgent('testAgent')

  const stream = await agent.stream('Hello')

  return new Response(stream.body)
}
```

--------------------------------

### Install @mastra/mcp with Bun

Source: https://mastra.ai/docs/connections/mcp

Install the MCP package using Bun. This is the first step to using MCPClient.

```bash
bun add @mastra/mcp@latest
```

--------------------------------

### Filter messages passed to subagent with messageFilter

Source: https://mastra.ai/docs/guides/context-engineering

Use messageFilter in the delegation options to pass only the last 10 messages to the subagent, reducing context bloat. This example is from the Subagents section of the context engineering guide.

```typescript
await supervisor.generate('Investigate the failed deployment.', {
  delegation: {
    messageFilter: ({ messages }) => messages.slice(-10),
  },
})
```

--------------------------------

### Mastra default PubSub backend setup

Source: https://mastra.ai/docs/server/pubsub

When the pubsub option is omitted, Mastra uses EventEmitterPubSub, which delivers events in process via Node.js EventEmitter. This example shows the minimal Mastra initialization without a pubsub option.

```typescript
import { Mastra } from '@mastra/core'

// No pubsub option: Mastra uses EventEmitterPubSub
export const mastra = new Mastra({})
```

--------------------------------

### Start the server with Mastra CLI

Source: https://mastra.ai/docs/deployment/mastra-server

Use the `mastra start` command to start the server. It loads environment variables from `.env.production` and `.env`, provides helpful error messages for missing modules, and handles process signals for graceful shutdown.

```bash
mastra start
```

--------------------------------

### Define custom route with FGA metadata

Source: https://mastra.ai/docs/auth/fga

For custom routes, prefer route-level fga metadata to keep authorization policy next to the route. This example shows a GET route for /projects/:projectId with resourceType, resourceIdParam, and permission.

```typescript
import { createRoute } from '@mastra/server/server-adapter'

export const getProjectRoute = createRoute({
  method: 'GET',
  path: '/projects/:projectId',
  responseType: 'json',
  requiresAuth: true,
  fga: {
    resourceType: 'project',
    resourceIdParam: 'projectId',
    permission: 'projects:read',
  },
  handler: async () => {
    return { project: null }
  },
})
```

--------------------------------

### Set up a workspace with local filesystem

Source: https://mastra.ai/docs/guides/context-engineering

Creates a Workspace with a LocalFilesystem, enabling BM25 search and auto-indexing of markdown files. Agents receive tools like read_file, list_files, grep, mastra_workspace_search, and mastra_workspace_index. The workspace must be initialized with await workspace.init().

```typescript
import { LocalFilesystem, Workspace } from '@mastra/core/workspace'

export const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './knowledge-base' }),
  bm25: true,
  autoIndexPaths: ['**/*.md'],
})

// Agents receive tools including read_file, list_files, grep,
// mastra_workspace_search, and mastra_workspace_index.
await workspace.init()
```

--------------------------------

### Agent schema validation with requestContextSchema

Source: https://mastra.ai/docs/server/request-context

Defines requestContextSchema on an agent to validate context at the start of generate() or stream(). If validation fails, the agent throws a MastraError before any LLM calls. The example shows accessing values via requestContext.all or .get() in instructions.

```typescript
import { Agent } from '@mastra/core/agent'
import { z } from 'zod'

export const validatedAgent = new Agent({
  id: 'validated-agent',
  name: 'Validated Agent',
  requestContextSchema: z.object({
    userId: z.string(),
    apiKey: z.string(),
  }),
  instructions: ({ requestContext }) => {
    // Access all values as a typed object
    const { userId, apiKey } = requestContext.all
    // { userId: string; apiKey: string }

    // Or retrieve individual values with .get()
    const id = requestContext.get('userId')
    // string

    return `You are helping user ${userId}`
  },
  model: 'openai/gpt-5.6-sol',
})
```

--------------------------------

### Get Port URL for Sandbox Web Server

Source: https://mastra.ai/docs/sandbox/overview

Use `sandbox.networking.getPortUrl()` to obtain a URL for previewing or testing a web server started inside a remote sandbox. The URL may be reachable to others depending on the backend's access controls.

```typescript
const url = await sandbox.networking?.getPortUrl(8000)
```

--------------------------------

### Configure MastraClient and get agent card with getA2A()

Source: https://mastra.ai/docs/connections/a2a

Use MastraClient.getA2A() to call an A2A-enabled agent. Configure baseUrl for the server origin and apiPrefix when the server doesn't use the default /api prefix. The example sets an Authorization header and retrieves the agent card.

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'https://agent.example.com',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_API_TOKEN}`,
  },
})

const a2a = client.getA2A('weather-agent')
const card = await a2a.getAgentCard()

console.log(card.name, card.capabilities)
```

--------------------------------

### Install @mastra/libsql adapter

Source: https://mastra.ai/docs/mastra-platform/database

Install the LibSQL adapter for Turso databases using npm, pnpm, Yarn, or Bun.

```bash
npm install @mastra/libsql@latest
```

```bash
pnpm add @mastra/libsql@latest
```

```bash
yarn add @mastra/libsql@latest
```

```bash
bun add @mastra/libsql@latest
```

--------------------------------

### Run basic experiment with startExperiment()

Source: https://mastra.ai/docs/evals/experiments

Call startExperiment() on a dataset with a target and scorers. Blocks until all items finish; logs status and success/failure counts. Requires a dataset ID and registered target.

```typescript
import { mastra } from '../index'

const dataset = await mastra.datasets.get({ id: 'translation-dataset-id' })

const summary = await dataset.startExperiment({
  name: 'gpt-5.1-baseline',
  targetType: 'agent',
  targetId: 'translation-agent',
  scorers: ['accuracy', 'fluency'],
})

console.log(summary.status) // 'completed' | 'failed'
console.log(summary.succeededCount) // number of items that ran successfully
console.log(summary.failedCount) // number of items that failed
```

--------------------------------

### Get authenticated customer record using MCP authInfo

Source: https://mastra.ai/docs/guides/authentication-identity

Use this tool to retrieve the authenticated customer record from the MCP authInfo object. It throws an error if the user ID is missing. This example uses the default bridge; req.auth is preserved from middleware or set via server.mcpOptions.setRequestAuth.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

import { customers } from '../lib/customers'

export const getCustomerRecord = createTool({
  id: 'get-customer-record',
  description: 'Get the authenticated customer record',
  inputSchema: z.object({}),
  execute: async (_input, { mcp }) => {
    const user = mcp?.extra.authInfo?.extra?.user as { id?: string } | undefined

    if (!user?.id) throw new Error('Authenticated MCP caller is missing')
    return customers.getByUserId(user.id)
  },
})
```

--------------------------------

### Using writer.write() in a workflow step

Source: https://mastra.ai/docs/guides/streaming

Example of a Mastra workflow step that uses the writer argument to emit custom events into the stream. The step fetches a URL and writes a 'custom-event' with status 'pending' before the fetch and 'success' after. You must await writer.write() or you will lock the stream and get a 'WritableStream is locked' error.

```typescript
import { createStep } from '@mastra/core/workflows'
import { z } from 'zod'

export const testStep = createStep({
  id: 'test-step',
  inputSchema: z.object({ url: z.url() }),
  outputSchema: z.object({ status: z.number() }),
  execute: async ({ inputData, writer }) => {
    const { url } = inputData

    await writer.write({
      type: 'custom-event',
      status: 'pending',
    })

    const response = await fetch(url)

    await writer.write({
      type: 'custom-event',
      status: 'success',
    })

    return {
      status: response.status,
    }
  },
})
```

--------------------------------

### Configure Vitest with MastraEvalsReporter and setup file

Source: https://mastra.ai/docs/evals/vitest-integration

Register the MastraEvalsReporter and the setup file in vitest.config.ts. The setup file registers custom matchers on expect.

```typescript
import { defineConfig } from 'vitest/config'
import { MastraEvalsReporter } from '@mastra/evals/vitest'

export default defineConfig({
  test: {
    reporters: ['default', new MastraEvalsReporter()],
    setupFiles: ['@mastra/evals/vitest/setup'],
  },
})
```

--------------------------------

### Start Studio with Yarn

Source: https://mastra.ai/docs/studio/overview

Run the development server for Studio using Yarn. This starts the Studio UI at localhost:4111 and the Swagger UI at localhost:4111/swagger-ui.

```bash
yarn dev
```

--------------------------------

### Install @mastra/nestjs with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the NestJS adapter using Yarn.

```bash
yarn add @mastra/nestjs@latest
```

--------------------------------

### Install @mastra/nestjs with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the NestJS adapter using pnpm.

```bash
pnpm add @mastra/nestjs@latest
```

--------------------------------

### Create an environment via deploy

Source: https://mastra.ai/docs/mastra-platform/environments

Deploys to the 'staging' environment, prompting for confirmation if the environment does not exist yet.

```bash
mastra deploy --env staging
```

--------------------------------

### Install @mastra/nestjs with npm

Source: https://mastra.ai/docs/server/server-adapters

Installs the NestJS adapter using npm.

```bash
npm install @mastra/nestjs@latest
```

--------------------------------

### deployToSandbox()

Source: https://mastra.ai/docs/deployment/sandbox

Deploys a prebuilt output directory to a sandbox without the bundler. Optionally includes Studio by passing studio: true. Returns a deployment object with url, logs(), stop(), and destroy() methods.

```APIDOC
## deployToSandbox()

### Description
Deploys a prebuilt output directory to a sandbox without the bundler. Unlike SandboxDeployer(), it doesn't include Studio unless you pass studio: true. Use it in CI or from agent code.

### Method
Function call

### Endpoint
`deployToSandbox(options)` from `@mastra/deployer-sandbox`

### Parameters
#### Options
- **sandbox** (Sandbox) - Required - The sandbox instance (e.g., `new VercelSandbox({ sandboxName: 'ci-smoke', ports: [4111] })`).
- **dir** (string) - Required - The prebuilt output directory path (e.g., `.mastra/output`).
- **studio** (boolean) - Optional - Whether to include Studio. Defaults to false.

### Request Example
```typescript
import { deployToSandbox } from '@mastra/deployer-sandbox'
import { VercelSandbox } from '@mastra/vercel'

const deployment = await deployToSandbox({
  sandbox: new VercelSandbox({ sandboxName: 'ci-smoke', ports: [4111] }),
  dir: '.mastra/output',
})
```

### Response
#### Success Response
- **deployment.url** (string) - The sandbox URL (e.g., `https://<sandbox-id>-4111.vercel.run`).
- **deployment.logs()** (Promise) - Tails the server log.
- **deployment.stop()** (Promise) - Stops the sandbox (resumable).
- **deployment.destroy()** (Promise) - Permanently deletes the sandbox.

#### Response Example
```typescript
console.info(deployment.url) // https://<sandbox-id>-4111.vercel.run
await deployment.logs() // tail the server log
await deployment.stop() // stop the sandbox (resumable)
await deployment.destroy() // permanently delete the sandbox
```
```

--------------------------------

### Install @mastra/koa with Yarn

Source: https://mastra.ai/docs/server/server-adapters

Installs the Koa adapter using Yarn.

```bash
yarn add @mastra/koa@latest
```

--------------------------------

### Install @mastra/koa with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Koa adapter using pnpm.

```bash
pnpm add @mastra/koa@latest
```

--------------------------------

### Start Mastra dev server with Bun

Source: https://mastra.ai/docs/develop

Run the local development server using Bun. Equivalent to the npm command, opens Mastra Studio at http://localhost:4111.

```bash
bun x mastra dev
```

--------------------------------

### Install WebSocket packages for screencast (Bun)

Source: https://mastra.ai/docs/browser

Install the required packages for screencast support using Bun. These are not included by default because they are incompatible with serverless environments like Cloudflare Workers.

```bash
bun add ws @hono/node-ws
```

--------------------------------

### Install @mastra/observability and storage backends with Yarn

Source: https://mastra.ai/docs/observability/overview

Install the required packages for observability and storage backends using Yarn.

```bash
yarn add @mastra/observability @mastra/libsql @mastra/duckdb
```

--------------------------------

### Install @mastra/hono with pnpm

Source: https://mastra.ai/docs/server/server-adapters

Installs the Hono adapter using pnpm.

```bash
pnpm add @mastra/hono@latest
```

--------------------------------

### Install @mastra/observability and storage backends with pnpm

Source: https://mastra.ai/docs/observability/overview

Install the required packages for observability and storage backends using pnpm.

```bash
pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
```

--------------------------------

### Create environment-scoped hosted databases for production and staging

Source: https://mastra.ai/docs/mastra-platform/environments

Creates separate hosted databases for the `production` and `staging` environments using the `turso` provider. Each environment reads and writes its own database by default. Use `--shared` to share one database across all environments instead.

```bash
mastra env db create production --kind turso --name my-project-production-db
mastra env db create staging --kind turso --name my-project-staging-db
```

--------------------------------

### Start workflow via Mastra CLI

Source: https://mastra.ai/docs/workflows/overview

Run this command to start the 'test-workflow' with input data. Requires a running Mastra server; start it with 'npx mastra dev' or pass the server's base URL with '--url'. Use '--schema' to inspect input schema before constructing different input.

```bash
npx mastra api workflow run start test-workflow '{"inputData":{"message":"Hello, world!"}}'
```
Tokens:
Raw