React 컴포넌트 스트리밍하기

RSC API를 쓰면 streamUI 함수로 React 컴포넌트를 서버에서 클라이언트로 스트리밍할 수 있어요. 단순한 텍스트를 넘어, 실시간으로 컴포넌트 자체를 클라이언트에 흘려보내고 싶을 때 유용합니다. AI SDK Core API(예: streamText)와 비슷하게, streamUI는 모델을 호출하고 React Server Components로 응답받게 해주는 하나의 함수예요. 같은 모델 인터페이스를 지원한다는 점도 장점입니다.

출처: 공식문서

본문

개념

streamUI 함수에서는 React 컴포넌트를 반환하는 도구들을 제공해요. 컴포넌트를 스트리밍할 수 있게 되면, 모델은 사용자 의도를 파악해 관련 UI를 골라 보여주는 일종의 동적 라우터(dynamic router)처럼 동작합니다.

streamUI도 다른 AI SDK Core 함수와 유사하게 동작해요. 모델에 프롬프트나 대화 기록, 그리고 선택적으로 도구를 넘겨주면, 모델이 대화 문맥에 따라 도구 호출을 결정합니다. streamUI는 그 도구를 실행해 React 컴포넌트를 반환하고, 모델이 쓸만한 도구를 찾지 못하면 텍스트 생성 결과를 text 함수에 넘겨서 렌더링하도록 합니다.

const result = await streamUI({
  model: openai('gpt-4o'),
  prompt: 'Get the weather for San Francisco',
  text: ({ content }) => <div>{content}</div>,
  tools: {},
});

이 예시는 OpenAI의 gpt-4o 모델로 streamUI를 호출하고, 프롬프트를 넘기며, 모델의 평문 응답(content)을 어떻게 렌더링할지 지정한 다음, 도구로 빈 객체를 제공해요. 주의할 점은 streamUI는 반드시 React 컴포넌트를 반환해야 한다는 거예요.

도구 추가하기

streamUI에서 도구를 쓰는 방식은 generateText나 streamText에서 쓰는 것과 비슷합니다. 도구는 이런 것을 가진 객체예요.

description — 모델에게 도구가 무엇을 하고 언제 써야 하는지 알려주는 문자열.
inputSchema — 도구 실행에 필요한 입력을 설명하는 Zod 스키마.
generate — 모델이 도구를 호출하면 실행되는 비동기 함수. 반드시 React 컴포넌트를 반환해야 해요.

const result = await streamUI({
  model: openai('gpt-4o'),
  prompt: 'Get the weather for San Francisco',
  text: ({ content }) => <div>{content}</div>,
  tools: {
    getWeather: {
      description: 'Get the weather for a location',
      inputSchema: z.object({ location: z.string() }),
      generate: async function* ({ location }) {
        yield <LoadingComponent />;
        const weather = await getWeather(location);
        return <WeatherComponent weather={weather} location={location} />;
      },
    },
  },
});

generate에서 제너레이터 문법(yield)을 쓰면 로딩 컴포넌트를 먼저 보여주고, 실제 데이터가 준비되면 최종 컴포넌트로 갈아끼울 수 있어요.

Next.js에서 `streamUI` 사용하기

Next.js 앱에서 streamUI를 쓰려면 두 가지가 필요해요.

Server Action — streamUI를 호출하는 곳.
Page — Server Action을 호출하고 결과 컴포넌트를 렌더링하는 페이지.

Server Action은 'use server' 지시어와 함께 streamUI를 호출하는 비동기 함수입니다. 입력을 받지 않고 ReactNode를 반환하도록 만들고, 그 안에서 모델(gpt-4o), 프롬프트, 텍스트일 때 렌더링할 컴포넌트, 그리고 getWeather 도구를 지정해요. 페이지에서는 액션이 반환한 ReactNode를 React state(setComponent)로 받아 화면에 그립니다.

더 알아보기

createStreamableUI — 더 저수준에서 컴포넌트 스트림을 다루는 함수.
AI/UI State 관리가 궁금하면 "Managing Generative UI State" 페이지.
Next.js App Router에서 streamUI로 컴포넌트를 스트리밍하는 전체 예시가 공식 문서에 있어요.

React 컴포넌트 스트리밍하기