> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 的 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

使用 `@mastra/cursor` 在 Mastra 中註冊 Cursor SDK Agent，同時將 Cursor 專屬設定保留在 Cursor SDK 選項中。

### 安裝 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 選項設定。透過 `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 的 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 繼續執行。若要依 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。當供應商 SDK 公開這些事件時，Mastra 會記錄 SDK 提供的用量、Tool 活動與 Provider metadata。

Claude SDK 執行可包含 Claude 結果訊息中的 SDK 預估成本。Cursor SDK 執行包含 Cursor 互動更新中的 token 用量。OpenAI SDK 執行則包含 OpenAI 執行狀態中的 token 用量。

如需儲存空間與儀表板設定，請參閱[可觀測性](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)。

## 相關內容

- [Agent 概觀](https://mastra.zisheng.pro/zh-TW/docs/agents/overview)
- [Tool](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)
- [可觀測性](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)