TanStack AI Tutorial: Gateways and Tool-Calling Agents

This TanStack AI tutorial shows you how to point the framework at an external model gateway, stream a working chat in a server route plus a client hook, and build a tool-calling loop that survives multiple iterations. TanStack AI 1.0 shipped in October 2026 with stable core APIs and an experimental agent harness, after growing from a single chat() function and four providers into a toolkit covering chat, tools, media, MCP, persistence, sandboxes and agents with 23 provider adapters and eight UI frameworks (tanstack.com).

If you searched for a step-by-step path rather than a release narrative, the sequence below is the one to follow: install the matching 1.x packages, wire chat() behind a gateway adapter, add a tool with toolDefinition(), then cap the loop with maxIterations(). Where TanStack AI's own documentation is the only authority — pricing, quotas, gateway SLAs, the exact current version of the experimental harness — this article says so instead of guessing.

What TanStack AI is, and what actually changed in 1.0

TanStack AI is a TypeScript toolkit for building AI features into applications. According to tanstack.com, 1.0 arrives with stable core APIs plus a new experimental agent harness whose packages stay on 0.x. The framework now supports 23 provider adapters plus openaiCompatible for any OpenAI-style API, and eight UI frameworks plus vanilla JS: React, Vue, Solid, Svelte, Preact, Angular, Octane and Remix.

Recent additions named in the 1.0 material include subagents in chat() and useChat, decide(), portable Agent Skills, provider-agnostic computer use, BYOK with defineByok, createMCPServer, and gateway adapters such as Cloudflare AI Gateway, Lovable AI Gateway and the Vercel AI Gateway via @tanstack/ai-vercel-gateway. The 1.0 post is a release narrative: it names these features but does not walk through code for each one, so treat the naming as verified and the implementation detail as something to confirm in the docs.

The stable-versus-experimental boundary

One upgrade rule is explicit on tanstack.com: move all stable @tanstack/ai* packages together, because a 1.0 client needs a 1.0 server. The current version numbers of the experimental harness packages are not stated in the verified material — check them yourself before pinning.

Step 1: install a matching set

The Vercel integration requires a JavaScript or TypeScript project with Node.js 22 or later and a Vercel account (vercel.com). Install the core package, your UI binding and the gateway adapter together:

npm install @tanstack/ai @tanstack/ai-react @tanstack/ai-vercel-gateway

Keep every @tanstack/ai* package on the same 1.x minor while you work through this tutorial. If you need Cloudflare AI Gateway or Lovable AI Gateway, the adapters exist per the 1.0 material, but no dedicated Cloudflare or Lovable walkthrough appeared in the verified sources — read each adapter's own documentation for its package name and configuration.

Step 2: route chat() through a gateway instead of a provider key

Per github.com, the core package exposes chat(), toolDefinition(), toServerSentEventsResponse() and maxIterations(), while @tanstack/ai-react provides the useChat() hook and re-exports connection adapters. A server route that speaks to the Vercel AI Gateway looks like this:

// app/api/chat/route.ts
import { chat, toServerSentEventsResponse } from "@tanstack/ai";
import { vercelGateway } from "@tanstack/ai-vercel-gateway";

const gateway = vercelGateway({
  apiKey: process.env.AI_GATEWAY_API_KEY!,
});

export async function POST(request: Request) {
  const { messages } = await request.json();

  const stream = await chat({
    adapter: gateway,
    model: process.env.GATEWAY_MODEL_ID!,
    messages,
  });

  return toServerSentEventsResponse(stream);
}

Two things to internalise. First, switching models is a model-ID change, not a code rewrite — vercel.com describes exactly that benefit for @tanstack/ai-vercel-gateway. Second, the export name and configuration object above are illustrative of the adapter pattern; confirm the exact import and option names in the adapter's reference page before shipping, because the verified sources describe the adapter's role rather than reproducing its signature.

For a plain OpenAI-style endpoint, the 1.0 material lists openaiCompatible as a supported option. Whether it behaves identically against every gateway's OpenAI-style endpoint is not confirmed in the verified sources — test your specific endpoint.

