SDK agents

SDK agents let you use other agent SDK frameworks inside Mastra. Use them to register SDK-backed agents in a Mastra project while the provider SDK keeps its own runtime, tools, permissions, and agent loop.

When to use SDK agents

• A vendor SDK already owns the agent loop, tools, permissions, or local runtime.
• You want to register that SDK-backed agent in a Mastra project.
• You need Mastra-compatible generate() and stream() outputs.
• You want usage, cost, and tool activity from the SDK run to appear in Mastra observability.

Supported SDK agents

• Claude Agent SDK: Use @mastra/claude to register a Claude SDK agent and call it with Mastra generate() and stream().
• Cursor Agent SDK: Use @mastra/cursor to register a Cursor SDK agent and call it with Mastra generate() and stream().

Claude Agent SDK

Use @mastra/claude for Claude Code runtime configuration, permissions, tools, and agent-loop behavior.

Install Claude packages

Install the Mastra package and the Claude Agent SDK peer dependency:

npm

npm install @mastra/claude @anthropic-ai/claude-agent-sdk

pnpm

pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk

Yarn

yarn add @mastra/claude @anthropic-ai/claude-agent-sdk

Bun

bun add @mastra/claude @anthropic-ai/claude-agent-sdk

Set the Claude SDK credential:

export ANTHROPIC_API_KEY="..."

Create a Claude SDK agent

Configure Claude Agent SDK through sdkOptions.

src/mastra/agents/claude-sdk-agent.ts

import { ClaudeSDKAgent } from '@mastra/claude'

export const claudeSDKAgent = new ClaudeSDKAgent({
  id: 'claude-sdk-agent',
  name: 'Claude SDK Agent',
  description: 'Use Claude Agent SDK through Mastra.',
  sdkOptions: {
    model: 'claude-sonnet-4-6',
    cwd: process.cwd(),
  },
})

Add Claude SDK tools

Claude Agent SDK tools are provided through Claude SDK Model Context Protocol (MCP) servers. Create the server with the Claude SDK, then pass it through sdkOptions.mcpServers.

src/mastra/agents/claude-sdk-agent.ts

import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
import { ClaudeSDKAgent } from '@mastra/claude'
import { getTemperature } from '../tools/get-temperature'

const weatherServer = createSdkMcpServer({
  name: 'weather',
  version: '1.0.0',
  tools: [getTemperature],
})

export const claudeSDKAgent = new ClaudeSDKAgent({
  id: 'claude-sdk-agent',
  name: 'Claude SDK Agent',
  description: 'Use Claude Agent SDK through Mastra.',
  sdkOptions: {
    model: 'claude-sonnet-4-6',
    cwd: process.cwd(),
    mcpServers: {
      weather: weatherServer,
    },
    allowedTools: ['mcp__weather__get_temperature'],
  },
})

The allowedTools value uses Claude Agent SDK MCP tool naming: mcp__<server name>__<tool name>.

Cursor Agent SDK

Use @mastra/cursor to register a Cursor SDK agent in Mastra while keeping Cursor-specific setup in Cursor SDK options.

Install Cursor packages

Install the Mastra package and the Cursor SDK peer dependency:

npm

npm install @mastra/cursor @cursor/sdk

pnpm

pnpm add @mastra/cursor @cursor/sdk

Yarn

yarn add @mastra/cursor @cursor/sdk

Bun

bun add @mastra/cursor @cursor/sdk

Set the Cursor SDK credential:

export CURSOR_API_KEY="..."

Create a Cursor SDK agent

Configure Cursor Agent SDK through sdkOptions.

src/mastra/agents/cursor-sdk-agent.ts

import { CursorSDKAgent } from '@mastra/cursor'

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  sdkOptions: {
    apiKey: process.env.CURSOR_API_KEY,
    model: {
      id: 'gpt-5.5',
    },
    local: {
      cwd: process.cwd(),
    },
  },
})

Cursor local agents require an explicit model. Set it in sdkOptions.model.

Use an existing Cursor SDK agent

If your app already creates a Cursor SDK agent, pass that agent to CursorSDKAgent instead:

src/mastra/agents/cursor-sdk-agent.ts

import { Agent as CursorAgent } from '@cursor/sdk'
import { CursorSDKAgent } from '@mastra/cursor'

const cursorAgent = CursorAgent.create({
  apiKey: process.env.CURSOR_API_KEY,
  model: {
    id: 'gpt-5.5',
  },
  local: {
    cwd: process.cwd(),
  },
})

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  agent: cursorAgent,
})

Add Cursor SDK tools

Cursor Agent SDK tools are configured with Cursor SDK options. Pass Model Context Protocol (MCP) servers through sdkOptions.mcpServers:

src/mastra/agents/cursor-sdk-agent.ts

import { CursorSDKAgent } from '@mastra/cursor'
import { mcpServers } from '../mcp/cursor'

export const cursorSDKAgent = new CursorSDKAgent({
  id: 'cursor-sdk-agent',
  name: 'Cursor SDK Agent',
  description: 'Use Cursor Agent SDK through Mastra.',
  sdkOptions: {
    apiKey: process.env.CURSOR_API_KEY,
    model: {
      id: 'gpt-5.5',
    },
    local: {
      cwd: process.cwd(),
    },
    mcpServers,
  },
})

Register SDK agents

Register SDK agents in the Mastra instance like other agents:

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { claudeSDKAgent } from './agents/claude-sdk-agent'
import { cursorSDKAgent } from './agents/cursor-sdk-agent'

export const mastra = new Mastra({
  agents: {
    claudeSDKAgent,
    cursorSDKAgent,
  },
})

After registration, call them with mastra.getAgentById():

src/mastra/run-sdk-agent.ts

import { mastra } from './index'

const agent = mastra.getAgentById('cursor-sdk-agent')
const stream = await agent.stream('Inspect this project and describe the test setup.')

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

Observability

SDK agents create Mastra agent and model spans for generate() and stream() calls. Mastra records SDK-provided usage, tool activity, and provider metadata when the vendor SDK exposes those events.

Claude SDK runs can include SDK-estimated cost from the Claude result message. Cursor SDK runs include token usage from Cursor interaction updates.

For storage and dashboard setup, see Observability.

Related

• Agents overview
• Tools
• Observability