TanStack AI 1.0 Guide: Upgrade, Build Agents, and Set Safe Boundaries

TanStack AI 1.0 is the first stable release of the open-source TypeScript toolkit for building streaming chat, tool calls, media features, MCP servers, and agents. The important detail is the boundary: the core APIs are stable at 1.0, while the new Agent Harness remains experimental.

That distinction should shape your rollout. A new application can start with the stable chat and tool stack. A 0.x application should upgrade all stable packages together, fix the required thread identifiers, and migrate stored data before deployment. A coding-agent harness belongs in a separate branch and sandbox until its behavior and changing APIs fit your operational requirements.

Quick take

Upgrade the stable @tanstack/ai* packages together.
A 1.0 client needs a compatible 1.0 server.
Supply a stable threadId in both browser and server code.
@tanstack/ai-harness and its CLI are still 0.x experimental packages.
The permissions plugin creates approval rules. It is not a sandbox.

What became stable, and what did not

According to the launch post, TanStack AI now covers 23 provider adapters plus an OpenAI-compatible adapter, multiple UI frameworks, tools, media, persistence, MCP, testing helpers, and model-independent options behind a typed interface. The ordinary product path built around chat(), a server route, and a framework hook is the 1.0 foundation.

The Agent Harness is a separate orchestration layer for conversations that remain open, accept new input while work is running, wait for approvals, launch typed agents, and recover work after a restart when durable persistence is configured. It is useful, but the packages remain on 0.x and may change in a minor release.

Area	Stable 1.0 core	Experimental Agent Harness
Primary job	Chat, tools, media, MCP, and UI connections	Long-lived sessions, waits, subagents, and background work
Version promise	1.0 compatibility baseline	0.x and subject to change
Recommended rollout	Default choice for new product features	Pilot branch, restricted users, isolated execution

Responsibility boundary between the stable TanStack AI 1.0 core and the experimental Agent Harness — The experimental harness sits above the stable core, while human approval and sandboxing remain separate safety boundaries.

What to prepare before you install

A supported Node.js project and a rollback branch. Do not change the production branch first. Keep the lockfile and stored-data backup available.
A provider adapter. The examples below use @tanstack/ai-openai. Choose the matching adapter if your application uses another provider.
Server-side secrets. Keep provider keys in the server environment or a dedicated secrets store, not in the browser bundle. Follow the separate BYOK guide if users supply their own keys.
A durable conversation identifier. TanStack AI 1.0 requires you to pass threadId. Use an ID from your route or database rather than generating a new one during every render.
A permission and isolation plan. Decide whether the feature needs reads, writes, shell commands, or network access. Prepare a sandbox before running unfamiliar repositories or untrusted code.

Start a new 1.0 streaming chat

1. Install compatible packages together

npm i @tanstack/ai @tanstack/ai-react @tanstack/ai-openai

Swap the React package for Vue, Svelte, Solid, or another supported UI package when necessary. Keep the core, client, UI, and provider packages on compatible versions.

2. Stream from the server route

const { messages, threadId, runId } = await chatParamsFromRequest(request)
const stream = chat({
  adapter: openaiText('YOUR_MODEL_ID'),
  messages,
  threadId,
  runId,
})
return toServerSentEventsResponse(stream)

The official quick start reads the request on the server, calls chat(), and returns Server-Sent Events. Replace the placeholder with a model that your selected adapter currently supports. The provider key should be read at runtime on the server.

3. Reuse the same thread in the client

const chat = useChat({
  connection: fetchServerSentEvents('/api/chat'),
  threadId: chatId,
})

A random ID created inside the component breaks continuity. Use a route parameter or a conversation record that survives navigation and reconnection.

4. Verify the result

The response should arrive incrementally, and Stop should cancel the active run.
The browser request and bundle must not expose the provider key.
Reloading the page should reuse the intended threadId.
If you add tools, distinguish read-only calls from writes and test the approval path.

Upgrade a 0.x application in five steps

The migration is not finished when TypeScript compiles. If the application stores conversations, runs, or files, follow the saved-data migration before deployment.

Five-step process in the official TanStack AI Upgrade to 1.0 documentation — TanStack AI’s official Upgrade to 1.0 sequence, checked October 26, 2026.

Preview the codemod. Add --dry --print first so you know which files and calls will change.
Run the codemod. It handles common renames, including chat-level body to forwardedProps and conversationId to threadId.
Upgrade stable packages together. Do not pair a 1.0 client with a 0.x server. The old @tanstack/ai-react-ui, solid-ui, and vue-ui packages do not have 1.0 releases, so move to the current UI entry points.
Fix manual changes and type errors. A codemod cannot choose the correct threadId value. Approval handling also moves from addToolApprovalResponse() to methods on the current interrupt object.
Migrate data and completion events. Apply the documented saved-data steps. A custom stream server should end a run with RUN_FINISHED rather than sending [DONE].

