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
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 对等依赖项：

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 对等依赖项：

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 一样在 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 没有公开受 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 用量。

有关存储和仪表板设置，请参阅可观测性。

何时使用 SDK Agent何时使用 SDK Agent的直接链接

支持的 SDK Agent支持的 SDK Agent的直接链接

Claude Agent SDKClaude Agent SDK的直接链接

安装 Claude 包安装 Claude 包的直接链接

创建 Claude SDK Agent创建 Claude SDK Agent的直接链接

添加 Claude SDK Tool添加 Claude SDK Tool的直接链接

Cursor Agent SDKCursor Agent SDK的直接链接

安装 Cursor 包安装 Cursor 包的直接链接

创建 Cursor SDK Agent创建 Cursor SDK Agent的直接链接

使用现有 Cursor SDK Agent使用现有 Cursor SDK Agent的直接链接

添加 Cursor SDK Tool添加 Cursor SDK Tool的直接链接

OpenAI Agents SDKOpenAI 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 运行的直接链接

结构化输出结构化输出的直接链接

可观测性可观测性的直接链接

相关内容相关内容的直接链接