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

# SDK Agent

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

## SDK Agent を使用する場面

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

## サポートされる SDK Agent

- [Claude Agent SDK](#claude-agent-sdk): `@mastra/claude` で Claude SDK Agent を登録し、Mastra の `generate()` と `stream()` から呼び出します。
- [Cursor Agent SDK](#cursor-agent-sdk): `@mastra/cursor` で Cursor SDK Agent を登録し、Mastra の `generate()` と `stream()` から呼び出します。
- [OpenAI Agents SDK](#openai-agents-sdk): `@mastra/openai` で OpenAI SDK Agent を登録し、Mastra の `generate()` と `stream()` から呼び出します。

## Claude Agent SDK

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

### Claude パッケージをインストールする

Mastra パッケージと 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
```

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

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

### Claude SDK Agent を作成する

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

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

### Claude SDK Tool を追加する

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

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

## Cursor Agent SDK

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

### Cursor パッケージをインストールする

Mastra パッケージと 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
```

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

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

### Cursor SDK Agent を作成する

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

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

### 既存の Cursor SDK Agent を使用する

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

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

### Cursor SDK Tool を追加する

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

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

### OpenAI パッケージをインストールする

Mastra パッケージと 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
```

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

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

### OpenAI SDK Agent を作成する

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

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

### 既存の OpenAI SDK Agent を使用する

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

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

### OpenAI SDK Tool を追加する

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

## SDK Agent を登録する

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

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

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

## SDK の実行を再開する

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

Claude SDK Agent は `sessionId` で既知のセッションを再開できます。

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

console.log(result.text)
```

OpenAI SDK Agent は、以前のレスポンス、会話、セッションから再開できます。

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

## 構造化出力

Claude と OpenAI の SDK Agent は、Provider ネイティブの構造化出力 API を通じて Mastra の `structuredOutput` をサポートしています。検証済みの値は `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 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 のトークン使用量が含まれます。

ストレージとダッシュボードの設定については、[可観測性](https://mastra.zisheng.pro/ja/docs/observability/overview)を参照してください。

## 関連情報

- [Agent の概要](https://mastra.zisheng.pro/ja/docs/agents/overview)
- [Tool](https://mastra.zisheng.pro/ja/docs/agents/using-tools)
- [可観測性](https://mastra.zisheng.pro/ja/docs/observability/overview)