트랜스포트

트랜스포트 (Transport)

useChat의 트랜스포트(transport) 시스템이 메시지를 API 엔드포인트로 보내는 방법과 응답을 처리하는 방법을 세밀하게 제어하는 방법을 설명하는 문서예요. WebSocket 같은 대체 통신 프로토콜, 커스텀 인증 패턴, 전문화된 백엔드 통합에 특히 유용해요.

출처: 문서

본문

useChat 트랜스포트 시스템은 메시지를 API 엔드포인트로 보내는 방법과 응답을 처리하는 방법을 세밀하게 제어할 수 있게 해 줘요. WebSocket 같은 대체 통신 프로토콜, 커스텀 인증 패턴, 전문화된 백엔드 통합에 특히 유용해요.

기본 트랜스포트 (Default Transport)

기본적으로 useChat는 HTTP POST 요청을 사용해 메시지를 /api/chat로 보내요:

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

// Uses default HTTP transport
const { messages, sendMessage } = useChat();

이것은 다음과 동일해요:

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

const { messages, sendMessage } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
  }),
});

커스텀 트랜스포트 구성 (Custom Transport Configuration)

커스텀 옵션으로 기본 트랜스포트를 구성해요:

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

const { messages, sendMessage } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/custom-chat',
    headers: {
      Authorization: 'Bearer your-token',
      'X-API-Version': '2024-01',
    },
    credentials: 'include',
  }),
});

동적 구성 (Dynamic Configuration)

구성 값을 반환하는 함수를 제공할 수도 있어요. 이는 새로고침해야 하는 인증 토큰이나 런타임 조건에 의존하는 구성에 유용해요:

const { messages, sendMessage } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
    headers: () => ({
      Authorization: `Bearer ${getAuthToken()}`,
      'X-User-ID': getCurrentUserId(),
    }),
    body: () => ({
      sessionId: getCurrentSessionId(),
      preferences: getUserPreferences(),
    }),
    credentials: () => 'include',
  }),
});

요청 변환 (Request Transformation)

API로 보내기 전에 요청을 변환해요:

const { messages, sendMessage } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
    prepareSendMessagesRequest: ({ id, messages, trigger, messageId }) => {
      return {
        headers: {
          'X-Session-ID': id,
        },
        body: {
          messages: messages.slice(-10), // Only send last 10 messages
          trigger,
          messageId,
        },
      };
    },
  }),
});

직접 에이전트 트랜스포트 (Direct Agent Transport)

HTTP를 거치지 않고 Agent와 직접 통신하고 싶은 시나리오에는 DirectChatTransport를 사용할 수 있어요. 이 트랜스포트는 에이전트의 stream() 메서드를 프로세스 내에서 직접 호출해요.

이것은 다음에 유용해요:

서버 측 렌더링: API 엔드포인트 없이 서버에서 에이전트 실행하기
테스팅: 네트워크 요청 없이 채팅 기능 테스트하기
단일 프로세스 애플리케이션: 클라이언트와 에이전트가 함께 실행되는 데스크톱이나 CLI 앱

import { useChat } from '@ai-sdk/react';
import { DirectChatTransport, ToolLoopAgent } from 'ai';
__PROVIDER_IMPORT__;

const agent = new ToolLoopAgent({
  model: __MODEL__,
  instructions: 'You are a helpful assistant.',
  tools: {
    weather: weatherTool,
  },
});

const { messages, sendMessage } = useChat({
  transport: new DirectChatTransport({ agent }),
});

동작 방식 (How It Works)

HTTP 요청을 보내는 DefaultChatTransport와 달리:

DirectChatTransport는 들어오는 UI 메시지를 검증해요
convertToModelMessages를 사용해 모델 메시지로 변환해요
에이전트의 stream() 메서드를 직접 호출해요
toUIMessageStream()을 통해 결과를 UI 메시지 스트림으로 반환해요

구성 옵션 (Configuration Options)

스트림 출력을 커스터마이즈하기 위해 추가 옵션을 전달할 수 있어요:

const transport = new DirectChatTransport({
  agent,
  // Pass options to the agent
  options: { customOption: 'value' },
  // Configure what's sent to the client
  sendReasoning: true,
  sendSources: true,
});

참고: 지속적인 서버 측 스트림이 없기 때문에 DirectChatTransport는 스트림 재연결을 지원하지 않아요. reconnectToStream() 메서드는 항상 null을 반환해요.

완전한 API 세부 정보는 DirectChatTransport 참조를 확인하세요.

워크플로 트랜스포트 (Workflow Transport)

Workflow SDK 위에 구축된 채팅 앱의 경우 @ai-sdk/workflow의 WorkflowChatTransport가 자동 스트림 재연결을 제공해요. 워크플로 함수가 스트림 도중에 타임아웃되는 흔한 시나리오를 처리하는데, 트랜스포트는 누락된 finish 이벤트를 감지하고 중단된 지점부터 재개하도록 재연결해요.

import { useChat } from '@ai-sdk/react';
import { WorkflowChatTransport } from '@ai-sdk/workflow/client';
import { useMemo } from 'react';

export default function Chat() {
  const transport = useMemo(
    () =>
      new WorkflowChatTransport({
        api: '/api/chat',
        maxConsecutiveErrors: 5,
        onChatEnd: ({ chatId, chunkIndex }) => {
          console.log(`Chat complete: ${chunkIndex} chunks`);
        },
      }),
    [],
  );

  const { messages, sendMessage } = useChat({ transport });

  // ... render chat UI
}

주요 기능:

자동 재연결: 중단된 스트림(finish 이벤트 없음)을 감지하고 GET으로 {api}/{runId}/stream에 재연결해요
페이지 새로고침 복구: initialStartIndex가 초기 재연결이 시작되는 위치를 제어해요
구성 가능한 재시도: maxConsecutiveErrors가 허용할 연속 재연결 실패 횟수를 제어해요
라이프사이클 콜백: 채팅 상태 추적을 위한 onChatSendMessage와 onChatEnd

음수 initialStartIndex 값은 지속적인 서버 스트림이 이미 UIMessageChunk 객체를 저장할 때 꼬리만 가져올 수 있어요. 원시 WorkflowAgent 스트림의 경우 비음수 커서를 사용하고 WorkflowAgent 가이드의 서버 측 변환을 따르세요.

전체 API 참조는 WorkflowChatTransport를 확인하세요. 서버 측 엔드포인트 설정은 WorkflowAgent 가이드를 참고하세요.

커스텀 트랜스포트 구축 (Building Custom Transports)

자체 트랜스포트를 구축하는 방법을 이해하려면 기본 구현의 소스 코드를 참조하세요:

DefaultChatTransport - 완전한 기본 HTTP 트랜스포트 구현
HttpChatTransport - 요청 처리를 포함한 기본 HTTP 트랜스포트
ChatTransport 인터페이스 - 구현해야 하는 트랜스포트 인터페이스

이 구현들은 다음을 정확히 어떻게 하는지 보여줘요:

sendMessages 메서드 처리
UI 메시지 스트림 처리
요청과 응답 변환
오류와 연결 관리 처리

트랜스포트 시스템은 채팅 애플리케이션이 통신하는 방법을 완전히 제어할 수 있게 해 줘서, 어떤 백엔드 프로토콜이나 서비스와도 통합할 수 있어요.

트랜스포트