AI SDK Core provides unified API
AI SDK Core is a unified API for generating text, structured objects, tool calls, and building agents with LLMs.
ai sdk surfaces
82 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
AI SDK UI provides framework-agnostic hooks
AI SDK UI is a set of framework-agnostic hooks for quickly building chat and generative user interface.
AI SDK Harnesses provide uniform API for agent harnesses
AI SDK Harnesses provide a uniform API for running established agent harnesses like Claude Code, Codex, and Pi through HarnessAgent. Harnesses are decoupled from model providers but use compatible stream and response primitives so AI SDK UI and agent surfaces can consume them in the same way.
AI SDK UI framework support for specific functions
useChat is supported in React, Svelte, and Vue.js. useChat with tool calling is supported in React and Svelte, but not Vue.js. useCompletion is supported in React, Svelte, and Vue.js. useObject is supported in React only. MCP Apps is supported in React only.
AI SDK RSC cancellation limitation
With AI SDK RSC, it is currently not possible to abort a stream using Server Actions. This limitation is expected to be improved in future releases of React and Next.js.
AI SDK RSC createStreamableUI data transfer limitation
Using createStreamableUI in AI SDK RSC can lead to quadratic data transfer proportional to the length of generated text. To avoid this, use createStreamableValue instead and render the component client-side.
AI SDK RSC re-mounting issue during streaming
When using createStreamableUI in AI SDK RSC, components re-mount on .done(), causing flickering.
AI SDK UI key features
AI SDK UI provides full support for streaming chat and client-side generative UI, utilities for handling common AI interaction patterns (chat, completion, assistant), production-tested reliability and performance, and compatibility across popular frameworks.
AI SDK UI environment compatibility
AI SDK UI works in React & Next.js, Vue & Nuxt, and Svelte & SvelteKit.
AI SDK RSC environment compatibility
AI SDK RSC works in any framework that supports React Server Components, such as Next.js.
Cannot destructure Chat class properties in Svelte
Destructuring Chat class properties in Svelte copies them by value and disconnects them from the class instance, so they become stale. Always access properties directly from the class instance like chat.messages rather than destructuring them.
Message parts structure in Chat UI
Messages in the Chat UI contain an ordered array of parts accessed via message.parts. Each part has a type property: 'text' for plain text responses, or 'tool-{toolName}' for tool invocations and results. The order of parts reflects the sequence of the model's outputs.
Chat class from @ai-sdk/svelte provides state management
The Chat class from '@ai-sdk/svelte' manages chat state and provides utility functions. Key properties include messages (array of chat messages with id, role, and parts), and sendMessage (function to send a message to the chat API). By default, Chat uses the POST route at /api/chat.
Chat class sendMessage method
The Chat class sendMessage method accepts an object with a text property containing the message text. Example: chat.sendMessage({ text: 'Hello' }). This sends the message to the API route and updates the chat state.
Svelte Chat class uses static initialization unlike React hooks
In Svelte, code in the script block only runs once when the component is created, unlike React hooks which rerun on invalidation. To make Chat class arguments reactive, pass a reference (via getter) rather than a value. For example, use { get id() { return id; } } instead of { id }.
createAIContext enables Svelte Chat instance synchronization
The createAIContext function from '@ai-sdk/svelte' creates a context in the root layout that synchronizes Chat instances with the same id. Chat instances created after this call or in child components will have synchronized state (messages, status, etc.). Call this in your root layout component.
Expo quickstart requires Expo 52 or higher
The Expo quickstart guide explicitly requires Expo 52 or higher to work correctly with the AI SDK.
useChat hook from @ai-sdk/react
The useChat hook is imported from '@ai-sdk/react' and provides messages state and sendMessage function. It accepts a transport option (DefaultChatTransport for Expo) and onError callback. Returns messages array and sendMessage function.
DefaultChatTransport for Expo with custom fetch
DefaultChatTransport is used with Expo to enable streaming. It takes a fetch option (use expo/fetch instead of native fetch) and api option with the endpoint URL. Example: new DefaultChatTransport({ fetch: expoFetch as unknown as typeof globalThis.fetch, api: generateAPIUrl('/api/chat') })
Message structure with id, role, and parts array
Chat messages have id, role, and parts properties. The parts array contains message components in order, each with a type property. Part types include 'text' and tool-specific types like 'tool-{toolName}'.
expo/fetch required for streaming instead of native fetch
In Expo applications, use expo/fetch instead of the native node fetch function to enable streaming of chat responses. This requires Expo 52 or higher. Import with: import { fetch as expoFetch } from 'expo/fetch'
generateAPIUrl utility for Expo development and production
Create a generateAPIUrl utility that handles both development and production URL generation for Expo. It uses Constants.experienceUrl in development and EXPO_PUBLIC_API_BASE_URL environment variable in production.
Required polyfills for Expo: structuredClone, TextEncoderStream, TextDecoderStream
Some AI SDK functions require polyfills in Expo. Install @ungap/structured-clone and @stardazed/streams-text-encoding, then add polyfills.js to root with structuredClone, TextEncoderStream, and TextDecoderStream. Import polyfills in root _layout.tsx.
sendMessage function in useChat accepts text property
The sendMessage function from useChat accepts an object with a text property. Call it like: sendMessage({ text: input })
useChat hook - messages and sendMessage properties
The useChat hook from @ai-sdk/vue provides a messages property containing the current chat messages as an array of objects with id, role, and parts properties. It also provides a sendMessage function to send a message to the chat API. By default, useChat targets the /api/chat API route.
Message parts array structure
Each message object contains a parts array with an ordered sequence of message components. These parts can include plain text (type 'text'), tool invocations (type 'tool-{toolName}'), reasoning tokens, and other generated content. The parts array preserves the order in which the model generated its outputs.
useChat default endpoint
The useChat hook from @ai-sdk/vue targets /api/chat by default as its API endpoint. No additional configuration is needed if the chat endpoint is at this default location.
TanStack Start route handler structure
In TanStack Start, route handlers are created in src/routes/api/{route}.ts and export a Route object created with createFileRoute(). Server-side handlers are defined in a server object with a handlers property containing POST, GET, and other HTTP methods.
runAgentTUI with local agent example
import { openai } from '@ai-sdk/openai'; import { runAgentTUI } from '@ai-sdk/tui'; import { ToolLoopAgent, tool } from 'ai'; import { z } from 'zod'; const agent = new ToolLoopAgent({ model: openai('gpt-5'), instructions: 'You are a helpful terminal assistant. Answer in markdown and use tools when they help.', tools: { weather: tool({ description: 'Get the weather in a location', inputSchema: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: 72, }), }), }, }); await runAgentTUI({ title: 'Weather Agent', agent, });
@ai-sdk/tui package purpose
The @ai-sdk/tui package lets you run a local ToolLoopAgent or connect to a remote agent through a ChatTransport in an interactive terminal interface. It is useful for local development, demos, and internal tools where a terminal experience is enough and you do not want to build a custom UI.
Terminal UI features handled
The terminal UI handles prompt input, streamed assistant responses, markdown rendering, tool cards, reasoning sections, scrolling, and tool approval prompts.
@ai-sdk/tui installation
Install @ai-sdk/tui alongside ai and the provider package you use. Example: pnpm add @ai-sdk/tui ai @ai-sdk/openai
runAgentTUI exit behavior
runAgentTUI runs until the user exits with Esc or Ctrl+C.
runAgentTUI with remote agent via ChatTransport
import { runAgentTUI } from '@ai-sdk/tui'; import { DefaultChatTransport } from 'ai'; await runAgentTUI({ title: 'Remote Agent', transport: new DefaultChatTransport({ api: 'https://example.com/api/chat', }), });
ChatTransport in terminal UI
The transport controls the endpoint, authentication, request body, and other remote communication behavior. The terminal UI keeps its internal chat id and message history private to the transport contract.
runAgentTUI with sandbox session
import { createJustBashSandbox } from '@ai-sdk/sandbox-just-bash'; const sandboxSession = await createJustBashSandbox({ cwd: '/home/user', }).createSession(); await runAgentTUI({ title: 'Sandbox Agent', agent, sandbox: sandboxSession.restricted(), });
Terminal UI sandbox behavior
The terminal UI forwards the sandbox to every agent call as experimental_sandbox. Tool description functions and tool execute functions can read it from their options and delegate command or file operations to it. Add the sandbox description to your agent instructions if the model should know details such as the working directory, public hostname, or exposed ports.
runAgentTUI display options example
await runAgentTUI({ title: 'Weather Agent', agent, tools: 'auto-collapsed', reasoning: 'collapsed', responseStatistics: 'outputTokensPerSecond', contextSize: 200_000, });
runAgentTUI tools option
The tools option controls tool call rendering. Use 'full' to show tool input and output, 'collapsed' to show only tool cards, 'auto-collapsed' to show the latest tool expanded until another visible section appears, or 'hidden' to omit tool calls. Defaults to 'auto-collapsed'.
runAgentTUI reasoning option
The reasoning option controls reasoning rendering. Use 'full' to show reasoning, 'collapsed' to show only reasoning cards, 'auto-collapsed' to show the latest reasoning expanded until another visible section appears, or 'hidden' to omit reasoning. Defaults to 'auto-collapsed'.
runAgentTUI responseStatistics option
The responseStatistics option controls what response metrics are shown. Use 'outputTokensPerSecond' to show output token throughput or 'outputTokenCount' to show output token count. Defaults to 'outputTokensPerSecond'.
runAgentTUI contextSize option
The contextSize option specifies the model context window size. When provided, the terminal UI shows total token usage as a percentage of the model context window.
runAgentTUI tool approvals support
runAgentTUI supports ToolLoopAgent tool approval flows. When an agent emits a manual approval request, the terminal UI prompts the user to approve or deny the tool call before the agent continues.
ToolLoopAgent tool approval configuration example
const agent = new ToolLoopAgent({ model: openai('gpt-5'), tools: { weather }, toolApproval: { weather: ({ location }) => location.toLowerCase().includes('san francisco') ? 'approved' : 'user-approval', }, }); await runAgentTUI({ title: 'Weather Agent', agent });
runAgentTUI compatibility constraints
When using the agent option, the agent must be runnable directly from terminal user input. It must not require per-call options and must not use structured output, because the terminal UI cannot infer those values from a free-form prompt. Use a transport for remote agents that need custom request handling.
runAgentTUI direct agent usage alternative
Use agent.generate() or agent.stream() directly for examples or apps that need fixed prompts, call options, structured output, custom result inspection, or custom stream processing.
Terminal UI keyboard controls
Terminal UI controls: Enter (submit prompt), y / n (approve or deny tool calls), Up / Down (scroll transcript), PageUp / PageDown (scroll transcript by a full page), Ctrl+L (repaint), Esc / Ctrl+C (exit).
experimental_useRealtime hook parameters
The experimental_useRealtime hook accepts: model (required) - the realtime model instance from a provider or gateway; api.token (required) - the path to your setup endpoint that returns a token; sessionConfig (object) - configuration with properties like instructions (string), inputAudioTranscription (object), voice (string like 'alloy'), turnDetection (object with type property like 'server-vad'); onToolCall (function) - callback to handle tool calls from the model.
experimental_useRealtime hook return properties
The experimental_useRealtime hook returns an object with: connect (function) - method to establish the WebSocket connection; disconnect (function) - method to close the connection; messages (array) - array of message objects; addToolOutput (function) - method to submit tool output manually.
Message structure in realtime sessions
Messages in realtime sessions have: id (string) - unique identifier; role (string) - 'user' or 'assistant'; parts (array) - message content where each part has type (like 'text') and content (e.g., text property for text parts).
useCompletion support across frameworks
The useCompletion hook is supported in React, Vue.js, and as 'Completion' in Svelte and Angular. SolidJS also supports useCompletion.
useObject support across frameworks
The useObject hook is supported in React, Vue.js, and as 'StructuredObject' in Svelte and Angular. SolidJS also supports useObject.
MCP Apps support across frameworks
MCP Apps are supported only in React (@ai-sdk/react). They are not supported in Vue.js, Svelte, Angular, or SolidJS.
AI SDK UI framework-agnostic design
AI SDK UI is a framework-agnostic toolkit designed to streamline the integration of advanced AI functionalities into applications across multiple frameworks.
AI SDK UI main hooks
AI SDK UI provides three main hooks for building interactive AI applications: useChat for real-time streaming of chat messages, useCompletion for handling text completions with automatic UI updates, and useObject for consuming streamed JSON objects.
useChat hook
The useChat hook offers real-time streaming of chat messages and abstracts state management for inputs, messages, loading, and errors, allowing for seamless integration into any UI design.
AI SDK UI framework support
AI SDK UI supports the following frameworks: React (via @ai-sdk/react), Svelte (via @ai-sdk/svelte), Vue.js (via @ai-sdk/vue), Angular (via @ai-sdk/angular), and SolidJS (community package).
useChat support across frameworks
The useChat hook is supported in React, Vue.js, and as 'Chat' in Svelte and Angular. SolidJS also supports useChat.
Clear activeStreamId when stream finishes via onEnd callback
Register an `onEnd` callback with `toUIMessageStream` to clear the active stream when finished. The callback should set `activeStreamId` to null in the saved chat data.
Resumable streams require Redis instance and resumable-stream package
To implement resumable streams, you need a Redis instance to store stream data (available through services like Redis through Vercel) and the `resumable-stream` npm package to handle the publisher/subscriber mechanism for streams.