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

# 핸들챗스트림()

AI SDK 호환 형식의 스트리밍 Agent 채팅을 위한 프레임워크에 구애받지 않는 핸들러입니다. Hono 또는 Mastra 외부에서 채팅 스트리밍을 처리해야 하는 경우 이 기능을 직접 사용하세요.[apiRoutes](https://mastra.zisheng.pro/ko/docs/server/custom-api-routes)특징.

`handleChatStream()`은 [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response)로 감쌀 수 있는 `ReadableStream`을 반환합니다. `handleChatStream()`기존 AI SDK v5/기본 동작을 유지합니다. 앱이 AI SDK v6에 대해 입력된 경우 다음을 통과하세요.`version: 'v6'`.

Mastra 서버 내에 채팅 경로를 만들려면 [`chatRoute()`](https://mastra.zisheng.pro/ko/reference/ai-sdk/chat-route)를 사용하세요.

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

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

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

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

## 사용예

Next.js 앱 라우터 예:

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

**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`): 스트림에서 시작 이벤트를 전송할지 여부입니다. (Default: `true`)

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

**sendReasoning** (`boolean`): 스트림에 추론 단계를 포함할지 여부입니다. (Default: `false`)

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

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

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