TanStack/ai

스트리밍 채팅 (streaming chat), 도구 호출 에이전트 (tool-calling agents), 구조화된 출력 (structured outputs), 실시간 음성 (realtime voice), 미디어 생성 (media generation), 그리고 프레임워크 네이티브 (framework-native) AI 앱을 구축하기 위한 타입 안전 (Type-safe) 및 제공자 불가지론적 (provider-agnostic) TypeScript SDK입니다.

TanStack AI는 조합 가능한 액티비티 (activities) 및 제공자 어댑터 (provider adapters)로 구축되었습니다. 하나의 제공자를 사용하거나 여러 제공자 사이를 전환할 수 있습니다. 채팅 (chat)만 가져오거나, 앱의 필요에 따라 이미지 (image), 오디오 (audio), 비디오 (video), 음성 (speech), 전사 (transcription), 요약 (summarization), 실시간 (realtime), 코드 모드 (Code Mode), 개발 도구 (devtools), 그리고 프레임워크 바인딩 (framework bindings)을 추가할 수 있습니다.

• 개요 (Overview) - TanStack AI가 무엇인지와 패키지들이 어떻게 결합되는지에 대한 설명.

• 빠른 시작: React - React 앱에 스트리밍 채팅 추가하기.

• 빠른 시작: Vue - Vue 컴포저블 (composables)로 구축하기.

• 빠른 시작: Svelte - Svelte 5 룬 (runes)으로 구축하기.

• 빠른 시작: 서버 전용 (Server Only) - 서버 엔드포인트, 스크립트 또는 백엔드 서비스에서 TanStack AI 사용하기.

• TanStack AI vs Vercel AI SDK - 아키텍처 (architecture), 기능 범위 (feature coverage), 그리고 트레이드오프 (tradeoffs) 비교.

• 타입이 지정된 메시지 (typed messages), 도구 호출 (tool calls), 추론 부분 (reasoning parts), 그리고 설정 가능한 연결 어댑터 (connection adapters)를 포함한 스트리밍 채팅 경험.

• 하나의 공유된 toolDefinition() 계약 (contract)으로부터 서버 또는 클라이언트에서 실행될 수 있는 타입 안전한 도구 (Type-safe tools).

• JSON Schema, Zod, ArkType, Valibot 또는 일반 JSON Schema를 기반으로 하는 구조화된 출력 (Structured output) 흐름.

• 텍스트, 이미지, 오디오, 비디오, 문서가 포함된 멀티모달 (Multimodal) 프롬프트 및 응답.

• 공유된 생성 클라이언트 (generation client) 패턴을 사용하는 이미지, 오디오, 비디오, 음성, 전사 및 요약 워크플로.

• 실시간 세션 및 토큰 민팅 (token minting)을 위한 제공자 어댑터를 갖춘 실시간 음성 채팅.

• LLM이 격리된 샌드박스 (sandbox)에서 TypeScript를 작성하고 실행하여 루프 (loops), 분기 (branches), 병렬 호출 (parallel calls)과 함께 도구를 오케스트레이션 (orchestrate)할 수 있는 코드 모드 (Code Mode) 에이전트.

• 메시지, 도구 호출, 스트림 청크 (stream chunks), 오류, 사용량, 그리고 OpenTelemetry 트레이스 (traces)를 검사하기 위한 개발 도구 (Devtools) 및 관측성 파이프라인 (observability pipelines).

• React, Solid, Vue, Svelte, Preact를 위한 프레임워크 네이티브 (Framework-native) 클라이언트 및 커스텀 런타임을 위한 헤드리스 클라이언트 (headless client).

코어 패키지와 앱에서 사용하는 제공자/프레임워크 패키지를 설치하세요:

pnpm add @tanstack/ai @tanstack/ai-openai

React 채팅 UI를 위한 경우:

pnpm add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-openai

하나의 API 키를 통해 많은 제공자(Providers)에 접근하고 싶다면 OpenRouter 또한 좋은 시작점입니다:

