跳至主要內容

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 對等依賴套件：

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

設定 Claude SDK API 金鑰：

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 對等依賴套件：

npm install @mastra/cursor @cursor/sdk

設定 Cursor SDK API 金鑰：

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 對等依賴套件：

npm install @mastra/openai @openai/agents zod

設定 OpenAI SDK API 金鑰：

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 一樣，在 Mastra 實例中註冊 SDK Agent：

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 並未提供受結構描述約束的輸出 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 用量。

如需了解儲存及儀表板設定，請參閱可觀測性。

On this page