> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 API 金鑰：

```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 API 金鑰：

```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 API 金鑰：

```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 並未提供受結構描述約束的輸出 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-HK/docs/observability/overview)。

## 相關內容

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