pnpm add @tanstack/ai @tanstack/ai-openrouter

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
export async function POST(request: Request) {
...

자세한 내용은 Chat & Streaming 문서와 Connection Adapters 문서를 참조하세요.

도구(Tool)를 한 번 정의한 다음, 동일한 입력 및 출력 타입을 가진 서버 또는 클라이언트 구현을 연결하세요:

import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'
const getProducts = toolDefinition({
...

자세한 내용은 Tools 문서, Tool Approval Flow 문서, 그리고 Lazy Tool Discovery 문서를 참조하세요.

자유 형식의 텍스트 대신 타입이 지정된 객체(Typed objects)가 필요한 경우 outputSchema를 사용하세요:

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import { z } from 'zod'
...

자세한 내용은 Structured Outputs 문서를 참조하세요.

• Generations - 이미지 생성, 텍스트 음성 변환 (Text-to-speech), 전사 (Transcription), 요약 (Summarization), 오디오 생성 및 비디오 생성을 위한 하나의 패턴.
• Realtime Voice Chat - 저지연 실시간 음성 경험 구축.
• Code Mode - 모델이 보안 격리 환경 (Secure isolate) 내에서 TypeScript를 작성하고 실행할 수 있도록 함.
• Code Mode with Skills - Code Mode에 재사용 가능한 런타임 기능 (Runtime capabilities) 부여.

공식 어댑터(Official adapters)는 다음과 같습니다:

패키지 (Package)	용도 (Use it for)
@tanstack/ai-openrouter	요청당 비용 추적 기능을 포함하여 하나의 OpenRouter API를 통해 300개 이상의 모델 사용
@tanstack/ai-openai	OpenAI 채팅 (chat), 이미지 (image), 비디오 (video), 음성 (speech), 전사 (transcription), 실시간 (realtime) 및 프로바이더 도구 (provider tools)
@tanstack/ai-anthropic	Anthropic Claude 채팅 (chat), 사고 (thinking), 도구 (tools) 및 구조화된 출력 (structured outputs)
@tanstack/ai-gemini	Google Gemini 채팅 (chat), 이미지 (image), 음성 (speech) 및 오디오 생성 (audio generation)
@tanstack/ai-ollama	로컬 Ollama 모델
@tanstack/ai-grok	xAI Grok 채팅 (chat), 이미지 (images) 및 실시간 (realtime)
@tanstack/ai-groq	Groq 저지연 추론 (low-latency inference)
@tanstack/ai-elevenlabs	ElevenLabs 실시간 음성 (realtime voice), 음성 (speech), 전사 (transcription), 음악 (music) 및 음향 효과 (sound effects)
@tanstack/ai-fal	fal.ai 이미지 (image), 비디오 (video), 오디오 (audio), 음성 (speech) 및 전사 (transcription) 모델

어댑터 시스템은 활동(activity) 단위로 트리 쉐이킹 (tree-shakeable)이 가능합니다. 채팅 (chat)을 위한 openaiText, 이미지 (images)를 위한 openaiImage, 비디오 (video)를 위한 falVideo, TTS를 위한 geminiSpeech 등을 임포트(Import)하세요.

패키지 (Package)	제공 기능 (What it provides)
@tanstack/ai-client	헤드리스 채팅 (Headless chat), 실시간 (realtime) 및 생성 (generation) 클라이언트
@tanstack/ai-react	useChat, useRealtimeChat 및 생성 훅 (generation hooks)을 포함한 React 훅 (hooks)
@tanstack/ai-solid	채팅 (chat) 및 생성을 위한 Solid 훅 (hooks)
@tanstack/ai-vue	채팅 (chat) 및 생성을 위한 Vue 컴포저블 (composables)
@tanstack/ai-svelte	채팅 (chat) 및 생성을 위한 Svelte 5 팩토리 (factories)
@tanstack/ai-preact	채팅 (chat)을 위한 Preact 훅 (hooks)
@tanstack/ai-react-ui, @tanstack/ai-solid-ui, @tanstack/ai-vue-ui	채팅 인터페이스를 위한 헤드리스 UI 컴포넌트 (Headless UI components)

• 미들웨어 (Middleware) - 채팅 설정 (chat configuration), 청크 (chunks), 도구 호출 (tool calls), 사용량 (usage), 에러 (errors) 및 구조화된 출력 (structured outputs)에 연결 (hook into).

• OpenTelemetry - 벤더 중립적인 (vendor-neutral) 생성형 AI (GenAI) 트레이스 (traces) 및 메트릭 (metrics) 방출.

• 모델별 타입 안정성 (Per-Model Type Safety) - 선택한 모델에 맞춰 모델 옵션과 콘텐츠 모달리티 (content modalities)를 제한합니다.

• 런타임 어댑터 전환 (Runtime Adapter Switching) - 런타임 중에 제공자 (providers)를 전환할 수 있습니다.

• 트리 쉐이킹 (Tree-Shaking) - 사용 중인 액티비티 (activities)와 어댑터 (adapters)만 포함하여 배포합니다.

• 에이전트 기술 (Agent Skills) - TanStack Intent를 사용하여 Claude Code, Cursor, GitHub Copilot, Codex 및 기타 코딩 에이전트에 TanStack AI 기술을 설치합니다.

• 문서를 읽어보세요.

• GitHub Discussions에 참여하세요.

• Discord에서 커뮤니티와 채팅하세요.

• 설정 지침은 CONTRIBUTING.md를 참조하세요.

• 스폰서가 되어주세요.

|
|
|

우리는 우리의 미션에 동참할 TanStack AI 파트너를 찾고 있습니다. TanStack AI의 경계를 넓히고 함께 놀라운 것들을 만들어가기 위해 저희와 파트너가 되어주세요.

LET'S CHAT

TanStack Config- JS/TS 패키지용 툴링 (tooling)
TanStack DB- 반응형 동기화 클라이언트 스토어 (reactive sync client store)
TanStack Devtools- 통합 개발자 도구 (unified devtools) 패널
TanStack Form- 타입 안정성이 보장된 폼 상태 (type-safe form state)
TanStack Pacer- 디바운싱 (debouncing), 쓰로틀링 (throttling), 배칭 (batching)
TanStack Query- 비동기 상태 (async state) 및 캐싱 (caching)
TanStack Ranger- 범위 (range) 및 슬라이더 (slider) 프리미티브 (primitives)
TanStack Router- 타입 안정성이 보장된 라우팅 (type-safe routing), 캐싱 (caching) 및 URL 상태 (URL state)
TanStack Start- 풀스택 SSR 및 스트리밍 (streaming)
TanStack Store- 반응형 데이터 스토어 (reactive data store)
TanStack Table- 헤드리스 데이터 그리드 (headless datagrids)
TanStack Virtual- 가상화 렌더링 (virtualized rendering)

...그리고 TanStack.com에서 더 많은 것을 확인하세요.