본문으로 건너뛰기

Overview

TanStack AI는 프로덕션에 바로 사용할 수 있는 AI 경험을 구축하기 위한 경량 타입 안전 SDK입니다. 프레임워크 독립적인 코어는 타입 안전한 도구/함수 호출, 스트리밍 응답, React 및 Solid를 위한 일급 통합과 여러 LLM 제공자용 어댑터를 제공하여 모든 스택에서 예측 가능하고 조합 가능하며 테스트 가능한 AI 기능을 구현합니다.

주요 기능​

  • ✅ 타입 안전 - Zod 스키마 타입 추론을 포함한 완전한 TypeScript 지원
  • ✅ 스트리밍 - 실시간 응답을 위한 기본 제공 스트리밍 지원
  • ✅ 동형 도구 - toolDefinition()으로 한 번 정의하고 .server() 또는 .client()로 구현
  • ✅ 프레임워크 독립적 - 코어 라이브러리가 어디서나 작동
  • ✅ 여러 제공자 - OpenRouter, OpenAI, Anthropic, Gemini, Ollama 등
  • ✅ 승인 흐름 - 도구 승인 워크플로를 기본 지원
  • ✅ 자동 실행 - 서버 도구와 클라이언트 도구를 모두 자동 실행

사용자는 브라우저에 자신의 제공자 API 키를 붙여 넣을 수 있습니다. Bring Your Own Key를 참조하세요.

프레임워크 독립성​

TanStack AI의 프레임워크 독립적인 코어는 다음을 포함한 모든 환경에서 AI 경험을 만드는 구성 요소를 제공합니다.

  • Next.js - API 라우트 및 App Router
  • TanStack Start - React Start 또는 Solid Start (권장!)
  • React Native / Expo - useChat, 절대 서버 URL 및 XHR 스트리밍 전송을 사용하는 네이티브 채팅 화면
  • Express - Node.js 서버
  • React Router v7 - 로더 및 액션

TanStack AI를 사용하면 도구를 한 번 정의하고 환경별 구현을 제공할 수 있습니다. toolDefinition()으로 도구의 입력/출력 타입을 선언하고 .server()로 서버 동작을 구현합니다(또는 .client()로 클라이언트 구현을 제공합니다). 이러한 동형 도구는 프레임워크와 관계없이 AI 런타임에서 호출할 수 있습니다.

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

// Define a tool
const getProductsDef = toolDefinition({
  name: 'getProducts',
  description: 'Search for products by query',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.array(z.object({ id: z.string(), name: z.string() })),
})

// Create server implementation
const getProducts = getProductsDef.server(async ({ query }) => {
  return await db.products.search(query)
})

// Use in AI chat
chat({
  adapter: openaiText('gpt-5.2'),
  messages: [{ role: 'user', content: 'Find products' }],
  tools: [getProducts]
})

핵심 패키지​

TanStack AI 생태계는 여러 패키지로 구성됩니다.

@tanstack/ai​

LLM 제공자에 연결하기 위한 AI 어댑터 인터페이스를 제공하는 핵심 AI 라이브러리입니다.

  • 채팅 완성 및 스트리밍
  • 동형 도구/함수 호출 시스템
  • 에이전트 루프 전략
  • toolDefinition()을 사용한 타입 안전 도구 정의
  • 어댑터 및 모델 선택에 기반한 타입 안전 Model Options
  • 모델 기능에 기반한 타입 안전 콘텐츠 모달리티(text, image, audio, video, document)

@tanstack/ai-client​

채팅 상태를 관리하는 프레임워크 독립적 헤드리스 클라이언트입니다.

  • 완전한 타입 안전성을 갖춘 메시지 관리
  • 스트리밍 지원
  • 연결 어댑터(SSE, HTTP stream, custom)
  • 도구 자동 실행(서버 및 클라이언트)
  • 도구 승인 흐름 처리

@tanstack/ai-react​

TanStack AI용 React 훅입니다.

  • 채팅 인터페이스를 위한 useChat 훅
  • 자동 상태 관리
  • 도구 승인 흐름 지원
  • InferChatMessages를 사용한 타입 안전 메시지 처리

@tanstack/ai-solid​

TanStack AI용 Solid 훅입니다.

  • 채팅 인터페이스를 위한 useChat 훅
  • 자동 상태 관리
  • 도구 승인 흐름 지원
  • InferChatMessages를 사용한 타입 안전 메시지 처리

@tanstack/ai-octane​

TanStack AI용 Octane 훅입니다.

  • 채팅 인터페이스를 위한 useChat 훅
  • @tanstack/ai-react와 동일한 훅 이름
  • .tsrx 소스에서 Octane 플러그인으로 컴파일됨

어댑터​

어댑터를 사용하면 TanStack AI를 다양한 LLM 제공자에 연결할 수 있습니다. 사용 가능한 어댑터는 다음과 같습니다.

  • @tanstack/ai-openrouter - 단일 API 키를 통해 300 개 이상의 모델을 제공하는 OpenRouter (권장)
  • @tanstack/ai-openai - OpenAI (GPT 시리즈)
  • @tanstack/ai-anthropic - Anthropic (Claude)
  • @tanstack/ai-gemini - Google Gemini
  • @tanstack/ai-vertex - Google Vertex AI 의 Gemini. Vertex 에는 @tanstack/ai-anthropic/vertex, @tanstack/ai-grok/vertex, @tanstack/ai-mistral/vertex 에서 Claude, Grok, Mistral 이 실행됩니다.
  • @tanstack/ai-ollama - Ollama (로컬 모델)
  • @tanstack/ai-groq - Groq
  • @tanstack/ai-grok - xAI Grok
  • @tanstack/ai-bedrock - Amazon Bedrock (AWS 를 통한 Claude, Nova, Llama 등)
  • @tanstack/ai-byteplus - BytePlus (Seed 채팅, Seedance 비디오, Seedream 이미지, Seed 음성)
  • @tanstack/ai-fal - fal (이미지 및 비디오 생성)
  • @tanstack/ai-llmgateway - LLM 게이트웨이 (하나의 OpenAI 호환 엔드포인트를 통해 수백 개의 모델, 자체 호스팅 가능)
  • @tanstack/ai-lovable - Lovable AI 게이트웨이 (하나의 프로젝트 키를 통한 Google 및 OpenAI 채팅, 이미지, 비디오, 임베딩, 음성)

다음 단계​