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

# SDK Agent

SDK Agent 让你可以在 Mastra 中使用其他 Agent SDK 框架。使用它们可在 Mastra 项目中注册由 SDK 支持的 Agent，同时由 Provider SDK 保持自己的运行时、Tool、权限和 Agent 循环。

## 何时使用 SDK Agent

- 厂商 SDK 已经负责 Agent 循环、Tool、权限或本地运行时。
- 你希望在 Mastra 项目中注册由该 SDK 支持的 Agent。
- 你需要与 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

使用 `@mastra/claude` 配置 Claude Code 运行时、权限、Tool 和 Agent 循环行为。

### 安装 Claude 包

安装 Mastra 包和 Claude Agent SDK 对等依赖项：

**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

使用 `@mastra/cursor` 在 Mastra 中注册 Cursor SDK Agent，同时将 Cursor 专用设置保留在 Cursor SDK 选项中。

### 安装 Cursor 包

安装 Mastra 包和 Cursor SDK 对等依赖项：

**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 选项配置。通过 `sdkOptions.mcpServers` 传入 Model Context Protocol（MCP）服务器：

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

使用 `@mastra/openai` 在 Mastra 中注册 OpenAI Agents SDK Agent，同时将 OpenAI 专用 Agent 设置保留在 OpenAI SDK 选项中。

### 安装 OpenAI 包

安装 Mastra 包和 OpenAI Agents SDK 对等依赖项：

**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 一样在 Mastra 实例中注册 SDK Agent：

```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 继续。如果需要按 ID 恢复已存储的 Cursor SDK Agent，请在 `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)
```

请求 `structuredOutput` 时，Cursor SDK Agent 会抛出明确错误，因为 Cursor TypeScript SDK 没有公开受 schema 约束的输出 API。

## 可观测性

SDK Agent 会为 `generate()` 和 `stream()` 调用创建 Mastra Agent span 和模型 span。当厂商 SDK 公开相关事件时，Mastra 会记录 SDK 提供的用量、Tool 活动和 Provider 元数据。

Claude SDK 运行可包含 Claude 结果消息中的 SDK 估算成本。Cursor SDK 运行包含 Cursor 交互更新中的 token 用量。OpenAI SDK 运行包含 OpenAI 运行状态中的 token 用量。

有关存储和仪表板设置，请参阅[可观测性](https://mastra.zisheng.pro/docs/observability/overview)。

## 相关内容

- [Agent 概览](https://mastra.zisheng.pro/docs/agents/overview)
- [Tool](https://mastra.zisheng.pro/docs/agents/using-tools)
- [可观测性](https://mastra.zisheng.pro/docs/observability/overview)