`useChat()`
useChat()
챗봇 애플리케이션의 대화형 UI를 쉽게 만들 수 있게 해 주는 훅이에요. AI 프로바이더의 메시지를 스트리밍하고 채팅 상태를 관리하며 UI를 자동으로 갱신해 줘요.
출처: 문서
본문
챗봇 애플리케이션을 위한 대화형 사용자 인터페이스를 쉽게 만들 수 있게 해 주는 훅이에요. AI 프로바이더에서 채팅 메시지를 스트리밍하고, 채팅 상태를 관리하며, 새 메시지가 도착하면 UI를 자동으로 업데이트해요.
Import
- React:
import { useChat } from '@ai-sdk/react' - Svelte:
import { Chat } from '@ai-sdk/svelte' - Vue:
import { useChat } from '@ai-sdk/vue' - Angular:
import { Chat } from '@ai-sdk/angular'
API Signature
Parameters
- chat:
Chat<UIMessage>(선택) — 사용할 기존 Chat 인스턴스. 제공되면 다른 파라미터는 무시돼요. - transport:
ChatTransport(선택) — 메시지를 보내는 데 사용할 transport. 기본값은/api/chat엔드포인트를 사용하는DefaultChatTransport예요.- api:
string = '/api/chat'(선택) — 채팅 요청용 API 엔드포인트. - credentials:
RequestCredentials(선택) — fetch 요청의 credentials 모드. - headers:
Record<string, string> | Headers(선택) — 요청과 함께 보낼 HTTP 헤더. - body:
object(선택) — 요청과 함께 보낼 추가 body 객체. - fetch:
FetchFunction(선택) — 커스텀 fetch 구현. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트용 커스텀 fetch 구현을 제공할 수 있어요. - prepareSendMessagesRequest:
PrepareSendMessagesRequest(선택) — 채팅 API 호출 전에 요청을 커스터마이즈하는 함수. 옵션:id(채팅 ID),messages(현재 채팅 메시지),requestMetadata(요청 메타데이터),body(요청 본문),credentials,headers,api(기본값 transport의/api/chat),trigger('submit-message' | 'regenerate-message'),messageId(해당 시 메시지 ID). - prepareReconnectToStreamRequest:
PrepareReconnectToStreamRequest(선택) — reconnect API 호출 전에 요청을 커스터마이즈하는 함수. 옵션:id,requestMetadata,body,credentials,headers,api(기본값 transport의 엔드포인트 + 채팅 ID:/api/chat/{chatId}/stream).
- api:
- id:
string(선택) — 채팅의 고유 식별자. 제공하지 않으면 랜덤으로 생성돼요. - messages:
UIMessage[](선택) — 대화를 채울 초기 채팅 메시지. - messageMetadataSchema:
FlexibleSchema(선택) — 메시지 메타데이터 검증용 스키마. - dataPartSchemas:
UIDataTypesToSchemas(선택) — 메시지의 데이터 파트 검증용 스키마. - generateId:
IdGenerator(선택) — 메시지와 채팅의 고유 ID를 생성하는 함수. 제공하지 않으면 기본 AI SDK generateId가 사용돼요. - onToolCall:
({toolCall: ToolCall}) => void | Promise<void>(선택) — 툴 호출을 받았을 때 호출되는 선택 콜백. 툴 결과를 제공하려면addToolOutput을 호출해야 해요. - sendAutomaticallyWhen:
(options: { messages: UIMessage[] }) => boolean | PromiseLike<boolean>(선택) — 제공하면 스트림이 끝나거나 툴 호출이 추가되었을 때 현재 메시지를 다시 제출할지 결정하기 위해 이 함수가 호출돼요. 일반적인 시나리오에는lastAssistantMessageIsCompleteWithToolCalls헬퍼를 사용할 수 있어요. - onFinish:
(options: OnFinishOptions) => void(선택) — 어시스턴트 응답 스트리밍이 끝났을 때 호출돼요. 옵션:message(응답 메시지),messages(응답 메시지를 포함한 모든 메시지),isAbort(클라이언트가 요청을 중단했을 때 true),isDisconnect(네트워크 오류 등으로 서버가 끊겼을 때 true),isError(스트리밍 중 오류로 응답이 일찍 멈췄을 때 true),finishReason(모델이 응답 생성을 끝낸 이유. 모델이 제공하지 않았으면 undefined). - onError:
(error: Error) => void(선택) — 오류를 만났을 때 호출되는 콜백. - onData:
(dataPart: DataUIPart) => void(선택) — 데이터 파트를 받았을 때 호출되는 선택 콜백. - throttle:
number(선택) — React와 Vue 전용. 반응형 채팅 메시지 갱신의 커스텀 throttle 대기 시간(밀리초). 양수 값은 스트림 처리나 콜백을 지연시키지 않고 UI 갱신 빈도를 낮춰요. 최신 메시지는 ready 또는 error 상태 전에 게시돼요. 기본값은 undefined로 throttle가 비활성화돼요. - resume:
boolean(선택) — 진행 중인 채팅 생성 스트림을 재개할지 여부. 기본값은 false.
Returns
- id:
string— 채팅의 ID. - messages:
UIMessage[]— 현재 채팅 메시지 배열. 각UIMessage는id(고유 식별자),role('system' | 'user' | 'assistant'),parts(UI 렌더링에 사용하는 메시지 파트),metadata(선택, 메시지 메타데이터)를 포함해요. - status:
'submitted' | 'streaming' | 'ready' | 'error'— 채팅의 현재 상태:"ready"(대기),"submitted"(요청 전송),"streaming"(응답 수신 중),"error"(요청 실패). - error:
Error | undefined— 오류가 발생한 경우의 오류 객체. - sendMessage:
(message?, options?) => Promise<void>— 새 메시지를 채팅에 보내는 함수. 어시스턴트 응답 생성을 위한 API 호출을 트리거해요. messageId를 제공하면 메시지를 교체해요(편집에 유용).CreateUIMessage로 교체할 때는 그 id를 제공해 교체본에 새 ID를 부여하세요. 메시지가 없으면 현재 메시지를 다시 제출해요(툴 출력 추가 후 유용). 옵션:headers,body,metadata. - regenerate:
(options?) => Promise<void>— 마지막 어시스턴트 메시지 또는 특정 메시지를 다시 생성하는 함수. messageId가 없으면 마지막 어시스턴트 메시지를 재생성해요. 헤더, body, 메타데이터용ChatRequestOptions를 받아요. - stop:
() => void— 현재 어시스턴트 스트리밍 응답을 중단하는 함수. - clearError:
() => void— 오류 상태를 지워요. - resumeStream:
() => void— 중단된 스트리밍 응답을 재개하는 함수. 스트리밍 중 네트워크 오류가 발생했을 때 유용해요. - addToolOutput:
(options: { tool: string; toolCallId: string; output: unknown } | { tool: string; toolCallId: string; state: "output-error", errorText: string }) => void— 채팅에 툴 결과를 추가하는 함수. 툴 결과로 채팅 메시지를 업데이트해요.sendAutomaticallyWhen이 설정되어 있으면 자동 제출을 트리거할 수 있어요. - addToolApprovalResponse:
(options: { id: string; approved: boolean; reason?: string }) => void | PromiseLike<void>— 툴 승인 요청에 응답하는 함수. id는 툴 호출의 승인 id와 일치해야 해요.sendAutomaticallyWhen이 설정되어 있으면 자동 제출을 트리거할 수 있어요. - addToolResult:
(options) => void— 더 이상 사용하지 않음.addToolOutput을 사용하세요. - setMessages:
(messages: UIMessage[] | ((messages: UIMessage[]) => UIMessage[])) => void— API 호출 없이 로컬에서 메시지 상태를 업데이트하는 함수. 낙관적 업데이트(optimistic updates)에 유용해요.