생성형 UI 상태 관리하기

챗봇에서 상태는 보통 messages 배열로 표현돼요. 각 메시지는 고유한 id, 보낸 사람을 뜻하는 role(user/assistant/system/tool), 그리고 content를 가집니다. 이런 상태는 UI에도 그릴 수 있고 모델에도 그대로 보낼 수 있어서 다루기 편합니다. 그런데 생성형 UI(Generative UI)에서는 모델이 평문 메시지 대신 React 컴포넌트를 돌려줄 수 있는데, React 컴포넌트는 직렬화(serialise)가 안 돼서 그 상태를 다시 모델로 보낼 수 없어요. 이 문제를 해결하기 위해 AI SDK RSC가 도입한 AI State와 UI State 개념을 살펴볼게요.

출처: 공식문서

본문

AI State와 UI State란 무엇인가

UI State는 클라이언트에서 렌더링되는 애플리케이션 상태를 가리켜요. React의 useState처럼 완전히 클라이언트 쪽에만 있는 상태라서, JavaScript 값부터 React 엘리먼트까지 무엇이든 담을 수 있어요. 즉 클라이언트에 실제로 그려지는 UI 요소들의 목록입니다. 참고로 UI State는 클라이언트에서만 접근할 수 있어요.

반대로 AI State는 모델과 주고받을 수 있는 상태입니다. 서버 쪽에서 접근하고 갱신할 수 있어요.

AI/UI State 사용하기

@ai-sdk/rsc는 내부적으로 React context를 사용해 여러 훅을 제공하고, 이를 통해 애플리케이션 전반의 AI/UI State 관리를 단순화합니다.

먼저 createAI로 React context를 만들어요. 두 타입을 정의하고, 초기 상태(initialAIState, initialUIState)와 Server Actions(actions)를 넘겨줍니다.

// AI State와 UI State 타입 정의
export type ServerMessage = {
  role: 'user' | 'assistant';
  content: string;
};

export type ClientMessage = {
  id: string;
  role: 'user' | 'assistant';
  display: ReactNode;
};

export const AI = createAI<AIState, UIState>({
  initialAIState: [],
  initialUIState: [],
  actions: {
    sendMessage,
  },
});

actions 객체에는 반드시 Server Actions를 넘겨야 해요. 만든 context로 애플리케이션을 감싸면, 앱 전체에서 AI/UI State를 읽고 쓸 수 있습니다.

클라이언트에서 UI State 읽기 — useUIState 훅이 현재 UI State와 갱신 함수를 돌려줘요. React의 useState와 비슷한 모양입니다.
서버에서 AI State 읽기 — createAI context에 제공한 Server Action 안에서 getAIState 함수로 현재 AI State를 읽기 전용 값으로 받아올 수 있어요.
서버에서 AI State 갱신하기 — history.update(...)처럼 갱신 함수로 AI State를 바꿉니다.

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

export async function sendMessage(message: string) {
  'use server';
  const history = getAIState();
  // ...
  history.update([...history.get(), { role: 'user', content: message }]);
  const response = await generateText({
    model: "xai/grok-4.6",
    messages: history.get(),
  });
  // 모델 응답으로 AI State를 다시 갱신
}

클라이언트에서 Server Actions 호출하기 — useActions 훅으로 sendMessage 같은 액션을 가져오고, useUIState로 메시지 목록을 다룹니다. 사용자가 메시지를 제출하면 sendMessage 액션이 호출되고, 그 응답이 UI State에 추가되어 화면에 반영됩니다.

중요! Server Action을 호출한 뒤에도 UI State를 갱신하는 것을 잊지 마세요. 그렇지 않으면 스트리밍된 컴포넌트가 UI에 나타나지 않아요.

더 알아보기

React Server Components와 context 기반 훅이 궁금하면 React 공식 문서의 Hooks 참고.
상태 저장/복원이 필요한 경우 "Saving and Restoring States" 페이지로 이어져요.
@ai-sdk/rsc로 AI/UI State를 다루는 전체 예시가 공식 문서에 제공됩니다.