언어 모델로 UI 렌더링하기

언어 모델은 기본적으로 텍스트를 만들어 내니까, 처음에는 애플리케이션에서 텍스트만 렌더링하면 된다고 생각할 수 있어요. 그런데 도구가 텍스트 대신 날씨 정보를 담은 JSON 객체를 돌려주고, 그 객체를 React 컴포넌트에 넘겨 조건부로 렌더링하면, 모델이 생성한 UI를 그대로 보여줄 수 있어요. 이 페이지에서는 이런 "언어 모델로 UI 렌더링" 방식이 어떻게 진행되는지, 그리고 서버에서 직접 UI를 스트리밍하는 방법까지 살펴볼게요.

출처: 공식문서

본문

기본 아이디어는 이래요. 언어 모델에 getWeather 같은 도구를 넘기고, 그 도구가 텍스트 대신 날씨 정보를 표현하는 JSON 객체를 반환하게 만듭니다. 그러면 클라이언트에서 그 객체를 props로 받아 <WeatherCard/> 컴포넌트를 조건부로 렌더링할 수 있어요.

여러 UI 렌더링하기

클라이언트에서 조건부로 UI를 렌더링하는 흐름은 이렇게 정리할 수 있어요.

사용자가 언어 모델에 프롬프트를 보냅니다.
언어 모델이 도구 호출을 포함한 응답을 생성해요.
도구 호출이 UI를 표현하는 JSON 객체를 돌려줍니다.
응답이 클라이언트로 전송됩니다.
클라이언트는 응답을 받아 가장 최근 메시지가 도구 호출인지 확인해요.
도구 호출이었다면, 도구 호출이 반환한 JSON 객체를 기반으로 사용자 인터페이스를 렌더링합니다.

서버에서 UI 렌더링하기

AI SDK RSC(@ai-sdk/rsc)는 React Server Components(RSC)를 활용해, 모든 React 컴포넌트를 클라이언트에서 관리해야 하는 문제를 해결해요. 클라이언트에서 모델이 돌려준 데이터를 기반으로 조건부 렌더링하는 대신, 모델 생성 중에 서버에서 컴포넌트를 직접 스트리밍할 수 있습니다.

createStreamableUI 함수는 @ai-sdk/rsc 모듈에 속하며, React 컴포넌트를 클라이언트로 보낼 수 있는 스트림을 만들어 줍니다.

import { createStreamableUI } from '@ai-sdk/rsc';

const uiStream = createStreamableUI();

const text = generateText({
  model: "xai/grok-4.6",
  instructions: 'you are a friendly assistant',
  prompt: 'what is the weather in SF?',
  tools: {
    getWeather: {
      // ...
      generate: async ({ location }) => {
        // ...
        return <WeatherCard weather={weather} location={location} />;
      },
    },
  },
});

return {
  display: uiStream.value,
};

서버에서 <WeatherCard/>를 props와 함께 렌더링한 뒤 클라이언트로 스트리밍하고, 클라이언트는 서버에서 온 UI만 그대로 보여주면 돼요.

사용자가 언어 모델에 프롬프트를 보냅니다.
언어 모델이 도구 호출을 포함한 응답을 생성해요.
도구 호출이 사용자 인터페이스를 표현하는 props와 함께 React 컴포넌트를 렌더링합니다.
응답이 클라이언트로 스트리밍되어 그대로 렌더링됩니다.

참고: React Server Components를 쓰면 텍스트도 서버에서 렌더링해 클라이언트로 스트리밍할 수 있어요. 이러면 언어 모델 생성부터 UI 렌더링까지 모든 작업을 서버에서 처리하고, 클라이언트는 스트리밍된 UI만 렌더링하면 됩니다.

더 알아보기

createStreamableUI — RSC에서 컴포넌트 스트림을 만드는 함수.
streamUI — React 컴포넌트를 스트리밍하는 상위 수준 함수(RSC 페이지 참고).
Next.js App Router에서 컴포넌트 업데이트를 스트리밍하는 전체 예시가 공식 문서에 제공돼요.