TanStack AI

TanStack AI 是一个类型安全、与提供商无关的 TypeScript SDK，用于构建流式聊天、工具调用代理（Agents）、结构化输出、实时语音、媒体生成以及框架原生的 AI 应用。

TanStack AI 由可组合的活动（Activities）和提供商适配器（Provider Adapters）构建而成。你可以使用单个提供商，也可以在多个提供商之间切换。只需按需导入聊天、图像、音频、视频、语音、转录、摘要、实时通信、代码模式（Code Mode）、开发工具（Devtools）以及框架绑定即可。

阅读文档 ->

从这里开始

• 概览 - 了解 TanStack AI 是什么以及各个包如何协同工作。
• 快速上手：React - 为 React 应用添加流式聊天功能。
• 快速上手：Vue - 使用 Vue Composables 进行构建。
• 快速上手：Svelte - 使用 Svelte 5 Runes 进行构建。
• 快速上手：纯服务端 - 在服务器端点、脚本或后端服务中使用 TanStack AI。
• TanStack AI 与 Vercel AI SDK 对比 - 比较架构、功能覆盖范围及权衡。

你可以构建什么

• 带有类型化消息、工具调用、推理部分和可配置连接适配器的流式聊天体验。
• 通过共享的 toolDefinition() 契约，在服务器或客户端上运行的类型安全工具。
• 由 JSON Schema、Zod、ArkType、Valibot 或原生 JSON Schema 支持的结构化输出流。
• 包含文本、图像、音频、视频和文档的多模态提示词（Prompts）与响应。
• 使用共享生成客户端模式的图像、音频、视频、语音、转录和摘要工作流。
• 具有用于实时会话和 Token 铸造的提供商适配器的实时语音聊天。
• 代码模式（Code Mode）代理，允许 LLM 在隔离沙箱中编写和执行 TypeScript，以通过循环、分支和并行调用来编排工具。
• 用于检查消息、工具调用、流块、错误、使用情况和 OpenTelemetry 追踪的开发工具（Devtools）与可观测性管道。
• 适用于 React、Solid、Vue、Svelte 和 Preact 的框架原生客户端，以及用于自定义运行时的 Headless 客户端。

安装

安装核心包以及你应用中用到的提供商/框架包：

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

对于 React 聊天 UI：

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

如果你想通过一个 API Key 访问多个提供商，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) {
  const body = await request.json()

  const stream = chat({
    adapter: openaiText('gpt-5.2'),
    messages: body.messages,
  })

  return toServerSentEventsResponse(stream)
}

在 聊天与流式传输文档 和 连接适配器文档 中了解更多。

类型安全工具

只需定义一次工具，然后通过相同的输入和输出类型挂载服务器或客户端实现：

import { toolDefinition } from '@tanstack/ai'
import { z } from 'zod'

const getProducts = toolDefinition({
  name: 'getProducts',
  description: 'Search the product catalog',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.array(
    z.object({
      id: z.string(),
      name: z.string(),
    }),
  ),
}).server(async ({ query }) => {
  return db.products.search(query)
})

在 工具文档、工具审批流文档 和 延迟工具发现文档 中了解更多。

结构化输出

当你需要类型化对象而非自由格式文本时，请使用 outputSchema：

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

const Person = z.object({
  name: z.string(),
  age: z.number(),
})

const person = await chat({
  adapter: openaiText('gpt-5.2'),
  messages: [{ role: 'user', content: 'Ada Lovelace, 36' }],
  outputSchema: Person,
})

在 结构化输出文档 中了解更多。

媒体、实时通信与代码模式

• 生成（Generations） - 用于图像生成、文本转语音、转录、摘要、音频生成的一种统一模式。