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().
• OpenAI Agents SDK: Use @mastra/openai to register an OpenAI 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',
    },
    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',
  },
  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',
    },
    local: {
      cwd: process.cwd(),
    },
    mcpServers,
  },
})

OpenAI Agents SDK

Use @mastra/openai to register an OpenAI Agents SDK agent in Mastra while keeping OpenAI-specific agent settings in OpenAI SDK options.

Install OpenAI packages

Install the Mastra package and the OpenAI Agents SDK peer dependency:

npm

npm install @mastra/openai @openai/agents zod

pnpm

pnpm add @mastra/openai @openai/agents zod

Yarn

yarn add @mastra/openai @openai/agents zod

Bun

bun add @mastra/openai @openai/agents zod

Set the OpenAI SDK credential:

export OPENAI_API_KEY="..."

Create an OpenAI SDK agent

Configure OpenAI Agents SDK through sdkOptions. OpenAISDKAgent creates the OpenAI SDK agent on first use.

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

import { OpenAISDKAgent } from '@mastra/openai'

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  sdkOptions: {
    name: 'Repository assistant',
    instructions: 'Answer clearly and cite the relevant files.',
    model: 'gpt-5',
  },
})

Use an existing OpenAI SDK agent

If your app already creates an OpenAI SDK agent, pass that agent to OpenAISDKAgent instead:

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

import { Agent as OpenAIAgent } from '@openai/agents'
import { OpenAISDKAgent } from '@mastra/openai'

const sdkAgent = new OpenAIAgent({
  name: 'Repository assistant',
  instructions: 'Answer clearly and cite the relevant files.',
  model: 'gpt-5',
})

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  agent: sdkAgent,
})

Add OpenAI SDK tools

OpenAI Agents SDK tools are configured with OpenAI SDK options. Create tools with the OpenAI SDK, then pass them through sdkOptions.tools.

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

import { tool } from '@openai/agents'
import { OpenAISDKAgent } from '@mastra/openai'
import { z } from 'zod'

const getTemperature = tool({
  name: 'get_temperature',
  description: 'Get the current temperature for a city.',
  parameters: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => {
    return `${city}: 27 C`
  },
})

export const openaiSDKAgent = new OpenAISDKAgent({
  id: 'openai-sdk-agent',
  name: 'OpenAI SDK Agent',
  description: 'Use OpenAI Agents SDK through Mastra.',
  sdkOptions: {
    name: 'Weather assistant',
    model: 'gpt-5',
    tools: [getTemperature],
  },
})

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'
import { openaiSDKAgent } from './agents/openai-sdk-agent'

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

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)
}

Resume SDK runs

SDK agents support Mastra resumeGenerate() and resumeStream() with provider-native resume data. Pass the message to continue with and the resume identifier used by the underlying SDK.

Claude SDK agents can resume a known session with sessionId:

src/mastra/resume-claude.ts

const result = await claudeSDKAgent.resumeGenerate({
  message: 'Continue the previous task.',
  sessionId: 'claude-session-id',
})

console.log(result.text)

OpenAI SDK agents can resume with a previous response, conversation, or session:

src/mastra/resume-openai.ts

const stream = await openaiSDKAgent.resumeStream({
  message: 'Continue the previous task.',
  previousResponseId: 'resp_123',
})

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

Cursor SDK agents can continue with the wrapped SDK agent. If you need to resume a stored Cursor SDK agent by ID, pass agentId in resumeData.

Structured output

Claude and OpenAI SDK agents support Mastra structuredOutput through their provider-native structured output APIs. The validated value is available on result.object.

src/mastra/run-openai-structured-output.ts

import { z } from 'zod'

const result = await openaiSDKAgent.generate<{ summary: string }>('Summarize this project.', {
  structuredOutput: {
    schema: z.object({
      summary: z.string(),
    }),
  },
})

console.log(result.object.summary)

Cursor SDK agents throw a clear error when structuredOutput is requested because the Cursor TypeScript SDK doesn't expose a schema-constrained output API.

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. OpenAI SDK runs include token usage from OpenAI run state.

For storage and dashboard setup, see Observability.

Related

• Agents overview
• Tools
• Observability