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

# toAISdkStream()

Mastra 스트림(Agent, 네트워크 또는 Workflow)을 AI SDK 호환 스트림으로 변환합니다. AI SDK와 함께 사용하기 위해 Mastra 스트림을 수동으로 변환해야 할 때 이 기능을 사용하십시오.`createUIMessageStream()`그리고`createUIMessageStreamResponse()`.

이는 [`chatRoute()`](https://mastra.zisheng.pro/ko/reference/ai-sdk/chat-route) 또는 [`workflowRoute()`](https://mastra.zisheng.pro/ko/reference/ai-sdk/workflow-route)처럼 Mastra가 제공하는 경로 헬퍼 외부에서 사용자 정의 스트리밍 엔드포인트를 구축할 때 유용합니다. `toAISdkStream()`은 기존 AI SDK v5/기본 동작을 유지합니다. 앱이 AI SDK v6을 기준으로 타입이 지정된 경우 옵션 객체에 `version: 'v6'`을 전달하세요.

## UI 스트림의 구조화된 출력

소스 Agent 스트림에 구조화된 최종 출력 객체가 포함된 경우 `toAISdkStream()`은 이를 사용자 정의 AI SDK UI 데이터 부분으로 내보냅니다.

```json
{
  "type": "data-structured-output",
  "data": {
    "object": {}
  }
}
```

`object` 필드에는 전체 구조화 출력 값이 포함됩니다. 이는 Mastra의 최종 구조화 출력 청크를 AI SDK UI 스트림에 매핑합니다. 부분 구조화 출력 청크는 내보내지 않습니다.

## 사용예

Next.js 앱 라우터 예:

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'agent' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

> **팁:** UI에서 어시스턴트 메시지가 중복되지 않도록 `createUIMessageStream()`의 `originalMessages`에 `messages`를 전달하세요. 자세한 내용은 [문제 해결: 반복되는 어시스턴트 메시지](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages)를 참조하세요.

## 매개변수

첫 번째 매개변수는 변환할 Mastra 스트림입니다. 다음 중 하나일 수 있습니다.

- `MastraModelOutput` - `agent.stream()`의 Agent 스트림
- `MastraAgentNetworkStream` - `agent.network()`의 네트워크 스트림
- `MastraWorkflowStream` 또는 `WorkflowRunOutput` - Workflow 스트림 두 번째 매개변수는 옵션 객체입니다:

**version** (`'v5' | 'v6'`): 출력할 AI SDK 스트림 계약을 선택합니다. 기존 기본 동작을 사용하려면 생략하거나 'v5'를 전달하세요. 앱이 AI SDK v6 응답 헬퍼를 기준으로 타입이 지정된 경우 'v6'을 전달하세요. (Default: `'v5'`)

**from** (`'agent' | 'network' | 'workflow'`): 변환 중인 Mastra 스트림의 타입입니다. (Default: `'agent'`)

**lastMessageId** (`string`): (Agent 전용) 대화의 마지막 메시지 ID입니다.

**sendStart** (`boolean`): (Agent 전용) 스트림에서 시작 이벤트를 전송할지 여부입니다. (Default: `true`)

**sendFinish** (`boolean`): (Agent 전용) 스트림에서 완료 이벤트를 전송할지 여부입니다. (Default: `true`)

**sendReasoning** (`boolean`): (Agent 전용) 스트림에 reasoning-delta 청크를 포함할지 여부입니다. 확장 사고를 지원하는 Model의 추론 콘텐츠를 스트리밍하려면 true로 설정하세요. (Default: `false`)

**sendSources** (`boolean`): (Agent 전용) 출력에 출처 인용을 포함할지 여부입니다. (Default: `false`)

**includeTextStreamParts** (`boolean`): (Workflow 전용) 출력에 텍스트 스트림 부분을 포함할지 여부입니다. (Default: `true`)

**messageMetadata** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): (Agent 전용) 현재 스트림 부분을 수신하고 시작 및 완료 청크에 첨부할 메타데이터를 반환하는 함수입니다.

**onError** (`(error: unknown) => string`): (Agent 전용) 스트림 변환 중 오류를 처리하는 함수입니다. 오류를 수신하고 문자열 표현을 반환해야 합니다.

## 예

### Workflow 스트림 변환

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { input } = await req.json()
  const workflow = mastra.getWorkflow('myWorkflow')
  const run = workflow.createRun()
  const stream = await run.stream({ inputData: input })

  const uiMessageStream = createUIMessageStream({
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'workflow' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

### 네트워크 스트림 변환

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const routingAgent = mastra.getAgent('routingAgent')
  const stream = await routingAgent.network(messages)

  const uiMessageStream = createUIMessageStream({
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, { from: 'network' })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

### 추론이 활성화된 Agent 스트림 변환

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const reasoningAgent = mastra.getAgent('reasoningAgent')
  const stream = await reasoningAgent.stream(messages, {
    providerOptions: {
      openai: { reasoningEffort: 'high' },
    },
  })

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        sendReasoning: true,
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

### AI SDK v6용 Agent 스트림 변환

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        version: 'v6',
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

### 사용`messageMetadata`

```typescript
import { mastra } from '../../mastra'
import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const myAgent = mastra.getAgent('weatherAgent')
  const stream = await myAgent.stream(messages)

  const uiMessageStream = createUIMessageStream({
    originalMessages: messages,
    execute: async ({ writer }) => {
      for await (const part of toAISdkStream(stream, {
        from: 'agent',
        messageMetadata: ({ part }) => ({
          timestamp: Date.now(),
          partType: part.type,
        }),
      })) {
        await writer.write(part)
      }
    },
  })

  return createUIMessageStreamResponse({
    stream: uiMessageStream,
  })
}
```

### 클라이언트 측 스트림 변환

클라이언트 측에서 Mastra 클라이언트 SDK(`@mastra/client-js`)를 사용하며 스트림을 AI SDK 형식으로 변환하려는 경우:

```typescript
import { MastraClient } from '@mastra/client-js'
import { createUIMessageStream } from 'ai'
import { toAISdkStream } from '@mastra/ai-sdk'
import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const agent = client.getAgent('weatherAgent')
const response = await agent.stream('What is the weather in Tokyo?')

// Convert the client SDK stream to a ReadableStream<ChunkType>
const chunkStream = new ReadableStream<ChunkType>({
  async start(controller) {
    await response.processDataStream({
      onChunk: async chunk => {
        controller.enqueue(chunk)
      },
    })
    controller.close()
  },
})

// Transform to AI SDK format
const uiMessageStream = createUIMessageStream({
  execute: async ({ writer }) => {
    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
      from: 'agent',
    })) {
      await writer.write(part)
    }
  },
})

for await (const part of uiMessageStream) {
  console.log(part)
}
```