メインコンテンツへ移動

SDK Agent

SDK Agent を使うと、Mastra 内で別の Agent SDK フレームワークを利用できます。Provider SDK が独自のランタイム、Tool、権限、Agent ループを維持したまま、SDK ベースの Agent を Mastra プロジェクトに登録できます。

SDK Agent を使用する場面
SDK Agent を使用する場面への直接リンク

  • ベンダー SDK が Agent ループ、Tool、権限、ローカルランタイムをすでに管理している場合。
  • SDK ベースの Agent を Mastra プロジェクトに登録したい場合。
  • Mastra 互換の generate() と stream() の出力が必要な場合。
  • SDK の実行による使用量、コスト、Tool のアクティビティを Mastra の可観測性に表示したい場合。

サポートされる SDK Agent
サポートされる SDK Agentへの直接リンク

  • Claude Agent SDK: @mastra/claude で Claude SDK Agent を登録し、Mastra の generate() と stream() から呼び出します。
  • Cursor Agent SDK: @mastra/cursor で Cursor SDK Agent を登録し、Mastra の generate() と stream() から呼び出します。
  • OpenAI Agents SDK: @mastra/openai で OpenAI SDK Agent を登録し、Mastra の generate() と stream() から呼び出します。

Claude Agent SDK
Claude Agent SDKへの直接リンク

Claude Code のランタイム設定、権限、Tool、Agent ループの動作には @mastra/claude を使用します。

Claude パッケージをインストールする
Claude パッケージをインストールするへの直接リンク

Mastra パッケージと Claude Agent SDK の peer dependency をインストールします。

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

Claude SDK の認証情報を設定します。

export ANTHROPIC_API_KEY="..."

Claude SDK Agent を作成する
Claude SDK Agent を作成するへの直接リンク

sdkOptions で Claude Agent SDK を設定します。

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

Claude SDK Tool を追加する
Claude SDK Tool を追加するへの直接リンク

Claude Agent SDK の Tool は、Claude SDK Model Context Protocol (MCP) サーバーを通じて提供されます。Claude SDK でサーバーを作成し、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'],
  },
})

allowedTools の値には、Claude Agent SDK MCP の Tool 命名規則である mcp__<server name>__<tool name> を使用します。

Cursor Agent SDK
Cursor Agent SDKへの直接リンク

Cursor 固有の設定を Cursor SDK オプションに保持したまま、Mastra に Cursor SDK Agent を登録するには @mastra/cursor を使用します。

Cursor パッケージをインストールする
Cursor パッケージをインストールするへの直接リンク

Mastra パッケージと Cursor SDK の peer dependency をインストールします。

npm install @mastra/cursor @cursor/sdk

Cursor SDK の認証情報を設定します。

export CURSOR_API_KEY="..."

Cursor SDK Agent を作成する
Cursor SDK Agent を作成するへの直接リンク

sdkOptions で Cursor Agent SDK を設定します。

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 のローカル Agent には明示的なモデルが必要です。sdkOptions.model で設定してください。

既存の Cursor SDK Agent を使用する
既存の Cursor SDK Agent を使用するへの直接リンク

アプリですでに Cursor SDK Agent を作成している場合は、その Agent を CursorSDKAgent に渡します。

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

Cursor SDK Tool を追加する
Cursor SDK Tool を追加するへの直接リンク

Cursor Agent SDK の Tool は Cursor SDK オプションで設定します。Model Context Protocol (MCP) サーバーを 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
OpenAI Agents SDKへの直接リンク

OpenAI 固有の Agent 設定を OpenAI SDK オプションに保持したまま、Mastra に OpenAI Agents SDK Agent を登録するには @mastra/openai を使用します。

OpenAI パッケージをインストールする
OpenAI パッケージをインストールするへの直接リンク

Mastra パッケージと OpenAI Agents SDK の peer dependency をインストールします。

npm install @mastra/openai @openai/agents zod

OpenAI SDK の認証情報を設定します。

export OPENAI_API_KEY="..."

OpenAI SDK Agent を作成する
OpenAI SDK Agent を作成するへの直接リンク

sdkOptions で OpenAI Agents SDK を設定します。OpenAISDKAgent は初回使用時に OpenAI SDK Agent を作成します。

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

既存の OpenAI SDK Agent を使用する
既存の OpenAI SDK Agent を使用するへの直接リンク

アプリですでに OpenAI SDK Agent を作成している場合は、その Agent を OpenAISDKAgent に渡します。

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

OpenAI SDK Tool を追加する
OpenAI SDK Tool を追加するへの直接リンク

OpenAI Agents SDK の Tool は OpenAI SDK オプションで設定します。OpenAI SDK で Tool を作成し、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],
  },
})

SDK Agent を登録する
SDK Agent を登録するへの直接リンク

ほかの Agent と同じように、SDK Agent を Mastra インスタンスに登録します。

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

登録後は 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)
}

SDK の実行を再開する
SDK の実行を再開するへの直接リンク

SDK Agent は、Provider ネイティブの再開データを使用する Mastra の resumeGenerate() と resumeStream() をサポートしています。処理を続行するメッセージと、基盤となる SDK が使用する再開識別子を渡します。

Claude SDK Agent は 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 Agent は、以前のレスポンス、会話、セッションから再開できます。

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 Agent はラップされた SDK Agent で処理を続行できます。保存済みの Cursor SDK Agent を ID で再開する場合は、resumeData に agentId を渡します。

構造化出力
構造化出力への直接リンク

Claude と OpenAI の SDK Agent は、Provider ネイティブの構造化出力 API を通じて Mastra の structuredOutput をサポートしています。検証済みの値は 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 TypeScript SDK はスキーマ制約付きの出力 API を公開していないため、structuredOutput を要求すると Cursor SDK Agent は明確なエラーをスローします。

可観測性
可観測性への直接リンク

SDK Agent は generate() と stream() の呼び出しに対して Mastra の Agent span と model span を作成します。ベンダー SDK が該当イベントを公開している場合、Mastra は SDK が提供する使用量、Tool のアクティビティ、Provider のメタデータを記録します。

Claude SDK の実行には、Claude の結果メッセージから SDK が見積もったコストを含められます。Cursor SDK の実行には Cursor interaction update のトークン使用量が含まれます。OpenAI SDK の実行には OpenAI run state のトークン使用量が含まれます。

ストレージとダッシュボードの設定については、可観測性を参照してください。

On this page