ai-sdk/usechat

27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

useChat message structure with tool calls

Each message returned by useChat contains a parts array where each part has a type property. Text content has type 'text' with a text property. Tool calls are represented with type prefixed as 'tool-' followed by the tool name (e.g., 'tool-getLocation', 'tool-getWeather'). Tool call parts can be stringified to JSON for display.

UI message structure for chat

UI messages have an id property and a parts array. Each part in the parts array contains a type field (e.g., 'text') and corresponding content field (e.g., text field for type 'text'). This structure is used both for sending messages via sendMessage and for rendering received messages.

useChat hook basic properties

The useChat hook from @ai-sdk/react returns the following properties: messages (array of message objects), input (current input value), handleInputChange (function to handle input changes), handleSubmit (function to submit messages), and error (optional error object with a message property).

sendMessage method parameters

The sendMessage method returned from useChat accepts an object with a text property containing the message text to send. Example: sendMessage({ text: input }).

useChat hook return value structure

The useChat hook returns an object with a messages property (array of message objects) and a sendMessage method. The messages array contains message objects with properties including id, role, and parts array. Each part in the parts array has a type property (e.g., 'text') and content properties like text.

Chat class and DefaultChatTransport

The Chat class is imported from '@ai-sdk/react' and accepts a transport option. DefaultChatTransport is used to specify the API endpoint: new Chat({ transport: new DefaultChatTransport({ api: '/api/chat' }) }).

Message object structure in useChat

Message objects returned from useChat contain an id property (string), a role property (either 'user' or 'assistant'), and a parts array. Each part has a type property and content properties; for text parts, there is a text property containing the message content.

Chat instance sharing between components

The same Chat instance can be shared between multiple components to maintain synchronized state. This allows splitting functionality like a form and chat messages into separate components while keeping their state synchronized.

useChat hook with throttle option

The useChat hook accepts a chat instance and a throttle option. The throttle option accepts a number value in milliseconds to throttle data updates to a specified interval. Example: useChat({ chat, throttle: 50 }) throttles updates to 50 milliseconds to manage rendering performance.

File conversion to data URLs for chat messages

Files can be converted to data URLs using FileReader.readAsDataURL(). Each file object in the parts array should have the structure: { type: 'file'; filename: string; mediaType: string; url: string }.

Message parts structure with text and files

Messages sent via sendMessage can contain multiple parts in an array. Text parts have { type: 'text', text: string }. File parts have { type: 'file', filename: string, mediaType: string, url: string }.

DefaultChatTransport configuration

DefaultChatTransport is initialized with an api parameter pointing to the route handler endpoint (e.g., '/api/chat').

useChat hook file attachment support

The useChat hook from @ai-sdk/react supports sending files alongside messages. Files are included in the parts array with type 'file', containing filename, mediaType, and url properties as data URLs.

Client component manages conversation state with useState

A client component can maintain conversation state using useState hook to store an array of Message objects. When a message is sent, it calls a server action passing the updated conversation history, receives the response, and updates the local state with the new messages.

Chat context provider pattern with useChat

Create a Chat context using React's createContext to hold a Chat<UIMessage> instance and provide methods like clearChat(). Wrap your app with ChatProvider in the layout to make the chat context available to all child components. Components access the shared context using useSharedChatContext() hook.

DefaultChatTransport API endpoint configuration

DefaultChatTransport accepts an api parameter that specifies the endpoint URL for chat operations. Example: new DefaultChatTransport({ api: '/api/chat' }).

useChat hook parameters and return values

useChat accepts a chat object as parameter. It returns messages array, status string, stop function, and sendMessage function. The status can be 'ready', 'submitted', or 'streaming'. sendMessage accepts an object with a text property.

UIMessage structure and message parts

UIMessage objects contain id, role, and parts properties. Parts is an array where each part has a type property. Text parts have type 'text' and a text property containing the message content.

Chat class generic type parameter

The Chat class accepts a generic type parameter specifying the message type. Example: Chat<UIMessage> for standard UI messages. This type is used throughout context and hook interactions.

useChat prepareSendMessagesRequest option customizes request body

The prepareSendMessagesRequest option in useChat allows you to customize the entire body content sent to the server. The function receives the message list, the request data, and the request body from the append call, and returns the body content that will be sent to the server.

DefaultChatTransport accepts prepareSendMessagesRequest parameter

DefaultChatTransport is initialized with an object containing the prepareSendMessagesRequest function to customize request body serialization.

useChat prepareSendMessagesRequest example sends only last message

This example demonstrates how to use prepareSendMessagesRequest to send only the last message to the server instead of all messages, reducing data sent. The function returns an object with a body property containing id and the last message from the messages array.

useChat message parts array has type and text properties

Messages from useChat contain a parts array where each part has a type property (e.g., 'text') and a text property containing the message content.

useChat hook with DefaultChatTransport

The useChat hook from @ai-sdk/react accepts a transport parameter configured with DefaultChatTransport. The DefaultChatTransport takes an api property pointing to the endpoint (e.g., '/api/chat'). The hook returns messages, sendMessage, and addToolOutput. It accepts a sendAutomaticallyWhen parameter that controls when messages are automatically sent, such as lastAssistantMessageIsCompleteWithToolCalls.

onToolCall handler in useChat

The useChat hook accepts an onToolCall handler that receives an object with a toolCall property. The toolCall contains toolName and toolCallId. The handler can call addToolOutput without await to avoid potential deadlocks, passing an object with tool (the tool name), toolCallId, and output properties.

Message parts structure for tools in useChat

Messages from useChat contain a parts array where each part has a type property. Tool parts have types like 'tool-askForConfirmation', 'tool-getWeatherInformation', and 'tool-getLocation'. Each tool part contains toolCallId, state (such as 'output-available'), and output properties that contain the tool's return value.

Rendering tool outputs in chat UI

Tool outputs can be rendered as visual React components by switching on part.type values like 'tool-getWeatherInformation'. When part.state is 'output-available', the part.output contains the structured tool result that can be used to render custom JSX components displaying weather data, confirmations, or other visual information.

Give your agent this brain