TanStack AI 1.0: Chat Agent with Tools and a Sandbox

What TanStack AI 1.0 actually is

TanStack AI 1.0 is the first stable release of TanStack's AI toolkit, shipped in October 2026, according to tanstack.com's release post "TanStack AI 1.0: Still Your AI, Still Your Way." It grew from a single chat() function into a toolkit spanning chat, tools, media, MCP, persistence, sandboxes and agents. The 1.0 release stabilizes the core APIs and adds an experimental agent harness on top, plus subagents, compaction, portable Agent Skills, createMCPServer and fakeText() testing.

For the query you typed — building a chat agent with tools and a sandbox provider in TanStack AI 1.0 — the practical shape is this: install the 1.0 packages together, define a tool, call it inside chat() from a server route, point the agent at one of the 11 sandbox providers, and test with fakeText() before you spend a single token. Everything below uses only capabilities documented by tanstack.com, the OpenRouter integration page, the Vercel AI Gateway page and the @tanstack/ai API docs on GitHub, plus TrendsAGI's own documented API for live trend data.

One honesty note up front: the sandbox provider list and many harness APIs are named in aggregate, not documented item by item on the pages above. Where this tutorial says "confirm in the docs," that is a real instruction, not hedging.

What is verified about TanStack AI 1.0 — and what is not

Verified on the cited sources

• 1.0 shipped in October 2026 with stable core APIs and a new experimental agent harness (tanstack.com).
• 23 provider adapters, plus openaiCompatible for any OpenAI-style API (tanstack.com).
• Nine UI frameworks: React, Vue, Solid, Svelte, Preact, Angular, Octane, Remix and vanilla JS (tanstack.com).
• 11 sandbox providers, including newly added Blaxel, Upstash Box, E2B, boxd and Railway (tanstack.com).
• Coding agent support for Claude Code, Codex, OpenCode, Grok Build and any ACP agent (tanstack.com).
• A 1.0 client requires a 1.0 server, so stable @tanstack/ai* packages must be upgraded together (tanstack.com).
• Experimental harness packages remain on 0.x versions (tanstack.com).
• A jscodeshift codemod applies the most common renames automatically (tanstack.com).
• createMCPServer serves TanStack tools as an MCP server for Claude Desktop, Cursor and other MCP hosts (tanstack.com).
• fakeText() tests chat(), tools and middleware with no network and no API key (tanstack.com).
• The OpenRouter adapter installs as @tanstack/ai-openrouter and gives access to 400+ models through one unified API (openrouter.ai).
• The Vercel AI Gateway adapter installs as @tanstack/ai-vercel-gateway and requires Node.js 22 or later (vercel.com).

Not stated on the cited sources

No pricing, rate limits, quotas, SLAs or support commitments appear on these pages. The 23 adapters and 11 sandbox providers are named in aggregate; only the five newcomer sandboxes are called out by name. There are no latency or reliability benchmarks between sandboxes, and the pages do not state whether the experimental harness is production-recommended. Treat all of that as "confirm in TanStack's own docs and each provider's docs."

Step 1: Install a version-locked 1.0 stack

The single hardest rule in 1.0 is the client/server lock: a 1.0 client requires a 1.0 server. Do not mix a fresh client package with an old server dependency. Upgrade every stable @tanstack/ai* package in the same pass, and keep the harness packages separate because they remain on 0.x.

# stable 1.0 core + one provider adapter + one sandbox provider (names illustrative; confirm exact package names in the @tanstack/ai API docs on GitHub)
npm install @tanstack/ai@1 @tanstack/ai-openrouter@1

# experimental harness: intentionally on 0.x per tanstack.com
npm install @tanstack/ai-harness@0

If you prefer the Vercel AI Gateway route, swap the adapter for @tanstack/ai-vercel-gateway and make sure you are on Node.js 22 or later, as vercel.com states. The OpenRouter adapter is documented by openrouter.ai as the single-API path to 400+ models, which makes it a reasonable first choice when you want to A/B model behavior inside the same tool definitions.

Step 2: Define a tool and let chat() call it from a server route

Tool calling is the core of the 1.0 chat agent, and the shape is stable API territory rather than harness territory. Define the tool with a name, a described input, and an execute function, then pass it into chat() inside your server route. The API docs on GitHub are the authority for exact signatures.

// server/trend-tool.ts — illustrative shape; verify exact imports and signatures in the @tanstack/ai API docs
import { tool } from "@tanstack/ai";

export const topTrends = tool({
  name: "top_trends",
  description: "List live topics gaining attention right now, sorted by velocity.",
  input: { category: "string", limit: "number" },
  execute: async ({ category, limit }) => {
    const params = new URLSearchParams({
      sort_by: "velocity",
      limit: String(limit ?? 5),
    });
    if (category) params.set("category", category);
    const res = await fetch(
      `https://api.trendsagi.com/api/trends?${params}`,
      { headers: { "X-API-Key": process.env.TRENDSAGI_API_KEY! } }
    );
    return res.json();
  },
});

Then wire it into the route:

// server/chat.ts — illustrative server route
import { chat } from "@tanstack/ai";
import { openrouter } from "@tanstack/ai-openrouter";
import { topTrends } from "./trend-tool";

export async function POST(request: Request) {
  const { messages } = await request.json();
  return chat({
    adapter: openrouter({ apiKey: process.env.OPENROUTER_API_KEY! }),
    messages,
    tools: [topTrends],
  });
}

Because the tool returns TrendsAGI's real REST response, the agent is answering from measured snapshot data, not from a stale training set. TrendsAGI documents velocity as a measured posts-per-hour rate from stored snapshots, not a forecast or a unique-user count — worth repeating to your agent in the tool description so it does not overstate what it has.

Step 3: Connect a sandbox provider

