SDK agents

SDK agents 让你在 Mastra 中使用其他 agent SDK 框架。使用它们可以在 Mastra 项目中注册由 SDK 支持的 agents，同时提供方 SDK 保留自己的运行时、tools、权限和 agent 循环。

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

供应商 SDK 已经拥有 agent 循环、tools、权限或本地运行时。
你希望在 Mastra 项目中注册该由 SDK 支持的 agent。
你需要 Mastra 兼容的 generate() 和 stream() 输出。
你希望 SDK 运行的使用量、成本和 tool 活动出现在 Mastra 可观测性中。

支持的 SDK agents
支持的 SDK agents的直接链接

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() 调用它。

没有专门 Mastra 包的 coding agents（例如 Cline 和 OpenCode）改为通过 Agent Client Protocol 运行。

Claude Agent SDK
Claude Agent SDK的直接链接

使用 @mastra/claude 进行 Claude Code 运行时配置、权限、tools 和 agent 循环行为。

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

安装 Mastra 包和 Claude Agent SDK peer 依赖：

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 tools
添加 Claude SDK tools的直接链接

Claude Agent SDK tools 通过 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 依赖：

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 本地 agents 需要显式模型。请在 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 tools
添加 Cursor SDK tools的直接链接

Cursor Agent SDK tools 通过 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 依赖：

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 tools
添加 OpenAI SDK tools的直接链接

OpenAI Agents SDK tools 通过 OpenAI SDK 选项配置。使用 OpenAI SDK 创建 tools，然后通过 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 agents
注册 SDK agents的直接链接

像其他 agents 一样在 Mastra 实例中注册 SDK agents：

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 agents 支持 Mastra 的 resumeGenerate() 和 resumeStream()，并使用提供方原生的恢复数据。传入要继续的消息以及底层 SDK 使用的恢复标识符。

Claude SDK agents 可以使用 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 agents 可以使用之前的 response、conversation 或 session 恢复：

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 agents 可以使用被包装的 SDK agent 继续。如果你需要按 ID 恢复已存储的 Cursor SDK agent，请在 resumeData 中传入 agentId。

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

Claude 和 OpenAI SDK agents 通过其提供方原生的结构化输出 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 agents 会抛出一个明确的错误，因为 Cursor TypeScript SDK 不提供受 schema 约束的输出 API。

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

SDK agents 会为 generate() 和 stream() 调用创建 Mastra agent 和模型 spans。当供应商 SDK 暴露这些事件时，Mastra 会记录 SDK 提供使用量、tool 活动和提供方 metadata。

Claude SDK 运行可以包含来自 Claude 结果消息的 SDK 估算成本。Cursor SDK 运行包含来自 Cursor 交互更新的 token 使用量。OpenAI SDK 运行包含来自 OpenAI 运行状态的 token 使用量。

关于存储和仪表盘设置，参见可观测性。

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

支持的 SDK agents支持的 SDK agents的直接链接

Claude Agent SDKClaude Agent SDK的直接链接

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

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

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

Cursor Agent SDKCursor Agent SDK的直接链接

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

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

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

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

OpenAI Agents SDKOpenAI Agents SDK的直接链接

安装 OpenAI 包安装 OpenAI 包的直接链接

创建 OpenAI SDK agent创建 OpenAI SDK agent的直接链接

使用现有的 OpenAI SDK agent使用现有的 OpenAI SDK agent的直接链接

添加 OpenAI SDK tools添加 OpenAI SDK tools的直接链接

注册 SDK agents注册 SDK agents的直接链接

恢复 SDK 运行恢复 SDK 运行的直接链接

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

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

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