TanStack AI – 생성형 AI 앱 구축을 위한 유형 안전, 공급업체에 구애받지 않는 SDK

정의 – 스트리밍 채팅, 도구 호출 에이전트, 구조화된 출력 흐름, 멀티모달 생성(이미지, 오디오, 비디오, 문서), 실시간 음성, 코드 실행 에이전트를 작성할 수 있는 TypeScript 패키지 모음입니다. 핵심 SDK는 공급업체에 구애받지 않습니다. OpenAI, Anthropic, Gemini, Ollama 등용 어댑터와 React, Vue, Solid, Svelte, Preact 또는 헤드리스 클라이언트용 프레임워크 바인딩을 추가할 수 있습니다.

---

핵심 개념

개념	제공 내용
구성 가능한 활동	채팅, 생성, 실시간, 도구 등은 필요할 때만 가져오는 별도의 "활동"으로, 번들을 작게 유지합니다.
공급업체에 구애받지 않는 어댑터	단일 adapter 객체로 OpenAI, Anthropic, Grok, Ollama, Cloudflare Workers AI 등을 전환합니다.
유형 안전 계약	도구, 구조화된 출력, 모델별 페이로드까지 Zod/Valibot/ArkType 또는 원시 JSON Schema로 정의되므로 TypeScript는 입력과 결과의 정확한 형태를 알 수 있습니다.
프레임워크 네이티브 훅	React, Vue, Solid, Svelte, Preact용 useChat, useRealtimeChat, 생성 훅, UI 구성 요소.
에이전트 스킬 통합	패키지는 코딩 어시스턴트(Claude, Cursor, Copilot…)가 자동으로 설치할 수 있는 SKILL.md를 노출하여 SDK를 AI 지원 개발을 위한 일급 스킬로 전환할 수 있습니다.

---

빠른 시작

# 핵심 SDK + OpenAI 어댑터
pnpm add @tanstack/ai @tanstack/ai-openai

# React UI용(훅 + UI 구성 요소)
pnpm add @tanstack/ai-react @tanstack/ai-client

서버 측 스트리밍 채팅 예제

import { chat, toServerSentEventsResponse } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages,
  })
  return toServerSentEventsResponse(stream)   // 브라우저용 SSE
}

동일한 chat 호출은 브라우저, 워커 또는 테스트 스크립트 내에서 작동합니다.

---

주요 기능

1. 스트리밍 채팅 및 도구 호출

• 유형화된 메시지 객체(role, content).
• 서버 또는 클라이언트에서 동일한 유형 계약으로 실행할 수 있는 도구 정의(toolDefinition)에 대한 기본 제공 지원.
• 동적 도구 로딩을 위한 자동 도구 승인 흐름 및 지연 검색.

2. 구조화된 출력

const Person = z.object({ name: z.string(), age: z.number() })
const result = await chat({
  adapter: openaiText('gpt-5.2'),
  messages: [{ role: 'user', content: '에이다 러브레이스의 짧은 약력을 알려주세요' }],
  outputSchema: Person,
})
// result는 { name: string; age: number }로 유형화됩니다.

모든 스키마 라이브러리 또는 원시 JSON Schema에서 작동합니다.

3. 멀티모달 생성

• openaiImage, falVideo, geminiSpeech와 같은 한 줄 어댑터를 사용하면 동일한 generationClient 패턴으로 이미지, 비디오, 오디오, 전사, 요약 등을 요청할 수 있습니다.

4. 실시간 음성 채팅

어댑터는 토큰을 생성하고 오디오 청크를 스트리밍하는 실시간 세션을 노출하여 저지연 음성 어시스턴트를 가능하게 합니다.

5. 코드 모드

모델은 샌드박스 VM 내에서 실행되는 TypeScript를 작성할 수 있어 루프, 분기, 병렬 도구 호출이 가능합니다. 복잡한 오케스트레이션 또는 데이터 처리 에이전트에 유용합니다.

6. 관찰 가능성 및 개발 도구

• 메시지, 도구 호출, 사용량, 오류에 대한 이벤트 스트림.
• 공급업체 중립적 추적을 위한 OpenTelemetry 내보내기.
• 라이브 스트림을 검사하기 위한 선택적 UI 개발 도구 패키지.

---

생태계 및 확장성

부분	목적
@tanstack/ai-client	헤드리스 클라이언트 – 프레임워크 바인딩 없는 핵심 로직.
@tanstack/ai‑react, ‑solid, ‑vue, ‑svelte, ‑preact	해당 UI 라이브러리용 훅/컴포저블.
@tanstack/ai‑react/ui(및 유사)	채팅 창용 기성 헤드리스 UI 구성 요소(사용자 지정 UI를 위해 더 이상 사용되지 않음).
공급업체 어댑터(‑openai, ‑anthropic, ‑gemini, ‑ollama, ‑groq, …)	일반 SDK 호출을 각 공급업체의 HTTP API로 변환합니다.
@tanstack/ai‑openrouter	300개 이상의 모델로 라우팅하는 단일 API 키. 요청별 비용 추적 기능 포함.
@tanstack/ai‑cloudflare	Cloudflare Workers에서 실행되며 AI Gateway, 임베딩 등을 노출합니다.

각 활동과 어댑터는 트리 셰이커블하므로 실제로 사용하는 코드만 제공합니다.

---

누가 사용할 수 있나요?

• 풀스택 개발자 – 챗봇, AI 강화 UI 또는 유형 안전이 필요한 내부 도구를 구축하는 개발자.
• 제품 팀 – 코드를 다시 작성하지 않고 공급업체(OpenAI ↔ Anthropic ↔ 로컬 Ollama)를 전환하려는 팀.
• LLM 운영 엔지니어 – 통합 관찰 가능성 계층과 OpenTelemetry 지원을 찾는 엔지니어.
• 도구 구축 플랫폼 – 다운스트림 에이전트에 유형화된 도구 계약을 노출하는 플랫폼.
• 교육 또는 취미 프로젝트 – 자체 HTTP 래퍼를 만드는 대신 기성의 잘 문서화된 SDK를 원하는 프로젝트.

---

문서 및 커뮤니티

• 전체 문서 – https://tanstack.com/ai(개요, 빠른 시작, Vercel AI SDK와의 비교, 고급 주제).
• GitHub 토론, Discord, 기여자를 위한 스폰서 프로그램.
• 에이전트 스킬 – 코딩 어시스턴트가 SDK를 스킬로 자동 설치할 수 있게 하는 고유한 기능으로, TanStack AI를 개발자를 위한 일급 어시스턴트로 만듭니다.

---

요약

TanStack AI는 채팅, 도구 호출 에이전트, 멀티모달 생성, 실시간 음성 또는 샌드박스 코드 실행 등 모든 종류의 생성형 AI 애플리케이션을 구축하기 위한 유형 안전하고 모듈식인 TypeScript SDK입니다. 어댑터를 통해 많은 공급업체를 추상화하고, 프레임워크별 훅을 제공하며, 개발자 경험(스키마, 관찰 가능성, 트리 셰이킹)을 강조합니다. 강력한 TypeScript 보장을 유지하면서 공급업체에 구애받지 않기를 원하는 팀에 이상적입니다.