Overview

TanStack AI is a modular, provider-agnostic AI SDK with tree-shakeable adapters for OpenAI, Anthropic, Gemini, Ollama, and more. It provides streaming-first text generation, tool calling with approval workflows, structured output with Zod schemas, multimodal content support, and React hooks for chat/completion UIs.

Core: @tanstack/ai Vanilla Client: @tanstack/ai-client (framework-agnostic) React: @tanstack/ai-react Solid: @tanstack/ai-solid Adapters: @tanstack/ai-openai, @tanstack/ai-anthropic, @tanstack/ai-gemini, @tanstack/ai-ollama Languages: TypeScript/JavaScript, PHP, Python Status: Alpha

Installation

npm install @tanstack/ai @tanstack/ai-react
# Or for framework-agnostic vanilla client:
npm install @tanstack/ai @tanstack/ai-client
# Provider adapters (install only what you need):
npm install @tanstack/ai-openai
npm install @tanstack/ai-anthropic
npm install @tanstack/ai-gemini
npm install @tanstack/ai-ollama

PHP Installation

composer require tanstack/ai tanstack/ai-openai

Python Installation

pip install tanstack-ai tanstack-ai-openai

Core: generate()

import { generate } from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai/adapters";

const result = await generate({
  adapter: openaiText({ model: "gpt-4o" }),
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain React hooks in 3 sentences." },
  ],
});

// Streaming with async iteration
for await (const chunk of result) {
  process.stdout.write(chunk.text);
}

Provider Adapters

import { openaiText } from "@tanstack/ai-openai/adapters";
import { anthropicText } from "@tanstack/ai-anthropic/adapters";
import { geminiText } from "@tanstack/ai-gemini/adapters";
import { ollamaText } from "@tanstack/ai-ollama/adapters";

// OpenAI
const openai = openaiText({ model: "gpt-4o" });

// Anthropic
const anthropic = anthropicText({ model: "claude-sonnet-4-20250514" });

// Google Gemini
const gemini = geminiText({ model: "gemini-pro" });

// Ollama (local)
const ollama = ollamaText({ model: "llama3" });

// Runtime adapter switching
const adapter = process.env.AI_PROVIDER === "anthropic" ? anthropic : openai;

React Hooks

useChat

import { useChat } from "@tanstack/ai-react";

function ChatUI() {
  const { messages, input, setInput, handleSubmit, isLoading } = useChat({
    adapter: openaiText({ model: "gpt-4o" }),
  });

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Type a message..."
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>
    </div>
  );
}

useCompletion

import { useCompletion } from "@tanstack/ai-react";

function CompletionUI() {
  const { completion, input, setInput, handleSubmit, isLoading } =
    useCompletion({
      adapter: openaiText({ model: "gpt-4o" }),
    });

  return (
    <div>
      <form onSubmit={handleSubmit}>
        <textarea
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Enter prompt..."
        />
        <button type="submit" disabled={isLoading}>
          Generate
        </button>
      </form>
      {completion && <div>{completion}</div>}
    </div>
  );
}

Solid.js Hooks

import { createChat } from "@tanstack/ai-solid";

function ChatUI() {
  const chat = createChat({
    adapter: openaiText({ model: "gpt-4o" }),
  });

  return (
    <div>
      <For each={chat.messages()}>
        {(msg) => (
          <div>
            <strong>{msg.role}:</strong> {msg.content}
          </div>
        )}
      </For>
      <form onSubmit={chat.handleSubmit}>
        <input
          value={chat.input()}
          onInput={(e) => chat.setInput(e.target.value)}
          placeholder="Type a message..."
        />
        <button type="submit" disabled={chat.isLoading()}>
          Send
        </button>
      </form>
    </div>
  );
}

Vanilla Client

For framework-agnostic usage without React or Solid:

import { createAIClient } from "@tanstack/ai-client";
import { openaiText } from "@tanstack/ai-openai/adapters";

const client = createAIClient({
  adapter: openaiText({ model: "gpt-4o" }),
});

