> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# SDK Agent

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

## SDK Agent를 사용하는 경우

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

## 지원되는 SDK Agent

- [Claude Agent SDK](#claude-agent-sdk): `@mastra/claude`를 사용해 Claude SDK Agent를 등록하고 Mastra의 `generate()` 및 `stream()`으로 호출합니다.
- [Cursor Agent SDK](#cursor-agent-sdk): `@mastra/cursor`를 사용해 Cursor SDK Agent를 등록하고 Mastra의 `generate()` 및 `stream()`으로 호출합니다.
- [OpenAI Agent SDK](#openai-agents-sdk): `@mastra/openai`를 사용해 OpenAI SDK Agent를 등록하고 Mastra의 `generate()` 및 `stream()`으로 호출합니다.

## 클로드 Agent SDK

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

### 클로드 패키지 설치

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
bun add @mastra/claude @anthropic-ai/claude-agent-sdk
```

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

```bash
export ANTHROPIC_API_KEY="..."
```

### Claude SDK Agent 만들기

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

```typescript
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 Agent SDK Tool은 Claude SDK MCP(Model Context Protocol) 서버를 통해 제공됩니다. Claude SDK로 서버를 생성한 후 해당 서버를 전달하세요.`sdkOptions.mcpServers`.

```typescript
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

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

### 커서 패키지 설치

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

**npm**:

```bash
npm install @mastra/cursor @cursor/sdk
```

**pnpm**:

```bash
pnpm add @mastra/cursor @cursor/sdk
```

**Yarn**:

```bash
yarn add @mastra/cursor @cursor/sdk
```

**Bun**:

```bash
bun add @mastra/cursor @cursor/sdk
```

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

```bash
export CURSOR_API_KEY="..."
```

### 커서 SDK Agent 만들기

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

```typescript
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를 생성한 경우 해당 Agent를`CursorSDKAgent` instead:

```typescript
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 추가

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

```typescript
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 설정을 OpenAI SDK 옵션에 유지하면서 Mastra에 OpenAI Agents SDK Agent를 등록하려면 `@mastra/openai`를 사용하세요.

### OpenAI 패키지 설치

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

**npm**:

```bash
npm install @mastra/openai @openai/agents zod
```

**pnpm**:

```bash
pnpm add @mastra/openai @openai/agents zod
```

**Yarn**:

```bash
yarn add @mastra/openai @openai/agents zod
```

**Bun**:

```bash
bun add @mastra/openai @openai/agents zod
```

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

```bash
export OPENAI_API_KEY="..."
```

### OpenAI SDK Agent 만들기

`sdkOptions`를 통해 OpenAI Agent SDK를 구성하세요. `OpenAISDKAgent`는 처음 사용할 때 OpenAI SDK Agent를 생성합니다.

```typescript
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를 생성한 경우 해당 Agent를`OpenAISDKAgent` instead:

```typescript
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 Agents SDK Tool은 OpenAI SDK 옵션으로 구성됩니다. OpenAI SDK로 Tool을 만든 후 전달하세요.`sdkOptions.tools`.

```typescript
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 등록

다른 Agent와 마찬가지로 Mastra 인스턴스에 SDK Agent를 등록합니다.

```typescript
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()`:

```typescript
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 Agent는 Provider 네이티브 재개 데이터와 함께 Mastra의 `resumeGenerate()` 및 `resumeStream()`을 지원합니다. 계속할 메시지와 기반 SDK에서 사용하는 재개 식별자를 전달하세요. Claude SDK Agent는 다음을 통해 알려진 세션을 재개할 수 있습니다.`sessionId`:

```typescript
const result = await claudeSDKAgent.resumeGenerate({
  message: 'Continue the previous task.',
  sessionId: 'claude-session-id',
})

console.log(result.text)
```

OpenAI SDK Agent는 이전 응답, 대화 또는 세션을 재개할 수 있습니다.

```typescript
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`에서 사용할 수 있습니다.

```typescript
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

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

저장소 및 대시보드 설정에 대해서는 다음을 참조하세요.[Observability](https://mastra.zisheng.pro/ko/docs/observability/overview).

## 관련된

- [Agent 개요](https://mastra.zisheng.pro/ko/docs/agents/overview)
- [Tool](https://mastra.zisheng.pro/ko/docs/agents/using-tools)
- [Observability](https://mastra.zisheng.pro/ko/docs/observability/overview)