Use the Agent Harness with explicit boundaries

A harness is defined once with defineHarness(), and a host opens a session for each thread. It supports queued input, a steer message that joins active work before the next model call, follow-up work, typed agents, plugins, and waits for a person. The in-memory persistence shown in introductory examples disappears with the process. Durable recovery requires an appropriate store and an understanding of the documented recovery limits.

The coding-agent guide combines permissions(), workspaceTools(), snapshots, todos, project instructions, and usage tracking. This is a useful starting point, but the documentation is explicit: the permissions plugin is not a sandbox. Its tools run on the host with the current user’s operating-system permissions.

Begin in read-only plan mode and ask for a change plan before allowing edits.
Limit writes to a dedicated branch and a narrow workspace root.
Use persistent “always allow” decisions only for tightly scoped, repeatable operations.
Deny deployment, destructive commands, and secret access unless the workflow genuinely requires them.
Run unfamiliar code and third-party repositories in a supported sandbox. Install Codex, Claude Code, or another agent CLI inside that sandbox rather than on the host.
Review /undo, Git diff, tests, and command output before merging.

Three practical ways to apply the release

1. Move a support chat onto the stable core

Goal: replace provider-specific streaming code with a typed adapter boundary. Inputs: a stable conversation ID, server-side credentials, and existing cancellation and error requirements. Flow: wrap the server call with chat(), send the same threadId from the client, and add read-only lookup tools before any write tool. Review: cancellation, reconnect behavior, error responses, and sensitive data in logs. This use case usually does not need the experimental harness.

2. Expose an internal lookup tool as an MCP server

Goal: let Claude Desktop, Cursor, or another MCP host call an existing TanStack server tool. Inputs: a validated input schema, user authentication, and a read-versus-write classification for each tool. Flow: create an HTTP route with createMCPServer(). Mark read-only behavior with readOnlyHint and external access with openWorldHint when applicable. Review: invalid argument rejection, authentication failure, server logs, and confirmation before writes. Do not expose the route publicly without an authentication plan.

3. Pilot a coding-agent harness in one repository

Goal: measure whether long-running work, subagents, approvals, and usage tracking fit the team. Inputs: a disposable clone, a sandbox, a test command, blocked paths, and a budget. Flow: request a read-only plan, approve one small change, then inspect tests and the diff manually. Evaluation: count approval friction, recovery quality, session resume behavior, and unexpected file access rather than judging only the generated code. Keep the experimental API outside the critical production path.

Cost, security, and operations checklist

TanStack AI does not remove model, sandbox, or storage charges. Check the terms of each provider you select.
The harness usage() plugin can report tokens and cost when the provider supplies the relevant data, but providers do not all report cost in the same way.
Keep API keys in server or sandbox secret storage. Do not leave them in logs, client state, snapshots, or committed environment files.
Give MCP tools accurate read-only, destructive, idempotent, and open-world annotations.
For durable sessions, document retention, tenant access, deletion, takeover, and restart recovery behavior.

Troubleshooting in the right order

Every message starts a new conversation

Log the threadId on both sides and verify that the values match. Look for IDs generated on every render, a server route that discards the ID, and remaining conversationId calls.

The 1.0 upgrade produces a large number of type errors

Confirm that all stable @tanstack/ai* packages are on compatible 1.0 versions. Compare the codemod in dry-run mode. Calls imported through a barrel file may not be transformed automatically, so search for them manually. Remove the old standalone UI packages.

A tool does not resume after approval

Check that the application resolves the matching item in the current interrupts collection rather than calling the removed approval helper. If several waits exist, match every response to the correct interrupt ID.

The agent requests an unexpected file or command

Stop the run. Check the workspace root, the last matching permission rule, and whether the session is in plan, acceptEdits, or bypass mode. Move untrusted work into a sandbox instead of retrying with broader host permissions.

Bottom line

TanStack AI 1.0 is useful because it draws a clearer line between the stable pieces you can build a product on and the experimental orchestration layer you should still pilot carefully. Start new applications with streaming chat and narrowly scoped tools. For an existing 0.x application, run the codemod, update stable packages together, supply a correct threadId, and migrate stored data. Treat approvals, snapshots, and sandboxing as separate controls when you evaluate the Agent Harness.

한국어 버전으로 읽기

Official sources

Sources checked October 26, 2026.

Search This Blog

Stackfinch