본문으로 건너뛰기

핸들챗스트림()

AI SDK 호환 형식의 스트리밍 Agent 채팅을 위한 프레임워크에 구애받지 않는 핸들러입니다. Hono 또는 Mastra 외부에서 채팅 스트리밍을 처리해야 하는 경우 이 기능을 직접 사용하세요.apiRoutes특징.

handleChatStream()은 createUIMessageStreamResponse()로 감쌀 수 있는 ReadableStream을 반환합니다. handleChatStream()기존 AI SDK v5/기본 동작을 유지합니다. 앱이 AI SDK v6에 대해 입력된 경우 다음을 통과하세요.version: 'v6'.

Mastra 서버 내에 채팅 경로를 만들려면 chatRoute()를 사용하세요.

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

기본 Agent 실행에 structuredOutput을 전달하면 최종 구조화 출력 객체가 AI SDK 호환 UI 스트림에서 사용자 지정 데이터 부분으로 내보내집니다.

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

object 필드에는 전체 구조화 출력 값이 포함됩니다. Mastra는 최종 구조화 출력 객체에 대해서만 이 이벤트를 내보냅니다. 부분 구조화 출력 청크는 UI 스트림에 노출되지 않습니다. onData와 같은 AI SDK UI의 사용자 지정 데이터 처리를 통해 이 이벤트를 읽거나 메시지 데이터 부분에서 렌더링하세요.

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

Next.js 앱 라우터 예:

app/api/chat/route.ts
import { handleChatStream } from '@mastra/ai-sdk'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/src/mastra'

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weatherAgent',
    params,
    messageMetadata: () => ({ createdAt: new Date().toISOString() }),
  })
  return createUIMessageStreamResponse({ stream })
}

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

version?:

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

mastra:

Mastra
등록된 Agent를 포함하는 Mastra 인스턴스입니다.

agentId:

string
채팅에 사용할 Agent의 ID입니다.

agentVersion?:

{ versionId: string } | { status?: 'draft' | 'published' }
특정 Agent 버전을 선택합니다. 정확한 버전을 대상으로 지정하려면 { versionId: '<id>' }를 전달하고, 상태로 확인하려면 { status: 'draft' } / { status: 'published' }를 전달하세요. Editor가 구성되어 있어야 합니다.

params:

ChatStreamHandlerParams
메시지와 선택적 재개 데이터를 포함하는 채팅 스트림 매개변수입니다.

params.messages:

UIMessage[]
대화의 메시지 배열입니다.

params.resumeData?:

Record<string, any>
일시 중단된 Agent 실행을 재개하기 위한 데이터입니다. runId를 설정해야 합니다.

params.runId?:

string
실행 ID입니다. resumeData가 제공된 경우 필수입니다.

params.providerOptions?:

Record<string, Record<string, unknown>>
언어 Model에 전달되는 Provider별 옵션입니다(예: { openai: { reasoningEffort: "high" } }). defaultOptions.providerOptions와 병합되며 params가 우선합니다.

params.requestContext?:

RequestContext
Agent 실행에 전달할 요청 컨텍스트입니다.

defaultOptions?:

AgentExecutionOptions
Agent 실행에 전달되는 기본 옵션입니다. params와 병합되며 params가 우선합니다.

sendStart?:

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

sendFinish?:

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

sendReasoning?:

boolean
= false
스트림에 추론 단계를 포함할지 여부입니다.

sendSources?:

boolean
= false
스트림에 출처 인용을 포함할지 여부입니다.

onError?:

(error: unknown) => string
스트림에서 오류가 발생할 때 호출됩니다. 오류 메시지로 클라이언트에 전송할 문자열을 반환하세요. 내부 인프라 세부 정보가 최종 사용자에게 유출되지 않도록 하는 등, 오류가 클라이언트에 도달하기 전에 정제하는 데 사용합니다.

messageMetadata?:

(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined
현재 스트림 부분을 받아 시작 및 완료 청크에 첨부할 메타데이터를 반환하는 함수입니다. 자세한 내용은 AI SDK 메시지 메타데이터 문서를 참고하세요.
On this page