본문으로 건너뛰기

SDK Agent

SDK Agent를 사용하면 Mastra 내에서 다른 Agent SDK 프레임워크를 사용할 수 있습니다. 공급자 SDK가 자체 런타임, Tool, 권한 및 Agent 루프를 유지하는 동안 이를 사용하여 Mastra 프로젝트에 SDK 지원 Agent를 등록합니다.

SDK Agent를 사용하는 경우
SDK Agent를 사용하는 경우에 대한 직접 링크

  • 공급업체 SDK가 이미 Agent 루프, Tool, 권한 또는 로컬 런타임을 소유하고 있습니다.
  • 해당 SDK 기반 Agent를 Mastra 프로젝트에 등록하려고 합니다.
  • Mastra 호환 generate() 및 stream() 출력이 필요합니다.
  • SDK 실행의 사용량, 비용 및 Tool 활동을 Mastra Observability에서 확인하려고 합니다.

지원되는 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 Agent SDK: @mastra/openai를 사용해 OpenAI SDK Agent를 등록하고 Mastra의 generate() 및 stream()으로 호출합니다.

클로드 Agent SDK
클로드 Agent SDK에 대한 직접 링크

Claude Code 런타임 구성, 권한, Tool 및 Agent 루프 동작에는 @mastra/claude를 사용하세요.

클로드 패키지 설치
클로드 패키지 설치에 대한 직접 링크

Mastra 패키지와 Claude Agent SDK 피어 종속성을 설치합니다.

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

Claude SDK 자격 증명을 설정합니다.

export ANTHROPIC_API_KEY="..."

Claude SDK Agent 만들기
Claude SDK Agent 만들기에 대한 직접 링크

Claude Agent SDK를 다음을 통해 구성하세요.sdkOptions.

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 MCP(Model Context Protocol) 서버를 통해 제공됩니다. 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>을 사용합니다.

커서 Agent SDK
커서 Agent SDK에 대한 직접 링크

Cursor 관련 설정은 Cursor SDK 옵션에 유지하면서 Mastra에 Cursor SDK Agent를 등록하려면 @mastra/cursor를 사용하세요.

커서 패키지 설치
커서 패키지 설치에 대한 직접 링크

Mastra 패키지와 Cursor SDK 피어 종속성을 설치합니다.

npm install @mastra/cursor @cursor/sdk

커서 SDK 자격 증명을 설정합니다.

export CURSOR_API_KEY="..."

커서 SDK Agent 만들기
커서 SDK Agent 만들기에 대한 직접 링크

다음을 통해 커서 Agent SDK를 구성합니다.sdkOptions.

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(),
    },
  },
})

커서 로컬 Agent에는 명시적 Model이 필요합니다. 설정하세요sdkOptions.model.

기존 Cursor SDK Agent 사용
기존 Cursor SDK Agent 사용에 대한 직접 링크

앱이 이미 Cursor SDK Agent를 생성한 경우 해당 Agent를CursorSDKAgent instead:

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,
})

커서 SDK Tool 추가
커서 SDK Tool 추가에 대한 직접 링크

커서 Agent SDK Tool은 커서 SDK 옵션으로 구성됩니다. MCP(Model Context Protocol) 서버를 다음을 통해 전달합니다.sdkOptions.mcpServers:

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 Agent SDK
OpenAI Agent SDK에 대한 직접 링크

OpenAI 관련 Agent 설정을 OpenAI SDK 옵션에 유지하면서 Mastra에 OpenAI Agents SDK Agent를 등록하려면 @mastra/openai를 사용하세요.

OpenAI 패키지 설치
OpenAI 패키지 설치에 대한 직접 링크

Mastra 패키지와 OpenAI Agents SDK 피어 종속성을 설치합니다.

npm install @mastra/openai @openai/agents zod

OpenAI SDK 자격 증명을 설정합니다.

export OPENAI_API_KEY="..."

OpenAI SDK Agent 만들기
OpenAI SDK Agent 만들기에 대한 직접 링크

sdkOptions를 통해 OpenAI Agent 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 instead:

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를 계속 사용할 수 있습니다. 저장된 Cursor SDK Agent를 ID로 재개해야 한다면 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)

Cursor TypeScript SDK는 스키마로 제한된 출력 API를 제공하지 않으므로 Cursor SDK Agent에서 structuredOutput을 요청하면 명확한 오류가 발생합니다.

Observability
Observability에 대한 직접 링크

SDK Agent는 generate() 및 stream() 호출을 위한 Mastra Agent 및 Model 범위를 생성합니다. 공급업체 SDK에서 관련 이벤트를 제공하면 Mastra는 SDK가 제공한 사용량, Tool 활동 및 Provider 메타데이터를 기록합니다. Claude SDK 실행에는 Claude 결과 메시지의 SDK 추정 비용이 포함될 수 있습니다. Cursor SDK 실행에는 Cursor 상호 작용 업데이트의 토큰 사용이 포함됩니다. OpenAI SDK 실행에는 OpenAI 실행 상태의 토큰 사용이 포함됩니다.

저장소 및 대시보드 설정에 대해서는 다음을 참조하세요.Observability.

On this page