Introducing type-safe chat and agentic loop control for full-stack AI applications
With over 2 million weekly downloads, the AI SDK is the leading open-source AI application toolkit for TypeScript and JavaScript. Its unified provider API allows you to use any language model and enables powerful integrations into leading web frameworks.
“When customers ask how they should build their agents, I always say the AI SDK. The industry is moving really fast and everything is changing constantly. The AI SDK is the only perfect abstraction I've seen so far. v5 continues that track record. You can tell it was built by people that are obsessed with Typescript. Everything feels right.When customers ask how they should build their agents, I always say the AI SDK. The industry is moving really fast and everything is changing constantly. The AI SDK is the only perfect abstraction I've seen so far. v5 continues that track record. You can tell it was built by people that are obsessed with Typescript. Everything feels right.”
Ben Hylak, raindrop.ai
Building applications with TypeScript means building applications for the web. Today, we are releasing AI SDK 5, the first AI framework with a fully typed and highly customizable chat integration for React, Svelte, Vue and Angular.
With AI SDK 5, we've rebuilt chat from the ground up. We took the powerful primitives that developers love for working with LLMs and built a world-class UI integration on top, with end-to-end type safety across your entire application. From server to the client, every piece of data, tool call, and metadata is fully typed. This represents the next evolution of AI libraries for the web.
One of the biggest challenges developers faced with previous versions of the AI SDK was managing different message types and figuring out how to properly persist chat history.
This was a core consideration in rebuilding useChat, which led to the creation of distinct types of messages:
UIMessage: This is the source of truth for your application state, containing all messages, metadata, tool results, and more. We recommend using UIMessages for persisting so that you can always restore the correct user-facing chat history.
ModelMessage: This is a streamlined representation optimized for sending to language models.
We've made this distinction explicit in the API:
// Explicitly convert your UIMessages to ModelMessages
// Convert the rich UIMessage format to ModelMessage format
// This can be replaced with any function that returns ModelMessage[]
messages: modelMessages,
});
// When finished: Get the complete UIMessage array for persistence
return result.toUIMessageStreamResponse({
originalMessages: uiMessages,
onFinish:({ messages, responseMessage })=>{
// Save the complete UIMessage array - your full source of truth
saveChat({ chatId, messages });
// Or save just the response message
saveMessage({ chatId, message: responseMessage })
},
});
This separation between UI and model messages makes persistence straightforward. The onFinish callback provides all your messages in the format needed to save, with no explicit conversion required.
With AI SDK 5, you can customize the UIMessage to create your own type with the exact shape of your data, tools, and metadata, that is tailored to your application. You can pass this type as a generic argument to createUIMessageStream on the server and to useChat on the client, providing full-stack type-safety.
Modern AI applications need to send more than just an LLM's plain-text response from the server to the client (e.g. anything from status updates to partial tool results). Without proper typing, streaming custom data can turn your frontend into a mess of runtime checks and type assertions. Data parts solve this by providing a first-class way to stream any arbitrary, type-safe data from the server to the client, ensuring your code remains maintainable as your application grows.
On the server, you can stream a data part by specifying your part type (e.g. data-weather) and then passing your data. You can update the same data part by specifying an ID:
// On the server, create a UIMessage stream
// Typing the stream with your custom message type
On the client, you can then render this specific part. When you use the same ID, the AI SDK replaces the existing data part with the new one:
// On the client, data parts are fully typed
const{ messages }=useChat<MyUIMessage>();
{
messages.map(message=>
message.parts.map((part, index)=>{
switch(part.type){
case'data-weather':
return(
<divkey={index}>
{/* TS knows part.data has city, status, and optional weather */}
{part.data.status ==='loading'
?`Getting weather for ${part.data.city}...`
:`Weather in ${part.data.city}: ${part.data.weather}`}
</div>
);
}
}),
);
}
There are also instances where you want to send data that you do not want to persist, but use to communicate status updates, or make other changes to the UI - this is where transient data parts and the onData hook comes in.
Transient parts are sent to the client but not added to the message history. They are only accessible via the onData useChat handler:
// server
writer.write({
type:'data-notification',
data:{ message:'Processing...', level:'info'},
transient:true,// Won't be added to message history
Tool invocations in useChat have been redesigned with type-specific part identifiers. Each tool now creates a part type like tool-TOOLNAME instead of using generic tool-invocation parts.
AI SDK 5 builds on this foundation with three improvements:
Type Safety: By defining your tools' shape within your custom message type, you get end-to-end type safety for both input (your tools' inputSchema) and output (your tools' outputSchema).
Automatic Input Streaming: Tool call inputs now stream by default, providing partial updates as the model generates them.
Explicit Error States: tool execution errors are limited to the tool and can be resubmitted to the LLM.
Together, these features enable you to build maintainable UIs that show users exactly what's happening throughout the tool execution process—from initial invocation through streaming updates to final results or errors:
// On the client, tool parts are fully typed with the new structure
const{ messages }=useChat<MyUIMessage>();
{
messages.map(message=>(
<>
{message.parts.map(part=>{
switch(part.type){
// Static tools with specific (`tool-${toolName}`) types
The chat also supports dynamic tools (more below). Dynamic tools (e.g. tools from MCP server) are not known during development and can be rendered using the dynamic-tool part:
For information about a message, such as a timestamp, model ID, or token count, you can now attach type-safe metadata to a message. You can use it to attach metadata that is relevant to your application.
To send metadata from the server:
// on the server
const result =streamText({
/* ... */
});
return result.toUIMessageStreamResponse({
messageMetadata:({ part })=>{
if(part.type==="start"){
return{
// This object is checked against your metadata type
model:"gpt-4o",
};
}
if(part.type==="finish"){
return{
model: part.response.modelId,
totalTokens: part.totalUsage.totalTokens,
};
}
},
});
You can then access it on the client:
// on the client
const{ messages }=useChat<MyUIMessage>();
{
messages.map(message=>(
<divkey={message.id}>
{/* TS knows message.metadata may have model and totalTokens */}
The new useChat hook has been redesigned with modularity at its core, enabling three powerful extensibility patterns:
Flexible Transports: Swap out the default fetch-based transport for custom implementations. Use WebSockets for real-time communication or connect directly to LLM providers without a backend for client-only applications, browser extensions, and privacy-focused use cases. To learn more, check out the transport documentation.
Decoupled State Management: The hook's state is fully decoupled, allowing seamless integration with external stores like Zustand, Redux, or MobX. Share chat state across your entire application while maintaining all of useChat's powerful features.
Framework-Agnostic Chat: Build your own chat hooks for any framework using the exposed AbstractChat class. Create custom integrations while maintaining full compatibility with the AI SDK ecosystem.
AI SDK 5 brings the redesigned chat experience to every major web framework. Vue and Svelte now have complete feature parity with React, and we've introduced support for Angular.
All frameworks now get the same powerful features: custom message types for your application's specific needs, data parts for streaming arbitrary typed data, fully typed tool invocations with automatic input streaming, and type-safe message metadata. Whether you're using useChat in React, Vue's composition API, Svelte's stores, or Angular's signals, you're working with the same powerful primitives and end-to-end type safety.
The AI SDK now uses Server-Sent Events (SSE) as its standard for streaming data from the server to the client. SSE is natively supported in all major browsers and environments. This change makes our streaming protocol more robust, easier to debug with standard browser developer tools, and simpler to build upon.
Building reliable AI agents requires precise control over execution flow and context. With AI SDK 5, we're introducing primitives that give you complete control over how your agents run and what context and tools they have at each step.
AI SDK 5 introduces three features for building agents:
stopWhen: Define when a tool-calling loop is stopped.
prepareStep: Adjust the parameters for each step
Agent Abstraction: Use generateText and streamText with predefined settings
When you make a request with the generateText and streamText, it runs for a single step by default. The stopWhen parameter transforms your single request into a tool-calling loop that will continue until:
The stopWhen condition is satisfied, or
The model generates text instead of a tool call (always a stopping condition)
Common stopping conditions include:
Step limit: stepCountIs(5) - run for up to 5 steps
Specific tool: hasToolCall('finalAnswer') - stop when a particular tool is called
The Agent class provides an object-oriented approach to building agents. It doesn't add new capabilities - everything you can do with Agent can be done with generateText or streamText. Instead, it allows you to encapsulate your agent configuration and execution:
system:"You are a coding agent. You specialise in Next.js and TypeScript.",
stopWhen:stepCountIs(10),
tools:{
/* Your tools */
},
});
// Calls `generateText`
const result = codingAgent.generate({
prompt:"Build an AI coding agent.",
});
// Calls `streamText`
const result = codingAgent.stream({
prompt:"Build an AI coding agent.",
});
Link to headingExperimental Speech Generation & Transcription
AI SDK 5 extends our unified provider abstraction to speech. Just as we've done for text and image generation, we're bringing the same consistent, type-safe interface to both speech generation and transcription. Whether you're using OpenAI, ElevenLabs, or DeepGram, you work with the same familiar API pattern, and can switch providers with a single line change.
AI SDK 5 enhances tool capabilities with comprehensive improvements including dynamic tools, provider-executed functions, lifecycle hooks, and type-safety throughout the tool calling process.
In AI SDK 5, we've aligned our tool definition interface more closely with the Model Context Protocol (MCP) specification by renaming key concepts:
parameters → inputSchema: This rename better describes the schema's purpose of validating and typing the tool's input.
result → output: Similarly, tool outputs are now consistently named.
AI SDK 5 also introduces an optional outputSchema property, which aligns with the MCP specification and enables type-safety for client-side tool calling.
These changes make tool definitions more intuitive and consistent with emerging industry standards:
AI applications often need to work with tools that can't be known in advance:
MCP (Model Context Protocol) tools without schemas
User-defined functions loaded at runtime
External tool providers
Dynamic tools and the dynamicTool function enables tools where input and output types are determined at runtime rather than at development time. Dynamic tools are separated from static tools to give you type safety and flexibility at the same time.
import{ dynamicTool }from'ai';
import{ z }from'zod';
const customDynamicTool =dynamicTool({
description:'Execute a custom user-defined function',
inputSchema: z.object({}),
// input is typed as 'unknown'
execute:asyncinput=>{
const{ action, parameters }= input as any;
// Execute your dynamic logic
return{
result:`Executed ${action} with ${JSON.stringify(parameters)}`,
Many AI providers have introduced provider-executed tools. When these tools are called, the provider will execute the tool and send back the tool result as part of the response (e.g. OpenAI’s web search and file search, xAI’s web search, and more).
The AI SDK now natively supports provider-executed tools, automatically appending the results to the message history without any additional configuration.
AI SDK 5 introduces granular tool lifecycle hooks (onInputStart, onInputDelta, onInputAvailable) that can be paired with data parts for sending input-related information (e.g. status updates) back to the client.
AI SDK 5 adds support for tool-level provider options. You can use this to, for example, cache tool definitions with Anthropic for multi-step agents, reducing token usage, processing time, and costs:
const result =awaitgenerateText({
model:anthropic('claude-3-5-sonnet-20240620'),
tools:{
cityAttractions:tool({
inputSchema: z.object({ city: z.string()}),
// Apply provider-specific options to individual tools
The foundation of the AI SDK is the specification layer, which standardizes how different language models, embeddings models, etc. plug into functions such as streamText . The specification layer enables the provider architecture of the AI SDK.
In AI SDK 5, we have updated all specifications to V2. These new specifications incorporate changes in the underlying API capabilities (like provider-executed tools) and have extensibility mechanisms such as provider metadata and options. They will serve as the foundation for AI SDK 5 and beyond.
When you need full control or want to implement new features before they're officially supported, the AI SDK provides complete access to raw request and response data. This escape hatch is invaluable for debugging, implementing provider-specific features, or handling edge cases.
AI SDK 5 includes breaking changes that remove deprecated APIs. We've made the migration process easier with automated migration tools. You can run our automated codemods to handle some of the changes.
npx @ai-sdk/codemod upgrade
For a detailed overview of all changes and manual steps that might be needed, refer to our AI SDK 5 migration guide. The guide includes step-by-step instructions and examples to ensure a smooth update.
Your feedback, bug reports, and pull requests on GitHub have been instrumental in shaping this release. We're excited to see what you'll build with these new capabilities.