// Subscribe to state changes
client.subscribe((state) => {
  console.log("Messages:", state.messages);
  console.log("Loading:", state.isLoading);
});

// Send a message
await client.send("Hello, world!");

// Clear conversation
client.clear();

Streaming

Streaming Strategies

import { generate } from '@tanstack/ai'

// Default: stream chunks as they arrive
const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [...],
  stream: true,
})

for await (const chunk of result) {
  // Process each chunk
  console.log(chunk.text)
}

Available streaming strategies:

Batch - Collect all chunks before delivery
Punctuation - Stream at sentence boundaries
WordBoundary - Stream at word boundaries
Composite - Combine multiple strategies

Server-Sent Events (SSE)

// Server-side SSE endpoint
import { createReplayStream } from "@tanstack/ai";

export async function handler(req: Request) {
  const stream = createReplayStream({
    adapter: openaiText({ model: "gpt-4o" }),
    messages: await req.json(),
  });

  return new Response(stream, {
    headers: { "Content-Type": "text/event-stream" },
  });
}

Structured Output

import { generate } from "@tanstack/ai";
import { convertZodToJsonSchema } from "@tanstack/ai";
import { z } from "zod";

const RecipeSchema = z.object({
  name: z.string(),
  ingredients: z.array(
    z.object({
      item: z.string(),
      amount: z.string(),
    }),
  ),
  steps: z.array(z.string()),
  cookTime: z.number(),
});

const result = await generate({
  adapter: openaiText({ model: "gpt-4o" }),
  messages: [{ role: "user", content: "Give me a pasta recipe" }],
  schema: convertZodToJsonSchema(RecipeSchema),
});

// result is typed as z.infer<typeof RecipeSchema>
console.log(result.name, result.ingredients);

Tool Calling

Basic Tools

import { generate } from "@tanstack/ai";

const result = await generate({
  adapter: openaiText({ model: "gpt-4o" }),
  messages: [{ role: "user", content: "What is the weather in NYC?" }],
  tools: {
    getWeather: {
      description: "Get weather for a location",
      parameters: z.object({
        location: z.string(),
        unit: z.enum(["celsius", "fahrenheit"]).optional(),
      }),
      execute: async ({ location, unit }) => {
        const data = await fetchWeather(location, unit);
        return data;
      },
    },
  },
});

Tool Calling with Approval Workflows

import { ToolCallManager } from "@tanstack/ai";

const manager = new ToolCallManager({
  tools: {
    deleteUser: {
      description: "Delete a user account",
      parameters: z.object({ userId: z.string() }),
      requiresApproval: true, // Requires human approval
      execute: async ({ userId }) => {
        await deleteUser(userId);
        return { success: true };
      },
    },
  },
  onApprovalRequired: async (toolCall) => {
    // Present to user for approval
    return await showApprovalDialog(toolCall);
  },
});

Agentic Loop

const result = await generate({
  adapter: openaiText({ model: "gpt-4o" }),
  messages: [{ role: "user", content: "Research and summarize the topic" }],
  tools: { search, summarize, writeReport },
  maxIterations: 10, // Limit agent loop iterations
});

Multimodal Content

// Images
const result = await generate({
  adapter: openaiText({ model: "gpt-4o" }),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is in this image?" },
        {
          type: "image_url",
          image_url: { url: "https://example.com/photo.jpg" },
        },
      ],
    },
  ],
});

// Image generation with DALL-E
import { openaiImage } from "@tanstack/ai-openai/adapters";

const image = await generate({
  adapter: openaiImage({ model: "dall-e-3" }),
  messages: [{ role: "user", content: "A sunset over mountains" }],
});

// Image generation with Gemini Imagen
import { geminiImage } from "@tanstack/ai-gemini/adapters";

const image = await generate({
  adapter: geminiImage({ model: "imagen-3" }),
  messages: [{ role: "user", content: "A futuristic cityscape at night" }],
});

Thinking Models (Reasoning Tokens)

Support for models with extended reasoning/thinking capabilities:

