DOCSEARCHbyAlgolia
Submit Docs

TanStack AI

repository·main·Indexed 25 days ago

https://github.com/tanstack/ai

A type-safe, provider-agnostic TypeScript SDK for building modern AI applications, including streaming chat, tool-calling agents, and multimodal workflows. The ecosystem includes @tanstack/ai for core functionality and @tanstack/ai-acp for Agent Client Protocol (ACP) plumbing, allowing developers to integrate ACP-compliant agent CLIs via acpCompatible.

Tokens
406.5K
Snippets
897
Records
1.6K
Agent score
83%

What's inside TanStack AI

  1. Overview of TanStack AI Capabilities

    main

    TanStack AI is a type-safe, provider-agnostic AI SDK designed for building AI-powered applications. It supports multiple frameworks including React, Solid, Vue, Svelte, and Preact.

    Key capabilities include:

    • Chat Experiences: End-to-end chat with server endpoints, streaming, and client hooks.
    • Tool Calling: Isomorphic tools with server/client execution and approval flows.
    • Media Generation: Image, video, TTS, and transcription via specific adapters.
    • Code Execution: A 'Code Mode' sandbox system for executing LLM-generated code.
    • Structured Outputs: Type-safe schema enforcement for chat responses.
    • Extensibility: Middleware for analytics, caching, and observability, and support for custom backend integrations via the AG-UI protocol.

  2. Overview of TanStack AI Sandboxes

    main

    A sandbox provides a coding agent with a real execution environment, including a filesystem, a shell, processes, and a cloned repository. This allows agents to perform actual work like file edits, command execution, and tool calls, rather than just discussing code.

    Sandboxed runs are composed of three independent parts:

    1. Provider: The isolation primitive defining where the agent runs (e.g., your host machine, a Docker container, or a cloud VM). Examples include dockerSandbox or localProcessSandbox.
    2. Workspace: Defines what the agent sees, including the source repository, package manager, setup commands, and secrets.
    3. Harness adapter: Defines which agent runs and how its output is translated into chat chunks. Examples include grokBuildText, claudeCodeText, codexText, opencodeText, or acpCompatible for any ACP agent.

    You bind these together using defineSandbox() and enable them in a chat() call using the withSandbox() middleware.

  3. Overview of Interrupts

    main

    Interrupts allow you to pause an agent run for a human or application decision (e.g., approving a money transfer or confirming a deletion) and then resume the run exactly where it stopped.

    Workflow

    1. Pause: The server reaches a step requiring a decision and ends the run with an interrupt outcome.
    2. Detection: The client receives the pending decisions via the interrupts array.
    3. Resolution: You resolve the interrupt by approving, rejecting, submitting a value, or canceling.
    4. Continuation: The client starts a fresh continuation run that carries your answers to resume the agent.

    This process is stateless; the browser sends the full message history back on the continuation request, allowing a stateless server to rebuild the paused step.

  4. Overview of TanStack AI Core Packages

    main

    The TanStack AI ecosystem is divided into several specialized packages:

    • @tanstack/ai: The core library. Provides the AI adapter interface, chat completion/streaming, the isomorphic tool system, agent loop strategies, and type-safe content modalities (text, image, audio, video, document).
    • @tanstack/ai-client: A headless, framework-agnostic client for managing chat state, message management, connection adapters (SSE, HTTP stream), and tool approval flows.
    • @tanstack/ai-react: React-specific hooks, including useChat for managing chat interfaces and state, with support for InferChatMessages.
    • @tanstack/ai-solid: Solid-specific hooks, including useChat for managing chat interfaces and state, with support for InferChatMessages.

  5. Mistral Adapter Features and Limitations

    main

    Supported Features

    • Streaming chat completions
    • Structured output (JSON Schema)
    • Function/tool calling
    • Reasoning (for magistral_ models — streamed as REASONING__ events)
    • Multimodal input (text + images) — requires a vision-capable model (pixtral-large-latest, pixtral-12b-2409, mistral-medium-latest, or mistral-small-latest)

    Unsupported Features

  6. Understand Runtime Context in TanStack AI

    main

    Runtime context is application state passed to tool implementations and middleware. It is used for request-scoped or client-local dependencies like authenticated users, database clients, tenancy, feature flags, or browser services.

    Key distinctions:

    • It is not prompt context.
    • It is not the AG-UI RunAgentInput.context field.
    • It is never sent to the model automatically.
    • It is used for implementation details that should remain private from the LLM.

  7. Pick a TanStack AI Connection Adapter

    main

    A connection adapter determines how data chunks travel between your server and the ChatClient (and useChat hook). Choose an adapter based on your environment and requirements:

    RequirementRecommended Adapter
    Default HTTP serverfetchServerSentEvents
    Environment blocking SSE (edge runtimes, strict proxies)fetchHttpStream
    React Native or ExpoxhrHttpStream (default), xhrServerSentEvents (for SSE), or fetchHttpStream (only if streaming fetch is supported)
    Synchronous AsyncIterable<StreamChunk> (in-process, RSC, tests)stream
    Async call (TanStack Start server function, Promise returning)fetcher
    RPC framework (Cap'n Web, gRPC-Web, tRPC)rpcStream
    Long-lived WebSocket/BroadcastChannelCustom subscribe / send adapter
    Standard SSE with custom fetch (auth, retries)fetchServerSentEvents with fetchClient
    Custom protocols (HTTP/3, etc.)Custom connect adapter

  8. Understand the TanStack AI Tool Architecture

    main

    TanStack AI uses a multi-layered architecture to enable AI agents to interact with external systems. The system is divided into several key components:

    • Server Tools: Execute securely on the backend, allowing for database access and private API calls.
    • Client Tools: Execute in the browser, ideal for UI updates and local operations.
    • The Agentic Cycle: Supports multi-step reasoning and complex workflows.
    • Tool States: Provides real-time feedback for building robust UIs.
    • Approval Flow: Allows users to review and approve sensitive operations before execution.

  9. Understand @tanstack/openai-base architecture

    main

    @tanstack/openai-base provides shared base adapters for providers that use the official openai Node SDK but point to a different baseURL (e.g., xAI's Grok, Groq, or OpenAI itself).

    It contains shared logic for two specific wire formats to ensure consistent AG-UI event emission (RUN_STARTED, TEXT_MESSAGE_*, TOOL_CALL_*, etc.) across different providers:

    • OpenAIBaseChatCompletionsTextAdapter: For the /v1/chat/completions endpoint.
    • OpenAIBaseResponsesTextAdapter: For the /v1/responses endpoint.

    Providers that do not follow the OpenAI wire format (like Anthropic or Gemini) extend the core BaseTextAdapter from @tanstack/ai directly instead of using this package.

  10. Choose a Sandbox Provider

    main

    TanStack AI uses providers to define where the agent's isolation primitive runs. Every provider implements the same SandboxProvider / SandboxHandle contract, making your workspace and policy provider-agnostic. Choose a provider based on your needs for isolation, authentication, and snapshot/resume behavior.

    ProviderPackageIsolationNotes
    Local process@tanstack/ai-sandbox-local-processnone (host)Fast dev loop. Trusted/dev use only.
    Docker@tanstack/ai-sandbox-dockercontainerReal isolation; supports snapshots, fork, and resume-by-id.
    Daytona@tanstack/ai-sandbox-daytonacloud sandboxManaged Daytona sandboxes; needs DAYTONA_API_KEY.
    Vercel@tanstack/ai-sandbox-vercelmicroVMManaged Vercel microVMs; needs VERCEL_TOKEN.
    Sprites@tanstack/ai-sandbox-spritesstateful sandboxManaged Sprites (Fly.io) sandboxes; needs SPRITES_API_KEY.
    import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
import { daytonaSandbox } from '@tanstack/ai-sandbox-daytona'
import { vercelSandbox } from '@tanstack/ai-sandbox-vercel'

const dev = localProcessSandbox() // runs on your host
const isolated = dockerSandbox({ image: 'node:22' }) // runs in a container
const daytona = daytonaSandbox({ apiKey: process.env.DAYTONA_API_KEY }) // managed cloud sandbox
const vercel = vercelSandbox({ runtime: 'node24' }) // managed Vercel microVM

  11. Compare TanStack AI and Vercel AI SDK

    main

    TanStack AI and Vercel AI SDK are both TypeScript toolkits for AI applications, but they differ in philosophy:

    • TanStack AI is a library composition approach. It provides composable building blocks (adapters, tools, agent loops, transport, UI) that you import and compose. It has no implicit platform associations and is designed to be tree-shakeable and isomorphic.
    • Vercel AI SDK is a full-stack platform approach. It provides primitives with optional platform integrations for gateway routing, observability, and deployment optimization.

    Key Technical Differences

    FeatureTanStack AIVercel AI SDK
    Framework HooksReact, Solid, Svelte, Vue, Preact (+ React Native)React, Vue, Svelte, Angular
    Tool CallingIsomorphic .server() / .client() systemtool() objects; client execution via onToolCall
    Agent LoopComposable strategy functions (state) => booleanstopWhen conditions + Agent class
    Type SafetyPer-model type narrowingPer-provider types
    Structured OutputsTyped StructuredOutputPart, streamed alongside tools and preserved in historygenerateObject() / streamObject() (per-call; no structured-output message part)
    Code ExecutionUser-managed sandboxes (Node.js, Cloudflare Workers, QuickJS)Provider-hosted tools (Anthropic, xAI, OpenAI)
    MCP SupportStandalone host-side client (@tanstack/ai-mcp) + mcpTool()Built-in (@ai-sdk/mcp)

  12. Compare Code Mode Isolate Drivers

    main

    Code Mode uses Isolate Drivers to provide secure sandbox runtimes for executing generated TypeScript. You can choose a driver based on your deployment target and performance needs. All drivers implement the same IsolateDriver interface, allowing you to swap them without changing your application logic.

    FeatureNode (isolated-vm)QuickJS (WASM)Cloudflare Workers
    Best forServer-side Node.js appsBrowsers, edge, portabilityEdge deployments on Cloudflare
    PerformanceFast (V8 JIT)Slower (interpreted)Fast (V8 on Cloudflare edge)
    Native depsYes (C++ addon)NoneNone
    Browser supportNoYesN/A
    Memory limitConfigurableConfigurableN/A
    Setuppnpm addpnpm addDeploy a Worker first