Chat
Build a chat from the AI components, with the AI SDK or TanStack AI.
This guide builds a chat in four files: the chat itself, a message, a message's reasoning and a tool call. Replies stream in with their reasoning, tool calls and Markdown. Users can attach files, and stop, copy or retry a reply. Each step has a version for the AI SDK (opens in a new tab) and one for TanStack AI (opens in a new tab). Pick your library, and every step switches to match.
Installation
Add the components and your AI library, then a route for the chat to send its messages to.
useChat sends the conversation to /api/chat. Set up that route as the
AI SDK's docs (opens in a new tab) show. The route's
toUIMessageStreamResponse() sends the model's reasoning by default. Pass it sendSources: true to
also send the sources a reply used. To have replies cite those sources, ask the model in the system
prompt to cite each one as a numbered link to its URL, such as
[1](https://example.com/docs/rate-limits).
useChat sends the conversation to /api/chat, where chat() streams the reply back, as TanStack
AI's quick start (opens in a new tab) shows. Any
adapter works in place of Anthropic's.
chatParamsFromRequest reads the request that useChat sends. Pass its parentRunId and resume
on to chat() so that a reply paused for the person's approval continues once they answer.
reasoning asks the model to think first and streams its reasoning as thinking parts.
serverTools holds your tools' .server() implementations, made from the
tool definitions (opens in a new tab) in lib/tools.ts. The browser
needs those definitions too.
The chat
sendMessage takes files either as a FileList, which it reads into the message for you, or as
FileUIParts you've read yourself. PromptInput passes the attached files as an array, so
toFileList converts them to a FileList. sendAutomaticallyWhen resends the conversation once
the person answers a tool's approval request, so the model can continue.
useChat takes a connection to the route and the conversation's threadId. Chat receives the
threadId as a prop from the page that renders it. reload() regenerates the last reply.
sendMessage takes the person's text as a string, or a message whose content holds their text
and files as parts. toContent reads each attached file as base64 into an image part, or into a
document part for a PDF.
A tool call that needs approval pauses the reply with an interrupt. respond resolves the interrupt
for the call the person answered, and the reply continues once every interrupt is resolved.
useChat only accepts answers for tools it knows about, so pass it toolDefinitions from
lib/tools.ts: the definitions of the tools the route implements.
Each message is a ConversationItem. The person's messages are anchors that mark where each turn
starts, so a new question settles near the top and its reply fills in below it.
ConversationContent stays aria-busy while a reply arrives, so screen readers read the reply once
it's done rather than paragraph by paragraph. Not every screen reader waits for aria-busy, so
Conversation's usage also announces the finished reply in a
status region.
status drives the rest of the chat, and both libraries use the same status names.
PromptInput takes status as is and turns its submit button into a
stop button while a reply arrives. While status is submitted, before the reply's first part
arrives, a "Thinking" TraceLine holds the reply's place. While the chat is
busy, the last message is the one being written, so it's marked streaming. Only the last reply
can be regenerated, and only once the chat is ready again. If a reply fails, error is set, and
an error message offers to regenerate the reply.
Messages
The AI SDK starts each step with a step-start part and sends sources as separate parts. The loop
skips every part that's neither text nor a step, so these parts don't split a run of steps. Text
renders as Markdown, which streams while the part's state is
streaming.
Link turns a reply's numbered links into citations. It looks up
each link among the message's source-url parts, which SourcesContext passes down. Links that
aren't sources render as Markdown's own MarkdownLink. components is defined once, outside the
component, since Markdown renders the whole reply again whenever it receives a new components
object.
Text and thinking parts hold their text in content and have no state of their own. A part
streams while it's current: the last part of the message being written. Each tool call's result
arrives as a tool-result part after the call. The loop stores the result by its call's ID for
ToolCall, instead of letting it split a run of steps. File parts don't carry a file name, so the
person's message labels them by kind.
TanStack AI doesn't send the sources a reply used, so the reply's links stay plain links. To cite
sources, return them from the tool that finds them and look up the links in that tool's output, as
the AI SDK version does with its source-url parts.
The person's text goes in a Message bubble, and each of their files in an
outlined bubble. A reply's reasoning and tool calls are steps. Consecutive steps share a
Trace above the text they lead to, and only text ends a run of steps.
Once a reply is done, its footer has a Copy Button for its text, and a
button to regenerate the reply when Chat passes onRegenerate.
Reasoning
Copy the Reasoning component into components/reasoning.tsx. Its code is below the example in
Trace's Reasoning section.
Tool calls
toolState maps the AI SDK's tool states onto Tool's. A
call the AI SDK approves automatically shows as running, and a denied call shows as denied.
ToolApproval shows only while the call is waiting for the person's answer.
addToolApprovalResponse also takes a reason to tell the model why a call was denied.
toolState maps TanStack AI's tool states onto Tool's. A
call ends in error when it fails, and also when the person denies or stops it. In those two cases
the result has an outcome of denied or cancelled, so a result with an outcome shows as
denied. A call has its input only once the input is complete, so until then parsePartialJSON
parses the part of arguments that has arrived. ToolApproval shows only while the call is waiting
for the person's answer.
Here the title is the tool's name. Where you can, write your own title for each tool and state, such as "Ran pnpm build" or "Searched the docs", since screen readers don't announce the line's color and motion.