Step 3: stream into the UI with useChat()

On the client, useChat() from @tanstack/ai-react consumes the server-sent event stream:

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

export function ChatPanel() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: "/api/chat",
  });

  return (
    <form onSubmit={handleSubmit}>
      <input value={input} onChange={handleInputChange} />
      <button type="submit">Send</button>
      <ul>
        {messages.map((m) => (
          <li key={m.id}>{m.role}: {m.content}</li>
        ))}
      </ul>
    </form>
  );
}

tanstack.com states that a quick start adds a server route, an API key and a UI to produce a streaming chat in about five minutes — the two blocks above are that shape. If your hook signature differs, the docs pages are available in plain markdown at a .md URL variant, which is the fastest way to diff your version against the current one.

Step 4: give the model a tool and cap the loop

A tool-calling agent is a chat request with a tool schema, a place to execute the call, and a ceiling on iterations. Define the tool with toolDefinition():

import { toolDefinition, chat, maxIterations } from "@tanstack/ai";

const trendingTopics = toolDefinition({
  name: "get_trending_topics",
  description: "Return topics currently gaining velocity.",
  parameters: {
    type: "object",
    properties: {
      category: { type: "string" },
      limit: { type: "number" },
    },
    required: ["category"],
  },
  execute: async ({ category, limit = 5 }) => {
    const res = await fetch(
      `https://api.trendsagi.com/api/trends?category=${encodeURIComponent(category)}&sort_by=velocity&limit=${limit}`,
      { headers: { "X-API-Key": process.env.TRENDSAGI_API_KEY! } }
    );
    if (!res.ok) throw new Error(`TrendsAGI ${res.status}`);
    const data = await res.json();
    return data;
  },
});

const stream = await chat({
  adapter: gateway,
  model: process.env.GATEWAY_MODEL_ID!,
  messages,
  tools: [trendingTopics],
  maxIterations: 4,
});

The verified source lists maxIterations() as a core export; the exact way it is passed versus called, and how tool results are fed back, should be confirmed in the reference docs. Two practical rules hold regardless: set an explicit iteration ceiling so a misbehaving tool cannot loop indefinitely, and make the tool throw on non-2xx responses so failures surface rather than becoming silent empty results.

Retries and failure handling

The release material mentions a chat({ retry }) option for retries, but no verified source in this research defines its shape. Do not copy a retry configuration from a blog post; read the current option list. For the TrendsAGI call itself, the API returns JSON on success and standard HTTP errors otherwise, so log the status and body together.

Step 5: MCP in both directions

Per vercel-docs.vercel.sh, @tanstack/ai-mcp connects TanStack AI to a Model Context Protocol server. That is the client direction: your agent gains tools hosted elsewhere, including a TrendsAGI MCP endpoint. In the other direction, createMCPServer in 1.0 serves TanStack tools as an MCP server for Claude Desktop, Cursor and other MCP hosts, so a tool you already wrote can be reused by desktop clients.

For a concrete server to point at, TrendsAGI runs a hosted MCP server at https://api.trendsagi.com/mcp (Streamable HTTP, read-only tools, API key as a Bearer token). Its tool names — list_trends, get_trend_ai_insights, get_trend_analytics, list_recommendations, list_crisis_events — map cleanly onto the tool-calling pattern above. If you would rather define tools locally, the Python SDK ships TrendsAGITools and a pip install "trendsagi[mcp]" server, which is a separate runtime from a TypeScript app but useful for testing what a tool should return.

Step 6: test before you trust

The release material mentions fakeText() and deterministic fixture-based tests, but no verified source here turns that into a worked step. The safe pattern is to unit-test your tool's execute function directly against a recorded TrendsAGI response, then test the route with a fake adapter. Confirm the fake-adapter API in the docs rather than inventing one.

Upgrading from 0.x