import { generate } from "@tanstack/ai";
import { anthropicText } from "@tanstack/ai-anthropic/adapters";

const result = await generate({
  adapter: anthropicText({ model: "claude-sonnet-4-20250514" }),
  messages: [
    {
      role: "user",
      content: "Solve this complex math problem step by step...",
    },
  ],
  thinking: {
    enabled: true,
    budget: 10000, // Max thinking tokens
  },
});

// Access thinking/reasoning output
console.log("Thinking:", result.thinking);
console.log("Response:", result.text);

// Streaming with thinking tokens
for await (const chunk of result) {
  if (chunk.type === "thinking") {
    console.log("[Thinking]", chunk.text);
  } else {
    process.stdout.write(chunk.text);
  }
}

Message Utilities

import { generateMessageId, normalizeToUIMessage } from "@tanstack/ai";

// Generate unique message IDs
const id = generateMessageId();

// Normalize provider-specific messages to UI format
const uiMessage = normalizeToUIMessage(providerMessage);

Observability

const result = await generate({
  adapter: openaiText({ model: 'gpt-4o' }),
  messages: [...],
  onEvent: (event) => {
    // Structured, typed events
    switch (event.type) {
      case 'text':
        console.log('Text chunk:', event.data)
        break
      case 'tool_call':
        console.log('Tool called:', event.name)
        break
      case 'error':
        console.error('Error:', event.error)
        break
    }
  },
})

AI Devtools

TanStack AI includes a dedicated devtools panel for debugging AI workflows:

import { TanStackDevtools } from "@tanstack/react-devtools";
import { AIDevtoolsPanel } from "@tanstack/ai-react/devtools";

function App() {
  return (
    <TanStackDevtools
      plugins={[
        {
          id: "ai",
          name: "AI",
          render: () => <AIDevtoolsPanel />,
        },
      ]}
    />
  );
}

AI Devtools features:

Message Inspector - View full conversation history with metadata
Token Usage - Track input/output tokens and costs per request
Streaming Visualization - Real-time view of streaming chunks
Tool Call Debugging - Inspect tool calls, parameters, and results
Thinking/Reasoning Viewer - Debug reasoning tokens from thinking models
Adapter Switching - Test different providers in development
Request/Response Logs - Full HTTP request/response inspection

TanStack Start Integration

// Shared implementation between AI tools and server functions
import { createServerFn } from "@tanstack/react-start";
import { generate } from "@tanstack/ai";

const aiChat = createServerFn({ method: "POST" })
  .validator(z.object({ messages: z.array(messageSchema) }))
  .handler(async ({ data }) => {
    const result = await generate({
      adapter: openaiText({ model: "gpt-4o" }),
      messages: data.messages,
    });
    return result;
  });

Partial JSON Parser

For streaming structured output that arrives incrementally:

import { parsePartialJson } from "@tanstack/ai";

// Parse incomplete JSON during streaming
const partial = parsePartialJson(
  '{"name": "Pasta", "ingredients": [{"item": "flour"',
);
// Returns: { name: "Pasta", ingredients: [{ item: "flour" }] }

Best Practices

Import only needed adapters - tree-shakeable design minimizes bundle size
Use structured output with Zod schemas for type-safe AI responses
Set maxIterations on agentic loops to prevent runaway execution
Use requiresApproval for destructive tool calls
Handle streaming errors gracefully with try/catch around async iteration
Use server functions for API key security (never expose keys client-side)
Use onEvent for observability and debugging in development
Switch adapters at runtime for A/B testing or fallback strategies
Use partial JSON parsing for progressive UI updates during streaming
Normalize messages when switching between providers

Common Pitfalls

Exposing API keys in client-side code (use server functions)
Not handling streaming errors (async iteration can throw)
Forgetting maxIterations in agentic loops (can run indefinitely)
Importing all adapters instead of just the one needed (bundle bloat)
Not using structured output for data extraction (unreliable string parsing)
Creating new adapter instances on every render (memoize or define at module level)

tanstack-ai