TanStack AI 1.0 supports 11 sandbox providers, and tanstack.com names five added since the release candidate: Blaxel, Upstash Box, E2B, boxd and Railway. A sandbox is where agent-generated work runs, so the choice matters more than the adapter choice for operational risk.

There is no verified ranking of these providers. The cited pages give no latency, reliability or cost comparisons, so any "best sandbox" list you read — including one written by us — would be invented. Build your own shortlist from your constraints:

• Existing infrastructure. If your team already runs on one of these platforms, the operator burden is lower. Confirm the exact package name for that provider in the API docs first.
• Cold-start and execution model. Ask the provider directly; TanStack's pages do not document it.
• Data boundary. Sandboxes run agent output. Decide what your tool calls are allowed to return before you pick a runner.
• Escape hatch. Keep sandbox-specific calls behind one thin module so replacing a provider is a one-file change.

To connect one, install its provider package alongside the stable core and pass it where the API docs specify for your route. Confirm the constructor options and lifecycle hooks in the @tanstack/ai docs, because sandbox wiring is one of the areas the release post describes but does not demonstrate.

Step 4: Add MCP, subagents and long-running behavior

Three 1.0 features matter once the basic loop works. createMCPServer serves your TanStack tools as an MCP server for Claude Desktop, Cursor and other MCP hosts, so the same tool definitions you wrote in Step 2 become reusable outside your app. Subagents and compaction are harness features: subagents split work across narrower agents, and compaction keeps a long-running agent's context from growing without bound. Portable Agent Skills let you package reusable agent capabilities.

Here the version boundary bites. tanstack.com states the experimental harness packages remain on 0.x versions. That means harness imports, subagent wiring and compaction options can change between minor releases, and the release page does not say they are production-recommended. Pin harness versions exactly, put them behind your own interface, and keep the stable chat/tools path working independently so a harness change cannot take down your product.

# pin the experimental layer exactly; stable packages stay on 1.x
npm install @tanstack/[email protected] --save-exact

Step 5: Upgrade an existing 0.x app to 1.0

The 1.0 upgrade path includes a jscodeshift codemod that applies the most common renames automatically, per tanstack.com. A practical sequence:

1. Freeze feature work and branch.
2. Install the stable @tanstack/ai* packages at 1.x together — client and server in the same commit. The 1.0 client requires a 1.0 server.
3. Run the codemod to apply renames, then read the diff by hand; codemods cannot see dynamic imports or custom wrappers.
4. Keep harness packages on 0.x deliberately, pinned, and isolated behind your own module.
5. Deploy client and server atomically. No staged rollout that leaves a 0.x server behind a 1.0 client.

Step 6: Test with fakeText() before spending a token

fakeText() lets you test chat(), tools and middleware with no network and no API key, according to tanstack.com. This is the cheapest place to catch a broken tool schema or a middleware ordering mistake. Write one test per tool that asserts the tool is selected for an obvious prompt and returns a shape your UI can render, and one test that asserts a tool error is surfaced rather than swallowed. Run those in CI on every pull request.

Where TrendsAGI fits alongside your agent

Two integrations are worth building once the agent runs. First, as shown in Step 2, expose TrendsAGI's GET /api/trends as a tool — sorted by velocity, growth, volume or timestamp, filtered by category or search. Second, add GET /api/insights/search?q=... or keyThemeContains=... as a second tool so the agent can retrieve the AI-written summary, key themes, sentiment and audience notes for a specific trend rather than re-deriving them. If you want the agent to react instead of poll, subscribe a webhook with trend_velocity or trend_category triggers and verify the X-Webhook-Signature HMAC against the raw body. For sandbox selection specifically, GET /api/trends/{id}/analytics?period=24h|7d|30d on trend IDs you have watchlisted gives you a measured adoption signal instead of guesswork about which provider is gaining attention.

Frequently asked questions

Which packages do I install for a 1.0 chat agent with tools, and which harness packages stay on 0.x?

Install the stable @tanstack/ai core plus one adapter — @tanstack/ai-openrouter or @tanstack/ai-vercel-gateway — all at 1.x together. The experimental agent harness packages remain on 0.x versions, so pin them exactly and keep them separate from the stable stack.

How do I define a tool and let the agent call it inside chat() from a server route?

Define the tool with a name, a described input and an execute function, then pass it in the tools array of the chat() call inside your server route. Confirm the exact import and argument names in the @tanstack/ai API docs on GitHub before you ship.

How do I connect a sandbox provider like E2B, Blaxel, Upstash Box, boxd or Railway?

Install the sandbox provider's package alongside the stable 1.0 core and pass it where the API docs specify for your route. TanStack's release page names these five as newly added to the 11 supported providers but does not document per-provider setup, so confirm constructor options in the provider's own docs.

How do I add subagents, portable Agent Skills or compaction to a long-running agent?

These are experimental harness features introduced in 1.0, and the harness packages remain on 0.x. Pin the harness version exactly, wrap it behind your own interface, and check the docs before relying on it for anything user-facing.

How do I upgrade an existing 0.x app to 1.0 without breaking client/server compatibility?

Upgrade every stable @tanstack/ai* package to 1.x in a single commit, because a 1.0 client requires a 1.0 server, then run the jscodeshift codemod and review the diff manually. Deploy client and server together.

How do I test tools and middleware locally with fakeText() and no API key?

Use fakeText() to exercise chat(), tools and middleware with no network and no API key. Assert tool selection and output shape for each tool, and run those tests in CI so schema regressions are caught before deployment.

How we researched this

Prepared by TrendsAGI Research. Facts checked on 2 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 Integration - OpenRouter SDK Support — openrouter.ai
• TanStack AI with AI Gateway (Vercel) — vercel.com
• @tanstack/ai API docs (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