본문으로 건너뛰기

AI 앱의 UI 패턴 — 스트리밍·도구 호출 상태·낙관적 렌더링

AI 응답이 느리고 부분적으로 도착하고 실패한다는 특성이 UI 설계를 지배합니다. 토큰 스트리밍 렌더링, 도구 호출의 상태 머신, 취소와 낙관적 렌더링, aria-live 접근성까지 정리한 플레이북입니다.

· 6분 읽기

AI 앱의 UI 패턴 — 스트리밍·도구 호출 상태·낙관적 렌더링

일반 폼 앱의 UI는 “요청 → 응답 → 렌더”로 정리됩니다. AI 앱은 그렇지 않습니다. 응답은 수 초 걸리고, 토큰 단위로 조금씩 도착하고, 중간에 도구가 호출되고, 실패도 잦습니다. 2026-06에 공개된 AI SDK 7이 에이전트급 기능을 기본으로 내세울 만큼 생태계는 성숙했지만, 화면을 어떻게 그릴지는 여전히 개발자의 몫입니다. 이 글은 제가 블로그에 붙인 소형 챗봇과 사이드 프로젝트에서 검증한 AI 앱 UI 패턴의 플레이북입니다.

문제 정의: AI 응답의 세 가지 특성

AI 응답 UI를 설계할 때 고려할 특성은 세 개로 압축됩니다.

  1. 느리게 시작한다 — 첫 토큰까지 수 초의 공백이 생긴다. 이 공백을 진행 표시 없이 방치하면 사용자는 끊겼다고 판단한다.
  2. 부분적으로 도착한다 — 문장이 통째로 오는 게 아니라 토큰이 흘러들어온다. 도구 호출이라는 중간 이벤트도 끼어든다.
  3. 실패한다 — 네트워크, 모델, 도구 실행 어디서든 깨질 수 있다. 실패 지점이 많은 만큼 복구 UI도 많아야 한다.

아래 패턴들은 세 특성에 대한 각각의 대답입니다.

토큰 스트리밍 렌더링

스트리밍의 전제는 “완성된 응답을 기다리지 않는 것”입니다. 표준 웹에서 이것은 ReadableStream 위에서 이뤄지고, AI SDK는 그 위에 스트림 프로토콜을 얹어 텍스트 청크와 도구 호출 이벤트를 같은 스트림에서 전달합니다. useChat은 이 스트림을 구독해 messages를 자동 갱신합니다.

'use client';

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

export function Chat() {
  const { messages, status, stop } = useChat();

  return (
    <div>
      {messages.map((message) => (
        <p key={message.id}>
          {message.parts
            .filter((part) => part.type === 'text')
            .map((part, i) => <span key={i}>{part.text}</span>)}
        </p>
      ))}
      {status === 'streaming' && <button onClick={() => stop()}>생성 중단</button>}
    </div>
  );
}

서버 렌더링 쪽과 헷갈리지 말 것입니다. React Server Components의 스트리밍은 Suspense로 느린 서버 컴포넌트를 경계부터 보내는 메커니즘이고(Next.js 문서의 스트리밍 설명, 그리고 서버/클라이언트 컴포넌트 정리 글 참고), LLM 토큰 스트리밍은 그 위에서 도는 애플리케이션 계층의 패턴입니다. 둘은 겹치지 않고 조합됩니다. RSC 스트리밍으로 셸을 먼저 보내고, 그 안에서 토큰 스트리밍이 일어나는 식입니다.

도구 호출의 UI 상태 머신

도구 호출은 이벤트가 아니라 기간입니다. AI SDK에서 도구 호출은 어시스턴트 메시지의 parts에 타입된 tool part로 들어오고, 상태 머신을 따라갑니다. input-streaming(인자 도착 중) → input-available(실행 가능) → output-available(완료) 또는 output-error(실패)이 기본 축이고, 승인 흐름이면 approval-requested/approval-responded/output-denied가 끼어듭니다.

UI는 이 상태 전부를 소모해야 합니다. 스위치문 하나로 끝나지만, 빠뜨린 상태는 곧 “아무 일도 안 하는 화면”이 됩니다.

function WeatherTool({ part }: { part: ToolPartGetWeather }) {
  switch (part.state) {
    case 'input-streaming':
      return <div role="status">요청 구성 중…</div>;
    case 'input-available':
      return <div role="status">{part.input.city} 날씨 조회 중…</div>;
    case 'output-available':
      return <WeatherCard weather={part.output} />;
    case 'output-error':
      return <ErrorNote message={part.errorText} />;
    default:
      return null;
  }
}

상태 머신을 직접 그리는 이유는 진행 표시가 여기 붙기 때문입니다. “로딩 스피너 하나”가 아니라, 어떤 도구가 어떤 인자로 실행 중인지 보여주는 것이 2026년의 기본기입니다. 사용자 동의가 필요한 도구는 approval-requested 상태에서 확인 버튼을 노출하면 됩니다. AI SDK 7이 강조하는 도구 승인(tool approval) 흐름도 같은 맥락입니다.

진행 표시와 취소

useChat은 대화 전체의 status(submitted → streaming → ready, 오류 시 error)를 노출합니다(참고 문서). 진행 표시는 이 상태를 그리는 것이고, 취소는 stop()입니다. 취소의 실체는 웹 표준인 AbortController의 어보트이므로, 직접 fetch를 쓰는 경우에도 같은 원리로 구현합니다.

const { status, stop, error } = useChat();

// 진행 표시: 상태별 문구
const hint =
  status === 'submitted' ? '질문을 보내는 중…'
  : status === 'streaming' ? '응답 생성 중…'
  : status === 'error' ? '오류가 발생했어요'
  : null;

