본문으로 건너뛰기

toAISdkStream()

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

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

UI 스트림의 구조화된 출력
UI 스트림의 구조화된 출력에 대한 직접 링크

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

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

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

사용예
사용예에 대한 직접 링크

Next.js 앱 라우터 예:

app/api/chat/route.ts
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를 전달하세요. 자세한 내용은 문제 해결: 반복되는 어시스턴트 메시지를 참조하세요.

매개변수
매개변수에 대한 직접 링크

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

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

version?:

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

from:

'agent' | 'network' | 'workflow'
= 'agent'
변환 중인 Mastra 스트림의 타입입니다.

lastMessageId?:

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

sendStart?:

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

sendFinish?:

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

sendReasoning?:

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

sendSources?:

boolean
= false
(Agent 전용) 출력에 출처 인용을 포함할지 여부입니다.

includeTextStreamParts?:

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

messageMetadata?:

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

onError?:

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

예
예에 대한 직접 링크

Workflow 스트림 변환
Workflow 스트림 변환에 대한 직접 링크

app/api/workflow/route.ts
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,
  })
}

네트워크 스트림 변환
네트워크 스트림 변환에 대한 직접 링크

app/api/network/route.ts
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 스트림 변환
추론이 활성화된 Agent 스트림 변환에 대한 직접 링크

app/api/reasoning/route.ts
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 스트림 변환
AI SDK v6용 Agent 스트림 변환에 대한 직접 링크

app/api/chat-v6/route.ts
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
using-messagemetadata에 대한 직접 링크

app/api/chat-with-metadata/route.ts
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 형식으로 변환하려는 경우:

client-stream-to-ai-sdk.ts
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)
}
On this page