SDK Agent

SDK Agent 可讓你在 Mastra 中使用其他 Agent SDK 框架。你可以用它們在 Mastra 專案中註冊由 SDK 支援的 Agent，同時讓 Provider SDK 保有自己的執行環境、Tool、權限與 Agent 迴圈。

適合使用 SDK Agent 的時機
「適合使用 SDK Agent 的時機」的直接連結

供應商 SDK 已經管理 Agent 迴圈、Tool、權限或本機執行環境。
你想在 Mastra 專案中註冊該 SDK 支援的 Agent。
你需要與 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」的直接連結

使用 @mastra/claude 設定 Claude Code 執行環境、權限、Tool 與 Agent 迴圈行為。

安裝 Claude 套件
「安裝 Claude 套件」的直接連結

安裝 Mastra 套件與 Claude Agent SDK 的 peer dependency：

npm
pnpm
Yarn
Bun

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

pnpm add @mastra/claude @anthropic-ai/claude-agent-sdk

yarn add @mastra/claude @anthropic-ai/claude-agent-sdk

bun add @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」的直接連結

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

安裝 Cursor 套件
「安裝 Cursor 套件」的直接連結

安裝 Mastra 套件與 Cursor SDK 的 peer dependency：

npm
pnpm
Yarn
Bun

npm install @mastra/cursor @cursor/sdk

pnpm add @mastra/cursor @cursor/sdk

yarn add @mastra/cursor @cursor/sdk

bun add @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 選項設定。透過 sdkOptions.mcpServers 傳入 Model Context Protocol（MCP）伺服器：

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」的直接連結

使用 @mastra/openai 在 Mastra 中註冊 OpenAI Agents SDK Agent，同時將 OpenAI 專屬的 Agent 設定保留在 OpenAI SDK 選項中。

安裝 OpenAI 套件
「安裝 OpenAI 套件」的直接連結

安裝 Mastra 套件與 OpenAI Agents SDK 的 peer dependency：

npm
pnpm
Yarn
Bun

npm install @mastra/openai @openai/agents zod

pnpm add @mastra/openai @openai/agents zod

yarn add @mastra/openai @openai/agents zod

bun add @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 繼續執行。若要依 ID 繼續已儲存的 Cursor SDK Agent，請在 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)

要求 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 用量。

如需儲存空間與儀表板設定，請參閱可觀測性。

適合使用 SDK Agent 的時機「適合使用 SDK Agent 的時機」的直接連結

支援的 SDK Agent「支援的 SDK Agent」的直接連結

Claude Agent SDK「Claude Agent SDK」的直接連結

安裝 Claude 套件「安裝 Claude 套件」的直接連結

建立 Claude SDK Agent「建立 Claude SDK Agent」的直接連結

新增 Claude SDK Tool「新增 Claude SDK Tool」的直接連結

Cursor Agent SDK「Cursor Agent SDK」的直接連結

安裝 Cursor 套件「安裝 Cursor 套件」的直接連結

建立 Cursor SDK Agent「建立 Cursor SDK Agent」的直接連結

使用現有的 Cursor SDK Agent「使用現有的 Cursor SDK Agent」的直接連結

新增 Cursor SDK Tool「新增 Cursor SDK Tool」的直接連結

OpenAI Agents SDK「OpenAI Agents SDK」的直接連結

安裝 OpenAI 套件「安裝 OpenAI 套件」的直接連結

建立 OpenAI SDK Agent「建立 OpenAI SDK Agent」的直接連結

使用現有的 OpenAI SDK Agent「使用現有的 OpenAI SDK Agent」的直接連結

新增 OpenAI SDK Tool「新增 OpenAI SDK Tool」的直接連結

註冊 SDK Agent「註冊 SDK Agent」的直接連結

繼續 SDK 執行「繼續 SDK 執行」的直接連結

結構化輸出「結構化輸出」的直接連結

可觀測性「可觀測性」的直接連結

相關內容「相關內容」的直接連結