Vercel AI SDK로 스트리밍 채팅 UI 만들기: 상태·중단·오류 처리

LLM 응답을 한 번에 기다렸다가 보여 주면 사용자는 수 초 동안 빈 화면을 본다. 토큰 단위로 흘려보내는 스트리밍 UI가 표준이 된 이유다. 다만 스트리밍 UI는 "로딩 중" 하나로 끝나지 않는다. 요청을 보낸 직후, 응답이 흐르는 중, 끝난 뒤, 실패했을 때 각각 다른 UI가 필요하고, 사용자가 중간에 멈출 수도 있어야 한다. 이 글은 AI SDK의 useChat 문서를 바탕으로 Next.js에서 이 상태들을 다루는 방법을 정리한다. 토큰 비용과 호출 제한 설계는 AI API 비용과 Rate Limit 설계 글에서 다뤘다.

1단계: Route Handler에서 스트리밍 응답 만들기

// app/api/chat/route.ts
import {
  convertToModelMessages,
  createUIMessageStreamResponse,
  streamText,
  toUIMessageStream,
  type UIMessage,
} from 'ai'

export const maxDuration = 30

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json()

  const result = streamText({
    model: 'anthropic/claude-sonnet-5.5',
    instructions: '사내 개발 문서에 대해 간결하게 답한다.',
    messages: await convertToModelMessages(messages),
  })

  return createUIMessageStreamResponse({
    stream: toUIMessageStream({ stream: result.stream }),
  })
}

클라이언트가 보낸 UI 메시지를 모델 메시지로 변환한 뒤, 결과 스트림을 UI 메시지 스트림 응답으로 돌려준다. maxDuration은 플랫폼에서 함수가 실행될 수 있는 최대 시간(초)이다. 인증과 호출 빈도 제한은 이 핸들러 앞단에서 처리한다. 문서 예제의 함수 이름은 SDK 버전에 따라 바뀌어 왔으므로, 설치한 버전의 문서 예제를 기준으로 맞춘다.

2단계: useChat으로 메시지 렌더링하기

'use client'

import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'
import { useState } from 'react'

export default function Chat() {
  const { messages, sendMessage, status, stop, error, regenerate } = useChat({
    transport: new DefaultChatTransport({ api: '/api/chat' }),
    throttle: 50,
  })
  const [input, setInput] = useState('')
  const busy = status === 'submitted' || status === 'streaming'

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role === 'user' ? '나' : 'AI'}</strong>
          {m.parts.map((p, i) => (p.type === 'text' ? <span key={i}>{p.text}</span> : null))}
        </div>
      ))}

      {status === 'submitted' && <p aria-live="polite">답변을 준비하는 중…</p>}
      {busy && <button type="button" onClick={() => stop()}>중단</button>}
      {error && (
        <div role="alert">
          응답을 받지 못했습니다. <button type="button" onClick={() => regenerate()}>다시 시도</button>
        </div>
      )}

      <form onSubmit={(e) => {
        e.preventDefault()
        if (!input.trim()) return
        sendMessage({ text: input })
        setInput('')
      }}>
        <input value={input} onChange={(e) => setInput(e.target.value)} disabled={status !== 'ready'} />
        <button type="submit" disabled={status !== 'ready'}>보내기</button>
      </form>
    </div>
  )
}

현재 버전의 메시지는 content 문자열 하나가 아니라 parts 배열로 구성된다. 텍스트 외에 도구 호출 결과 같은 다른 종류의 부분이 섞일 수 있어서, type별로 렌더링을 나눈다. 입력값은 훅이 관리하지 않으므로 useState로 직접 관리한다.

상태별로 보여 줄 UI

status	의미	권장 UI
submitted	요청을 보냈고 스트림 시작을 기다리는 중	"준비 중" 표시, 중단 버튼, 입력 비활성화
streaming	응답을 받는 중	텍스트가 늘어나는 메시지, 중단 버튼
ready	응답 완료, 새 메시지 가능	입력 활성화
error	요청 실패	오류 안내와 다시 시도 버튼

문서에 따르면 stop()은 서버 스트림을 중단하고 이후 메시지 처리를 멈춘다. 사용자가 잘못 보낸 질문이나 너무 긴 답변을 끊을 수 있게 하면 불필요한 토큰 소비도 줄어든다. regenerate()는 마지막 응답을 다시 생성한다.

3단계: 렌더링 빈도 조절하기

토큰이 들어올 때마다 리렌더링하면 긴 대화에서 화면이 버벅일 수 있다. throttle 옵션(밀리초)을 주면 스트림 처리는 그대로 두고 화면 업데이트만 묶어서 반영한다. 메시지 목록이 길어지면 메시지 컴포넌트를 분리하고 메모이제이션해 이전 메시지가 다시 그려지지 않게 한다.

운영 전에 확인할 것

1. 네트워크를 끊은 상태에서 전송해 error 상태와 다시 시도 버튼이 나타나는지 확인한다.
2. 긴 답변 도중 중단 버튼을 눌러 서버 로그에서 생성이 멈추는지 확인한다.
3. 연속으로 빠르게 전송했을 때 입력이 비활성화되어 중복 요청이 생기지 않는지 본다.
4. 응답 텍스트를 HTML로 그대로 넣지 않고 텍스트로 렌더링해 스크립트 삽입을 막는다.
5. Route Handler에 인증·호출 빈도 제한·입력 길이 제한이 있는지 확인한다.

에이전트 기능을 붙여 도구 호출 결과를 UI에 보여 주려면 parts의 다른 타입을 렌더링해야 한다. 에이전트 확장 방식은 Vercel Agent Plugins 글에서 다뤘다.