@mastra/core/dist/docs/references/docs-agents-sdk-agents.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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](#claude-agent-sdk): Use `@mastra/claude` to register a Claude SDK agent and call it with Mastra `generate()` and `stream()`.
- [Cursor Agent SDK](#cursor-agent-sdk): Use `@mastra/cursor` to register a Cursor SDK agent and call it with Mastra `generate()` and `stream()`.
- [OpenAI Agents SDK](#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**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

Set the Claude SDK credential:

```bash
export ANTHROPIC_API_KEY="..."
```

### Create a Claude SDK agent

Configure Claude Agent SDK through `sdkOptions`.

```typescript
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`.

```typescript
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**:

```bash
npm install @mastra/cursor @cursor/sdk
```

**pnpm**:

```bash
pnpm add @mastra/cursor @cursor/sdk
```

**Yarn**:

```bash
yarn add @mastra/cursor @cursor/sdk
```

**Bun**:

```bash
bun add @mastra/cursor @cursor/sdk
```

Set the Cursor SDK credential:

```bash
export CURSOR_API_KEY="..."
```

### Create a Cursor SDK agent

Configure Cursor Agent SDK through `sdkOptions`.

```typescript
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:

```typescript
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`:

```typescript
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**:

```bash
npm install @mastra/openai @openai/agents zod
```

**pnpm**:

```bash
pnpm add @mastra/openai @openai/agents zod
```

**Yarn**:

```bash
yarn add @mastra/openai @openai/agents zod
```

**Bun**:

```bash
bun add @mastra/openai @openai/agents zod
```

Set the OpenAI SDK credential:

```bash
export OPENAI_API_KEY="..."
```

### Create an OpenAI SDK agent

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

```typescript
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:

```typescript
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`.

```typescript
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:

```typescript
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()`:

```typescript
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`:

```typescript
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:

```typescript
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`.

```typescript
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](https://mastra.ai/docs/observability/overview).

## Related

- [Agents overview](https://mastra.ai/docs/agents/overview)
- [Tools](https://mastra.ai/docs/agents/using-tools)
- [Observability](https://mastra.ai/docs/observability/overview)