Three facts are verified. All stable @tanstack/ai* packages must move together because a 1.0 client needs a 1.0 server. The upgrade includes a jscodeshift codemod for AG-UI compliance renames. And the experimental harness packages remain on 0.x, which means your upgrade plan needs two lanes: stable packages to 1.x, harness packages pinned where they are until their own stable release. Run the codemod on a branch, then run a type check, then exercise one streaming route and one tool call end to end. The full upgrade text in the release post is truncated in the available material, so consult the live guide for the remaining steps.

When a gateway is worth it

A hosted gateway buys you model switching by ID and one credential surface; a direct provider adapter keeps one fewer network hop and one fewer account. Nothing in the verified sources states pricing, rate limits, quotas or SLAs for Vercel AI Gateway, Cloudflare AI Gateway, Lovable AI Gateway or TanStack AI itself, so a cost comparison cannot be made from these pages — gather that from each vendor's own terms. What can be said is structural: with 23 adapters plus openaiCompatible, TanStack AI does not force the decision at the code level, which is the point of the framework's positioning.

That is also where trend data helps. If you are choosing which model or gateway to standardise on, watching which integration topics are accelerating — gateway adapters, MCP, tool-calling patterns — gives you a signal that documentation alone cannot. TrendsAGI measures velocity as posts per hour from stored snapshots, not as a forecast or unique-user count, and recommendation confidence reflects evidence completeness rather than probability of success. Used honestly, it tells you where developer attention is moving, not what will succeed.

Frequently asked questions

How do I install TanStack AI 1.0 and wire chat() to an external model gateway instead of a direct provider key?

Install @tanstack/ai together with your UI binding and a gateway adapter such as @tanstack/ai-vercel-gateway, keeping every @tanstack/ai* package on the same 1.x version. Then pass the gateway adapter and a model ID to chat() in a server route and return the stream with toServerSentEventsResponse().

What is the minimum server route plus client hook setup for a streaming chat that actually runs?

One POST route that calls chat() and wraps the result in toServerSentEventsResponse(), plus a component that calls useChat({ api: "/api/chat" }) from @tanstack/ai-react. tanstack.com describes this as a roughly five-minute quick start once the API key is in place.

How do I define a tool with toolDefinition() and get a model to call it across multiple iterations?

Create the tool with toolDefinition(), giving it a name, description, JSON parameters and an execute function, then pass it in the tools array to chat(). Add maxIterations so the loop has a hard ceiling; confirm the exact call form in the reference docs before relying on it.

How do I connect an MCP server to TanStack AI and expose my own tools as an MCP server with createMCPServer?

@tanstack/ai-mcp connects TanStack AI to a Model Context Protocol server, per vercel-docs.vercel.sh, while createMCPServer in 1.0 does the reverse and serves your TanStack tools to Claude Desktop, Cursor and other MCP hosts.

What changed in 1.0 versus 0.x, and what does the upgrade codemod actually do?

1.0 stabilises the core APIs and adds an experimental agent harness, taking the project from one chat function and four providers to 23 adapters and eight UI frameworks. The codemod performs jscodeshift renames for AG-UI compliance; beyond that, the available upgrade text is truncated, so check the live guide.

Which parts are stable versus experimental, and what does that mean for production?

Core packages such as @tanstack/ai and @tanstack/ai-react are stable 1.x APIs; the agent harness packages are experimental and stay on 0.x. Build production chat, tools and streaming on the stable packages, and pin exact versions for anything experimental.

How we researched this

Prepared by TrendsAGI Research. Facts checked on 7 November 2026 against the sources listed below.

We read the official TanStack AI documentation listed below. The TrendsAGI steps and code use its documented REST API and Python SDK; confirm the TanStack AI side against its current documentation, since third-party products change.

Sources

• TanStack AI 1.0: Still Your AI, Still Your Way — tanstack.com
• TanStack AI with AI Gateway (Vercel) — vercel.com
• TanStack AI with MCP (Vercel) — vercel-docs.vercel.sh
• TanStack AI (React) SKILL.md (GitHub) — github.com

Try it with TrendsAGI

• Install the Python SDK with agent tools and the MCP server
• TrendsAGI API documentation
• More guides and trend analysis