// 취소는 사용자가 "기다림의 주도권"을 갖게 하는 최소한의 예의
{status !== 'ready' && <button onClick={() => stop()}>중단</button>}

긴 생성이 많은 서비스라면 새로고침 후에도 스트림을 이어 받는 스트림 재개(resume)까지 고려합니다. 취소와 재개를 함께 설계해야 “중단”이 “유실”이 되지 않습니다.

낙관적 렌더링과 생성형 UI

사용자 행동에 대한 응답도 느립니다. 예를 들어 메시지 전송 버튼을 누르면 내 메시지가 즉시 목록에 올라가야 하는데, 이럴 때 쓰는 것이 React 19의 useOptimistic입니다. 임시 상태를 보여주고 서버 확정 시 자동 원복되는 훅입니다(React 19 릴리즈).

한 걸음 더 나가면 생성형 UI입니다. 도구 결과를 텍스트가 아니라 컴포넌트로 렌더링하는 패턴으로, Generative User Interfaces 가이드가 표준 레시피를 제공합니다. 위의 WeatherCard가 바로 그 예시입니다. 도구의 output 타입을 컴포넌트 props로 대응시키는 것 외에 특별한 기술은 없습니다. 중요한 규칙은 하나, 생성형 UI에도 상태 머신이 적용된다는 점입니다. 카드가 뜨기 전까지는 input-available 상태의 안내가 그 자리를 채웁니다.

에러와 재시도

에러 UI의 원칙은 “어디서 깨졌는지 보여주고, 사용자가 다시 시도할 수 있게 한다”입니다. 제 체크리스트는 이렇습니다.

  • status === 'error'와 error 객체를 화면에 노출: 원인(네트워크/모델/도구)을 구분해 문구를 다르게
  • 도구 실패는 메시지 전체 실패와 구분: output-error인 tool part만 빨간 카드로
  • 재시도는 마지막 사용자 메시지를 재전송하는 버튼으로: 전체 새로고침은 최후 수단
  • 부분 도착한 텍스트는 버리지 않고 유지: 재시도 시 이어 붙일 수 있게

접근성: aria-live로 스트리밍 알리기

스트리밍 UI의 접근성 함정은 “조용한 갱신”입니다. 화면은 계속 바뀌지만 스크린리더는 알지 못합니다. 대답은 ARIA 라이브 영역입니다. 다만 토큰마다 공지하면 그것도 재해입니다. 저는 토큰 단위가 아니라 상태 전이 단위로 공지합니다.

<div aria-live="polite" role="status">
  {status === 'streaming' ? '응답 생성 중' : '응답 완료'}
</div>

polite는 현재 발화를 끊지 않고 다음 기회에 읽어줍니다. 생성 완료 시점에 최종 문장 요약을 한 번 공지하는 구조가 토큰 낭독보다 훨씬 쓸 만합니다. 접근성 회귀 체크 관점은 프론트엔드 접근성 회귀 체크리스트에 따로 정리해 두었습니다.

체크리스트

  • 첫 토큰 전 공백을 채우는 진행 표시가 있는가
  • 텍스트를 청크 단위로 렌더링하는가 (전체 응답 대기 금지)
  • 도구 호출 상태 머신의 모든 상태를 렌더링하는가
  • 취소 버튼과 AbortController 기반 중단이 동작하는가
  • 사용자 메시지는 낙관적으로 즉시 표시되는가
  • 에러 지점(네트워크/모델/도구)을 구분해 안내하는가
  • 부분 도착 텍스트를 보존하며 재시도하는가
  • aria-live로 상태 전이를 공지하는가 (토큰 단위 공지 금지)

마치기

AI 앱의 UI 패턴은 특수해 보이지만, 결국 “느림·부분성·실패”라는 세 특성에 대한 고전적 대답의 조합입니다. 스트리밍은 대기 시간을 잘게 쪼개고, 상태 머신은 부분성을 구조로 만들고, 낙관적 렌더링과 재시도는 실패를 복구 가능하게 만듭니다. 프레임워크가 이 패턴들을 훅과 프로토콜로 흡수한 지금, 남은 일은 상태를 전부 그리는 성실함뿐이었습니다.

레퍼런스

Related

· 18 min read Build Logs

damon-chat-desk 구축기 — 로컬 에이전트 데몬의 /ws 위에 얇은 웹 데스크를 얹기

로컬 AI 에이전트 데몬(damon-agent-core) 위에 정적 SPA 채팅 데스크를 얹었습니다. OpenAI 호환 경로 대신 /ws JSON-RPC v2와 일회용 ws_ticket을 고른 이유, 툴 실행 아코디언·turn.steer·plan.respond CAS·session.fork, 메모리 게이트(-32011)를 UI 문장으로 옮기는 법, ⌘K 팔레트, https 페이지에서 loopback 데몬에 붙을 수 없을 때의 demo 폴백까지 — PR 4건 +18,477줄, 테스트 223개, 번들 375kB의 기록입니다.

프론트엔드AI
→
· 15 min read Build Logs

AI 과제 지도(assignment-map) 구축기 — 수집기 흰 화면 복구부터 18종 레퍼런스 기반 UI 개편까지

채용 과제·해커톤의 AI 정책과 마감을 매일 수집하는 과제 지도를 6일 동안 PR 16건으로 고도화했습니다. evidence 문자열 하나가 배포 화면을 통째로 죽인 장애와 그 뿌리 수정, 18종 레퍼런스 실측에서 나온 PR A~E, npm ci 앞에서 돌던 테스트가 배포를 막은 CI 함정까지 실제 수치로 정리합니다.

프론트엔드AI
→