# Table of Contents - [AI SDK by Vercel](#ai-sdk-by-vercel) - [Foundations](#foundations) - [Foundations: Overview](#foundations-overview) - [Foundations: Tools](#foundations-tools) - [Foundations: Prompts](#foundations-prompts) - [Foundations: Streaming](#foundations-streaming) - [Foundations: Providers and Models](#foundations-providers-and-models) - [Getting Started](#getting-started) - [Foundations: Agents](#foundations-agents) - [Getting Started: Navigating the Library](#getting-started-navigating-the-library) - [Getting Started: Next.js Pages Router](#getting-started-next-js-pages-router) - [Getting Started: Next.js App Router](#getting-started-next-js-app-router) - [Getting Started: Svelte](#getting-started-svelte) - [Guides](#guides) - [Getting Started: Node.js](#getting-started-node-js) - [Getting Started: Vue.js (Nuxt)](#getting-started-vue-js-nuxt-) --- # AI SDK by Vercel [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [AI SDK](#ai-sdk) ================== The AI SDK is the TypeScript toolkit designed to help developers build AI-powered applications and agents with React, Next.js, Vue, Svelte, Node.js, and more. [Why use the AI SDK?](#why-use-the-ai-sdk) ------------------------------------------- Integrating large language models (LLMs) into applications is complicated and heavily dependent on the specific model provider you use. The AI SDK standardizes integrating artificial intelligence (AI) models across [supported providers](/docs/foundations/providers-and-models) . This enables developers to focus on building great AI applications, not waste time on technical details. For example, here’s how you can generate text with various models using the AI SDK: xAI OpenAI Anthropic Google Custom import { generateText } from "ai" import { xai } from "@ai-sdk/xai" const { text } = await generateText({ model: xai("grok-3-beta"), prompt: "What is love?" }) Love is a universal emotion that is characterized by feelings of affection, attachment, and warmth towards someone or something. It is a complex and multifaceted experience that can take many different forms, including romantic love, familial love, platonic love, and self-love. The AI SDK has two main libraries: * **[AI SDK Core](/docs/ai-sdk-core) :** A unified API for generating text, structured objects, tool calls, and building agents with LLMs. * **[AI SDK UI](/docs/ai-sdk-ui) :** A set of framework-agnostic hooks for quickly building chat and generative user interface. [Model Providers](#model-providers) ------------------------------------ The AI SDK supports [multiple model providers](/providers) . [xAI Grok\ \ Image InputImage GenerationObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/xai) [OpenAI\ \ Image InputImage GenerationObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/openai) [Azure\ \ ![Azure logo](/_next/image?url=%2Ficons%2Fazure.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image InputObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/azure) [Anthropic\ \ Image InputObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/anthropic) [Amazon Bedrock\ \ Image InputImage GenerationObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/amazon-bedrock) [Groq\ \ Object GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/groq) [Fal AI\ \ Image Generation](/providers/ai-sdk-providers/fal) [DeepInfra\ \ Image InputObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/deepinfra) [Google Generative AI\ \ ![Google Generative AI logo](/_next/image?url=%2Ficons%2Fgoogle.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image InputObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/google-generative-ai) [Google Vertex AI\ \ ![Google Vertex AI logo](/_next/image?url=%2Ficons%2Fgoogle.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image InputImage GenerationObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/google-vertex) [Mistral\ \ ![Mistral logo](/_next/image?url=%2Ficons%2Fmistral.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image InputObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/mistral) [Together.ai\ \ Object GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/togetherai) [Cohere\ \ ![Cohere logo](/_next/image?url=%2Ficons%2Fcohere.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Tool UsageTool Streaming](/providers/ai-sdk-providers/cohere) [Fireworks\ \ ![Fireworks logo](/_next/image?url=%2Ficons%2Ffireworks.png&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image GenerationObject GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/fireworks) [DeepSeek\ \ ![DeepSeek logo](/_next/image?url=%2Ficons%2Fdeepseek.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Object GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/deepseek) [Cerebras\ \ Object GenerationTool UsageTool Streaming](/providers/ai-sdk-providers/cerebras) [Perplexity\ \ ![Perplexity logo](/_next/image?url=%2Ficons%2Fperplexity.svg&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)](/providers/ai-sdk-providers/perplexity) [Luma AI\ \ ![Luma AI logo](/_next/image?url=%2Ficons%2Fluma.png&w=256&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)\ \ Image Generation](/providers/ai-sdk-providers/luma) [Templates](#templates) ------------------------ We've built some [templates](https://vercel.com/templates?type=ai) that include AI SDK integrations for different use cases, providers, and frameworks. You can use these templates to get started with your AI-powered application. ### [Starter Kits](#starter-kits) [Chatbot Starter Template\ \ Uses the AI SDK and Next.js. Features persistence, multi-modal chat, and more.](https://vercel.com/templates/next.js/nextjs-ai-chatbot) [Internal Knowledge Base (RAG)\ \ Uses AI SDK Language Model Middleware for RAG and enforcing guardrails.](https://vercel.com/templates/next.js/ai-sdk-internal-knowledge-base) [Multi-Modal Chat\ \ Uses Next.js and AI SDK useChat hook for multi-modal message chat interface.](https://vercel.com/templates/next.js/multi-modal-chatbot) [Semantic Image Search\ \ An AI semantic image search app template built with Next.js, AI SDK, and Postgres.](https://vercel.com/templates/next.js/semantic-image-search) [Natural Language PostgreSQL\ \ Query PostgreSQL using natural language with AI SDK and GPT-4o.](https://vercel.com/templates/next.js/natural-language-postgres) ### [Feature Exploration](#feature-exploration) [Feature Flags Example\ \ AI SDK with Next.js, Feature Flags, and Edge Config for dynamic model switching.](https://vercel.com/templates/next.js/ai-sdk-feature-flags-edge-config) [Chatbot with Telemetry\ \ AI SDK chatbot with OpenTelemetry support.](https://vercel.com/templates/next.js/ai-chatbot-telemetry) [Structured Object Streaming\ \ Uses AI SDK useObject hook to stream structured object generation.](https://vercel.com/templates/next.js/use-object) [Multi-Step Tools\ \ Uses AI SDK streamText function to handle multiple tool steps automatically.](https://vercel.com/templates/next.js/ai-sdk-roundtrips) ### [Frameworks](#frameworks) [Next.js OpenAI Starter\ \ Uses OpenAI GPT-4, AI SDK, and Next.js.](https://github.com/vercel/ai/tree/main/examples/next-openai) [Nuxt OpenAI Starter\ \ Uses OpenAI GPT-4, AI SDK, and Nuxt.js.](https://github.com/vercel/ai/tree/main/examples/nuxt-openai) [SvelteKit OpenAI Starter\ \ Uses OpenAI GPT-4, AI SDK, and SvelteKit.](https://github.com/vercel/ai/tree/main/examples/sveltekit-openai) [Solid OpenAI Starter\ \ Uses OpenAI GPT-4, AI SDK, and Solid.](https://github.com/vercel/ai/tree/main/examples/solidstart-openai) ### [Generative UI](#generative-ui) [Gemini Chatbot\ \ Uses Google Gemini, AI SDK, and Next.js.](https://vercel.com/templates/next.js/gemini-ai-chatbot) [Generative UI with RSC (experimental)\ \ Uses Next.js, AI SDK, and streamUI to create generative UIs with React Server Components.](https://vercel.com/templates/next.js/rsc-genui) ### [Security](#security) [Bot Protection\ \ Uses Kasada, OpenAI GPT-4, AI SDK, and Next.js.](https://vercel.com/templates/next.js/advanced-ai-bot-protection) [Rate Limiting\ \ Uses Vercel KV, OpenAI GPT-4, AI SDK, and Next.js.](https://github.com/vercel/ai/tree/main/examples/next-openai-upstash-rate-limits) [Join our Community](#join-our-community) ------------------------------------------ If you have questions about anything related to the AI SDK, you're always welcome to ask our community on [GitHub Discussions](https://github.com/vercel/ai/discussions) . [`llms.txt` (for Cursor, Windsurf, Copilot, Claude etc.)](#llmstxt-for-cursor-windsurf-copilot-claude-etc) ----------------------------------------------------------------------------------------------------------- You can access the entire AI SDK documentation in Markdown format at [sdk.vercel.ai/llms.txt](/llms.txt) . This can be used to ask any LLM (assuming it has a big enough context window) questions about the AI SDK based on the most up-to-date documentation. ### [Example Usage](#example-usage) For instance, to prompt an LLM with questions about the AI SDK: 1. Copy the documentation contents from [sdk.vercel.ai/llms.txt](/llms.txt) 2. Use the following prompt format: Documentation:{paste documentation here}---Based on the above documentation, answer the following:{your question} On this page [AI SDK](#ai-sdk) [Why use the AI SDK?](#why-use-the-ai-sdk) [Model Providers](#model-providers) [Templates](#templates) [Starter Kits](#starter-kits) [Feature Exploration](#feature-exploration) [Frameworks](#frameworks) [Generative UI](#generative-ui) [Security](#security) [Join our Community](#join-our-community) [llms.txt (for Cursor, Windsurf, Copilot, Claude etc.)](#llmstxt-for-cursor-windsurf-copilot-claude-etc) [Example Usage](#example-usage) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Foundations](#foundations) ============================ [Overview\ \ Learn about foundational concepts around AI and LLMs.](/docs/foundations/overview) [Providers and Models\ \ Learn about the providers and models that you can use with the AI SDK.](/docs/foundations/providers-and-models) [Prompts\ \ Learn about how Prompts are used and defined in the AI SDK.](/docs/foundations/prompts) [Tools\ \ Learn about tools in the AI SDK.](/docs/foundations/tools) [Streaming\ \ Learn why streaming is used for AI applications.](/docs/foundations/streaming) [Agents\ \ Learn how to build agents with the AI SDK.](/docs/foundations/agents) On this page [Foundations](#foundations) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Overview [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Overview](#overview) ====================== This page is a beginner-friendly introduction to high-level artificial intelligence (AI) concepts. To dive right into implementing the AI SDK, feel free to skip ahead to our [quickstarts](/docs/getting-started) or learn about our [supported models and providers](/docs/foundations/providers-and-models) . The AI SDK standardizes integrating artificial intelligence (AI) models across [supported providers](/docs/foundations/providers-and-models) . This enables developers to focus on building great AI applications, not waste time on technical details. For example, here’s how you can generate text with various models using the AI SDK: xAI OpenAI Anthropic Google Custom import { generateText } from "ai" import { xai } from "@ai-sdk/xai" const { text } = await generateText({ model: xai("grok-3-beta"), prompt: "What is love?" }) Love is a universal emotion that is characterized by feelings of affection, attachment, and warmth towards someone or something. It is a complex and multifaceted experience that can take many different forms, including romantic love, familial love, platonic love, and self-love. To effectively leverage the AI SDK, it helps to familiarize yourself with the following concepts: [Generative Artificial Intelligence](#generative-artificial-intelligence) -------------------------------------------------------------------------- **Generative artificial intelligence** refers to models that predict and generate various types of outputs (such as text, images, or audio) based on what’s statistically likely, pulling from patterns they’ve learned from their training data. For example: * Given a photo, a generative model can generate a caption. * Given an audio file, a generative model can generate a transcription. * Given a text description, a generative model can generate an image. [Large Language Models](#large-language-models) ------------------------------------------------ A **large language model (LLM)** is a subset of generative models focused primarily on **text**. An LLM takes a sequence of words as input and aims to predict the most likely sequence to follow. It assigns probabilities to potential next sequences and then selects one. The model continues to generate sequences until it meets a specified stopping criterion. LLMs learn by training on massive collections of written text, which means they will be better suited to some use cases than others. For example, a model trained on GitHub data would understand the probabilities of sequences in source code particularly well. However, it's crucial to understand LLMs' limitations. When asked about less known or absent information, like the birthday of a personal relative, LLMs might "hallucinate" or make up information. It's essential to consider how well-represented the information you need is in the model. [Embedding Models](#embedding-models) -------------------------------------- An **embedding model** is used to convert complex data (like words or images) into a dense vector (a list of numbers) representation, known as an embedding. Unlike generative models, embedding models do not generate new text or data. Instead, they provide representations of semantic and syntactic relationships between entities that can be used as input for other models or other natural language processing tasks. In the next section, you will learn about the difference between models providers and models, and which ones are available in the AI SDK. On this page [Overview](#overview) [Generative Artificial Intelligence](#generative-artificial-intelligence) [Large Language Models](#large-language-models) [Embedding Models](#embedding-models) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Tools [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Tools](#tools) ================ While [large language models (LLMs)](/docs/foundations/overview#large-language-models) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. For example, when you ask an LLM for the "weather in London", and there is a weather tool available, it could call a tool with London as the argument. The tool would then fetch the weather data and return it to the LLM. The LLM can then use this information in its response. [What is a tool?](#what-is-a-tool) ----------------------------------- A tool is an object that can be called by the model to perform a specific task. You can use tools with [`generateText`](/docs/reference/ai-sdk-core/generate-text) and [`streamText`](/docs/reference/ai-sdk-core/stream-text) by passing one or more tools to the `tools` parameter. A tool consists of three properties: * **`description`**: An optional description of the tool that can influence when the tool is picked. * **`parameters`**: A [Zod schema](/docs/foundations/tools#schema-specification-and-validation-with-zod) or a [JSON schema](/docs/reference/ai-sdk-core/json-schema) that defines the parameters. The schema is consumed by the LLM, and also used to validate the LLM tool calls. * **`execute`**: An optional async function that is called with the arguments from the tool call. `streamUI` uses UI generator tools with a `generate` function that can return React components. If the LLM decides to use a tool, it will generate a tool call. Tools with an `execute` function are run automatically when these calls are generated. The results of the tool calls are returned using tool result objects. You can automatically pass tool results back to the LLM using [multi-step calls](/docs/ai-sdk-core/tools-and-tool-calling#multi-step-calls) with `streamText` and `generateText`. [Schemas](#schemas) -------------------- Schemas are used to define the parameters for tools and to validate the [tool calls](/docs/ai-sdk-core/tools-and-tool-calling) . The AI SDK supports both raw JSON schemas (using the [`jsonSchema` function](/docs/reference/ai-sdk-core/json-schema) ) and [Zod](https://zod.dev/) schemas (either directly or using the [`zodSchema` function](/docs/reference/ai-sdk-core/zod-schema) ). [Zod](https://zod.dev/) is a popular TypeScript schema validation library. You can install it with: pnpm npm yarn pnpm add zod You can then specify a Zod schema, for example: import z from 'zod'; const recipeSchema = z.object({ recipe: z.object({ name: z.string(), ingredients: z.array( z.object({ name: z.string(), amount: z.string(), }), ), steps: z.array(z.string()), }),}); You can also use schemas for structured output generation with [`generateObject`](/docs/reference/ai-sdk-core/generate-object) and [`streamObject`](/docs/reference/ai-sdk-core/stream-object) . [Toolkits](#toolkits) ---------------------- When you work with tools, you typically need a mix of application specific tools and general purpose tools. There are several providers that offer pre-built tools as **toolkits** that you can use out of the box: * **[agentic](https://github.com/transitive-bullshit/agentic) ** - A collection of 20+ tools. Most tools connect to access external APIs such as [Exa](https://exa.ai/) or [E2B](https://e2b.dev/) . * **[browserbase](https://docs.browserbase.com/integrations/vercel-ai/introduction) ** - Browser tool that runs a headless browser * **[Stripe agent tools](https://docs.stripe.com/agents) ** - Tools for interacting with Stripe. * **[StackOne ToolSet](https://docs.stackone.com/agents) ** - Agentic integrations for hundreds of [enterprise SaaS](https://www.stackone.com/integrations) * **[Toolhouse](https://docs.toolhouse.ai/toolhouse/using-vercel-ai) ** - AI function-calling in 3 lines of code for over 25 different actions. * **[Agent Tools](https://ai-sdk-agents.vercel.app/?item=introduction) ** - A collection of tools for agents. * **[AI Tool Maker](https://github.com/nihaocami/ai-tool-maker) ** - A CLI utility to generate AI SDK tools from OpenAPI specs. * **[Composio](https://docs.composio.dev/javascript/vercel) ** - Composio provides 250+ tools like GitHub, Gmail, Salesforce and [more](https://composio.dev/tools) . * **[Interlify](https://www.interlify.com/docs/integrate-with-vercel-ai) ** - Convert APIs into tools so that AI can connect to your backend in minutes. * **[Freestyle](https://docs.freestyle.sh/integrations/vercel) ** — Tool for your AI to execute JavaScript or TypeScript with arbitrary node modules. Do you have open source tools or tool libraries that are compatible with the AI SDK? Please [file a pull request](https://github.com/vercel/ai/pulls) to add them to this list. [Learn more](#learn-more) -------------------------- The AI SDK Core [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) and [Agents](/docs/foundations/agents) documentation has more information about tools and tool calling. On this page [Tools](#tools) [What is a tool?](#what-is-a-tool) [Schemas](#schemas) [Toolkits](#toolkits) [Learn more](#learn-more) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Prompts [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Prompts](#prompts) ==================== Prompts are instructions that you give a [large language model (LLM)](/docs/foundations/overview#large-language-models) to tell it what to do. It's like when you ask someone for directions; the clearer your question, the better the directions you'll get. Many LLM providers offer complex interfaces for specifying prompts. They involve different roles and message types. While these interfaces are powerful, they can be hard to use and understand. In order to simplify prompting, the AI SDK supports text, message, and system prompts. [Text Prompts](#text-prompts) ------------------------------ Text prompts are strings. They are ideal for simple generation use cases, e.g. repeatedly generating content for variants of the same prompt text. You can set text prompts using the `prompt` property made available by AI SDK functions like [`streamText`](/docs/reference/ai-sdk-core/stream-text) or [`generateObject`](/docs/reference/ai-sdk-core/generate-object) . You can structure the text in any way and inject variables, e.g. using a template literal. const result = await generateText({ model: yourModel, prompt: 'Invent a new holiday and describe its traditions.',}); You can also use template literals to provide dynamic data to your prompt. const result = await generateText({ model: yourModel, prompt: `I am planning a trip to ${destination} for ${lengthOfStay} days. ` + `Please suggest the best tourist activities for me to do.`,}); [System Prompts](#system-prompts) ---------------------------------- System prompts are the initial set of instructions given to models that help guide and constrain the models' behaviors and responses. You can set system prompts using the `system` property. System prompts work with both the `prompt` and the `messages` properties. const result = await generateText({ model: yourModel, system: `You help planning travel itineraries. ` + `Respond to the users' request with a list ` + `of the best stops to make in their destination.`, prompt: `I am planning a trip to ${destination} for ${lengthOfStay} days. ` + `Please suggest the best tourist activities for me to do.`,}); When you use a message prompt, you can also use system messages instead of a system prompt. [Message Prompts](#message-prompts) ------------------------------------ A message prompt is an array of user, assistant, and tool messages. They are great for chat interfaces and more complex, multi-modal prompts. You can use the `messages` property to set message prompts. Each message has a `role` and a `content` property. The content can either be text (for user and assistant messages), or an array of relevant parts (data) for that message type. const result = await streamUI({ model: yourModel, messages: [ { role: 'user', content: 'Hi!' }, { role: 'assistant', content: 'Hello, how can I help?' }, { role: 'user', content: 'Where can I buy the best Currywurst in Berlin?' }, ],}); Instead of sending a text in the `content` property, you can send an array of parts that includes a mix of text and other content parts. Not all language models support all message and content types. For example, some models might not be capable of handling multi-modal inputs or tool messages. [Learn more about the capabilities of select models](./providers-and-models#model-capabilities) . ### [Provider Options](#provider-options) You can pass through additional provider-specific metadata to enable provider-specific functionality at 3 levels. #### [Function Call Level](#function-call-level) Functions like [`streamText`](/docs/reference/ai-sdk-core/stream-text#provider-options) or [`generateText`](/docs/reference/ai-sdk-core/generate-text#provider-options) accept a `providerOptions` property. Adding provider options at the function call level should be used when you do not need granular control over where the provider options are applied. const { text } = await generateText({ model: azure('your-deployment-name'), providerOptions: { openai: { reasoningEffort: 'low', }, },}); #### [Message Level](#message-level) For granular control over applying provider options at the message level, you can pass `providerOptions` to the message object: const messages = [ { role: 'system', content: 'Cached system message', providerOptions: { // Sets a cache control breakpoint on the system message anthropic: { cacheControl: { type: 'ephemeral' } }, }, },]; #### [Message Part Level](#message-part-level) Certain provider-specific options require configuration at the message part level: const messages = [ { role: 'user', content: [ { type: 'text', text: 'Describe the image in detail.', providerOptions: { openai: { imageDetail: 'low' }, }, }, { type: 'image', image: 'https://github.com/vercel/ai/blob/main/examples/ai-core/data/comic-cat.png?raw=true', // Sets image detail configuration for image part: providerOptions: { openai: { imageDetail: 'low' }, }, }, ], },]; AI SDK UI hooks like [`useChat`](/docs/reference/ai-sdk-ui/use-chat) return arrays of `UIMessage` objects, which do not support provider options. We recommend using the [`convertToCoreMessages`](/docs/reference/ai-sdk-ui/convert-to-core-messages) function to convert `UIMessage` objects to [`CoreMessage`](/docs/reference/ai-sdk-core/core-message) objects before applying or appending message(s) or message parts with `providerOptions`. ### [User Messages](#user-messages) #### [Text Parts](#text-parts) Text content is the most common type of content. It is a string that is passed to the model. If you only need to send text content in a message, the `content` property can be a string, but you can also use it to send multiple content parts. const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: [ { type: 'text', text: 'Where can I buy the best Currywurst in Berlin?', }, ], }, ],}); #### [Image Parts](#image-parts) User messages can include image parts. An image can be one of the following: * base64-encoded image: * `string` with base-64 encoded content * data URL `string`, e.g. `data:image/png;base64,...` * binary image: * `ArrayBuffer` * `Uint8Array` * `Buffer` * URL: * http(s) URL `string`, e.g. `https://example.com/image.png` * `URL` object, e.g. `new URL('https://example.com/image.png')` ##### [Example: Binary image (Buffer)](#example-binary-image-buffer) const result = await generateText({ model, messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe the image in detail.' }, { type: 'image', image: fs.readFileSync('./data/comic-cat.png'), }, ], }, ],}); ##### [Example: Base-64 encoded image (string)](#example-base-64-encoded-image-string) const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe the image in detail.' }, { type: 'image', image: fs.readFileSync('./data/comic-cat.png').toString('base64'), }, ], }, ],}); ##### [Example: Image URL (string)](#example-image-url-string) const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: [ { type: 'text', text: 'Describe the image in detail.' }, { type: 'image', image: 'https://github.com/vercel/ai/blob/main/examples/ai-core/data/comic-cat.png?raw=true', }, ], }, ],}); #### [File Parts](#file-parts) Only a few providers and models currently support file parts: [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai) , [Google Vertex AI](/providers/ai-sdk-providers/google-vertex) , [OpenAI](/providers/ai-sdk-providers/openai) (for `wav` and `mp3` audio with `gpt-4o-audio-preview`), [Anthropic](/providers/ai-sdk-providers/anthropic) , [OpenAI](/providers/ai-sdk-providers/openai) (for `pdf`). User messages can include file parts. A file can be one of the following: * base64-encoded file: * `string` with base-64 encoded content * data URL `string`, e.g. `data:image/png;base64,...` * binary data: * `ArrayBuffer` * `Uint8Array` * `Buffer` * URL: * http(s) URL `string`, e.g. `https://example.com/some.pdf` * `URL` object, e.g. `new URL('https://example.com/some.pdf')` You need to specify the MIME type of the file you are sending. ##### [Example: PDF file from Buffer](#example-pdf-file-from-buffer) import { google } from '@ai-sdk/google';import { generateText } from 'ai'; const result = await generateText({ model: google('gemini-1.5-flash'), messages: [ { role: 'user', content: [ { type: 'text', text: 'What is the file about?' }, { type: 'file', mimeType: 'application/pdf', data: fs.readFileSync('./data/example.pdf'), filename: 'example.pdf', // optional, not used by all providers }, ], }, ],}); ##### [Example: mp3 audio file from Buffer](#example-mp3-audio-file-from-buffer) import { openai } from '@ai-sdk/openai';import { generateText } from 'ai'; const result = await generateText({ model: openai('gpt-4o-audio-preview'), messages: [ { role: 'user', content: [ { type: 'text', text: 'What is the audio saying?' }, { type: 'file', mimeType: 'audio/mpeg', data: fs.readFileSync('./data/galileo.mp3'), }, ], }, ],}); ### [Assistant Messages](#assistant-messages) Assistant messages are messages that have a role of `assistant`. They are typically previous responses from the assistant and can contain text, reasoning, and tool call parts. #### [Example: Assistant message with text content](#example-assistant-message-with-text-content) const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: 'Hi!' }, { role: 'assistant', content: 'Hello, how can I help?' }, ],}); #### [Example: Assistant message with text content in array](#example-assistant-message-with-text-content-in-array) const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: 'Hi!' }, { role: 'assistant', content: [{ type: 'text', text: 'Hello, how can I help?' }], }, ],}); #### [Example: Assistant message with tool call content](#example-assistant-message-with-tool-call-content) const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: 'How many calories are in this block of cheese?' }, { role: 'assistant', content: [ { type: 'tool-call', toolCallId: '12345', toolName: 'get-nutrition-data', args: { cheese: 'Roquefort' }, }, ], }, ],}); #### [Example: Assistant message with file content](#example-assistant-message-with-file-content) This content part is for model-generated files. Only a few models support this, and only for file types that they can generate. const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: 'Generate an image of a roquefort cheese!' }, { role: 'assistant', content: [ { type: 'file', mimeType: 'image/png', data: fs.readFileSync('./data/roquefort.jpg'), }, ], }, ],}); ### [Tool messages](#tool-messages) [Tools](/docs/foundations/tools) (also known as function calling) are programs that you can provide an LLM to extend its built-in functionality. This can be anything from calling an external API to calling functions within your UI. Learn more about Tools in [the next section](/docs/foundations/tools) . For models that support [tool](/docs/foundations/tools) calls, assistant messages can contain tool call parts, and tool messages can contain tool result parts. A single assistant message can call multiple tools, and a single tool message can contain multiple tool results. const result = await generateText({ model: yourModel, messages: [ { role: 'user', content: [ { type: 'text', text: 'How many calories are in this block of cheese?', }, { type: 'image', image: fs.readFileSync('./data/roquefort.jpg') }, ], }, { role: 'assistant', content: [ { type: 'tool-call', toolCallId: '12345', toolName: 'get-nutrition-data', args: { cheese: 'Roquefort' }, }, // there could be more tool calls here (parallel calling) ], }, { role: 'tool', content: [ { type: 'tool-result', toolCallId: '12345', // needs to match the tool call id toolName: 'get-nutrition-data', result: { name: 'Cheese, roquefort', calories: 369, fat: 31, protein: 22, }, }, // there could be more tool results here (parallel calling) ], }, ],}); #### [Multi-modal Tool Results](#multi-modal-tool-results) Multi-part tool results are experimental and only supported by Anthropic. Tool results can be multi-part and multi-modal, e.g. a text and an image. You can use the `experimental_content` property on tool parts to specify multi-part tool results. const result = await generateText({ model: yourModel, messages: [ // ... { role: 'tool', content: [ { type: 'tool-result', toolCallId: '12345', // needs to match the tool call id toolName: 'get-nutrition-data', // for models that do not support multi-part tool results, // you can include a regular result part: result: { name: 'Cheese, roquefort', calories: 369, fat: 31, protein: 22, }, // for models that support multi-part tool results, // you can include a multi-part content part: content: [ { type: 'text', text: 'Here is an image of the nutrition data for the cheese:', }, { type: 'image', data: fs.readFileSync('./data/roquefort-nutrition-data.png'), mimeType: 'image/png', }, ], }, ], }, ],}); ### [System Messages](#system-messages) System messages are messages that are sent to the model before the user messages to guide the assistant's behavior. You can alternatively use the `system` property. const result = await generateText({ model: yourModel, messages: [ { role: 'system', content: 'You help planning travel itineraries.' }, { role: 'user', content: 'I am planning a trip to Berlin for 3 days. Please suggest the best tourist activities for me to do.', }, ],}); On this page [Prompts](#prompts) [Text Prompts](#text-prompts) [System Prompts](#system-prompts) [Message Prompts](#message-prompts) [Provider Options](#provider-options) [Function Call Level](#function-call-level) [Message Level](#message-level) [Message Part Level](#message-part-level) [User Messages](#user-messages) [Text Parts](#text-parts) [Image Parts](#image-parts) [Example: Binary image (Buffer)](#example-binary-image-buffer) [Example: Base-64 encoded image (string)](#example-base-64-encoded-image-string) [Example: Image URL (string)](#example-image-url-string) [File Parts](#file-parts) [Example: PDF file from Buffer](#example-pdf-file-from-buffer) [Example: mp3 audio file from Buffer](#example-mp3-audio-file-from-buffer) [Assistant Messages](#assistant-messages) [Example: Assistant message with text content](#example-assistant-message-with-text-content) [Example: Assistant message with text content in array](#example-assistant-message-with-text-content-in-array) [Example: Assistant message with tool call content](#example-assistant-message-with-tool-call-content) [Example: Assistant message with file content](#example-assistant-message-with-file-content) [Tool messages](#tool-messages) [Multi-modal Tool Results](#multi-modal-tool-results) [System Messages](#system-messages) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Streaming [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Streaming](#streaming) ======================== Streaming conversational text UIs (like ChatGPT) have gained massive popularity over the past few months. This section explores the benefits and drawbacks of streaming and blocking interfaces. [Large language models (LLMs)](/docs/foundations/overview#large-language-models) are extremely powerful. However, when generating long outputs, they can be very slow compared to the latency you're likely used to. If you try to build a traditional blocking UI, your users might easily find themselves staring at loading spinners for 5, 10, even up to 40s waiting for the entire LLM response to be generated. This can lead to a poor user experience, especially in conversational applications like chatbots. Streaming UIs can help mitigate this issue by **displaying parts of the response as they become available**. Blocking UI Blocking responses wait until the full response is available before displaying it. Streaming UI Streaming responses can transmit parts of the response as they become available. [Real-world Examples](#real-world-examples) -------------------------------------------- Here are 2 examples that illustrate how streaming UIs can improve user experiences in a real-world setting – the first uses a blocking UI, while the second uses a streaming UI. ### [Blocking UI](#blocking-ui) Come up with the first 200 characters of the first book in the Harry Potter series. Generate ... ### [Streaming UI](#streaming-ui) Come up with the first 200 characters of the first book in the Harry Potter series. Generate ... As you can see, the streaming UI is able to start displaying the response much faster than the blocking UI. This is because the blocking UI has to wait for the entire response to be generated before it can display anything, while the streaming UI can display parts of the response as they become available. While streaming interfaces can greatly enhance user experiences, especially with larger language models, they aren't always necessary or beneficial. If you can achieve your desired functionality using a smaller, faster model without resorting to streaming, this route can often lead to simpler and more manageable development processes. However, regardless of the speed of your model, the AI SDK is designed to make implementing streaming UIs as simple as possible. In the example below, we stream text generation from OpenAI's `gpt-4-turbo` in under 10 lines of code using the SDK's [`streamText`](/docs/reference/ai-sdk-core/stream-text) function: import { openai } from '@ai-sdk/openai';import { streamText } from 'ai'; const { textStream } = streamText({ model: openai('gpt-4-turbo'), prompt: 'Write a poem about embedding models.',}); for await (const textPart of textStream) { console.log(textPart);} For an introduction to streaming UIs and the AI SDK, check out our [Getting Started guides](/docs/getting-started) . On this page [Streaming](#streaming) [Real-world Examples](#real-world-examples) [Blocking UI](#blocking-ui) [Streaming UI](#streaming-ui) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Providers and Models [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Providers and Models](#providers-and-models) ============================================== Companies such as OpenAI and Anthropic (providers) offer access to a range of large language models (LLMs) with differing strengths and capabilities through their own APIs. Each provider typically has its own unique method for interfacing with their models, complicating the process of switching providers and increasing the risk of vendor lock-in. To solve these challenges, AI SDK Core offers a standardized approach to interacting with LLMs through a [language model specification](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v1) that abstracts differences between providers. This unified interface allows you to switch between providers with ease while using the same API for all providers. Here is an overview of the AI SDK Provider Architecture: ![](/_next/image?url=%2Fimages%2Fai-sdk-diagram.png&w=1920&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6)![](/_next/image?url=%2Fimages%2Fai-sdk-diagram-dark.png&w=1920&q=75&dpl=dpl_871rTgMYWjQ4RNpX2EFjGhADztW6) [AI SDK Providers](#ai-sdk-providers) -------------------------------------- The AI SDK comes with a wide range of providers that you can use to interact with different language models: * [xAI Grok Provider](/providers/ai-sdk-providers/xai) (`@ai-sdk/xai`) * [OpenAI Provider](/providers/ai-sdk-providers/openai) (`@ai-sdk/openai`) * [Azure OpenAI Provider](/providers/ai-sdk-providers/azure) (`@ai-sdk/azure`) * [Anthropic Provider](/providers/ai-sdk-providers/anthropic) (`@ai-sdk/anthropic`) * [Amazon Bedrock Provider](/providers/ai-sdk-providers/amazon-bedrock) (`@ai-sdk/amazon-bedrock`) * [Google Generative AI Provider](/providers/ai-sdk-providers/google-generative-ai) (`@ai-sdk/google`) * [Google Vertex Provider](/providers/ai-sdk-providers/google-vertex) (`@ai-sdk/google-vertex`) * [Mistral Provider](/providers/ai-sdk-providers/mistral) (`@ai-sdk/mistral`) * [Together.ai Provider](/providers/ai-sdk-providers/togetherai) (`@ai-sdk/togetherai`) * [Cohere Provider](/providers/ai-sdk-providers/cohere) (`@ai-sdk/cohere`) * [Fireworks Provider](/providers/ai-sdk-providers/fireworks) (`@ai-sdk/fireworks`) * [DeepInfra Provider](/providers/ai-sdk-providers/deepinfra) (`@ai-sdk/deepinfra`) * [DeepSeek Provider](/providers/ai-sdk-providers/deepseek) (`@ai-sdk/deepseek`) * [Cerebras Provider](/providers/ai-sdk-providers/cerebras) (`@ai-sdk/cerebras`) * [Groq Provider](/providers/ai-sdk-providers/groq) (`@ai-sdk/groq`) * [Perplexity Provider](/providers/ai-sdk-providers/perplexity) (`@ai-sdk/perplexity`) * [ElevenLabs Provider](/providers/ai-sdk-providers/elevenlabs) (`@ai-sdk/elevenlabs`) * [LMNT Provider](/providers/ai-sdk-providers/lmnt) (`@ai-sdk/lmnt`) * [Hume Provider](/providers/ai-sdk-providers/hume) (`@ai-sdk/hume`) * [Rev.ai Provider](/providers/ai-sdk-providers/revai) (`@ai-sdk/revai`) * [Deepgram Provider](/providers/ai-sdk-providers/deepgram) (`@ai-sdk/deepgram`) * [Gladia Provider](/providers/ai-sdk-providers/gladia) (`@ai-sdk/gladia`) You can also use the [OpenAI Compatible provider](/providers/openai-compatible-providers) with OpenAI-compatible APIs: * [LM Studio](/providers/openai-compatible-providers/lmstudio) * [Baseten](/providers/openai-compatible-providers/baseten) Our [language model specification](https://github.com/vercel/ai/tree/main/packages/provider/src/language-model/v1) is published as an open-source package, which you can use to create [custom providers](/providers/community-providers/custom-providers) . The open-source community has created the following providers: * [Ollama Provider](/providers/community-providers/ollama) (`ollama-ai-provider`) * [ChromeAI Provider](/providers/community-providers/chrome-ai) (`chrome-ai`) * [FriendliAI Provider](/providers/community-providers/friendliai) (`@friendliai/ai-provider`) * [Portkey Provider](/providers/community-providers/portkey) (`@portkey-ai/vercel-provider`) * [Cloudflare Workers AI Provider](/providers/community-providers/cloudflare-workers-ai) (`workers-ai-provider`) * [OpenRouter Provider](/providers/community-providers/openrouter) (`@openrouter/ai-sdk-provider`) * [Crosshatch Provider](/providers/community-providers/crosshatch) (`@crosshatch/ai-provider`) * [Mixedbread Provider](/providers/community-providers/mixedbread) (`mixedbread-ai-provider`) * [Voyage AI Provider](/providers/community-providers/voyage-ai) (`voyage-ai-provider`) * [Mem0 Provider](/providers/community-providers/mem0) (`@mem0/vercel-ai-provider`) * [Spark Provider](/providers/community-providers/spark) (`spark-ai-provider`) * [AnthropicVertex Provider](/providers/community-providers/anthropic-vertex-ai) (`anthropic-vertex-ai`) * [LangDB Provider](/providers/community-providers/langdb) (`@langdb/vercel-provider`) [Self-Hosted Models](#self-hosted-models) ------------------------------------------ You can access self-hosted models with the following providers: * [Ollama Provider](/providers/community-providers/ollama) * [LM Studio](/providers/openai-compatible-providers/lmstudio) * [Baseten](/providers/openai-compatible-providers/baseten) Additionally, any self-hosted provider that supports the OpenAI specification can be used with the [OpenAI Compatible Provider](/providers/openai-compatible-providers) . [Model Capabilities](#model-capabilities) ------------------------------------------ The AI providers support different language models with various capabilities. Here are the capabilities of popular models: | Provider | Model | Image Input | Object Generation | Tool Usage | Tool Streaming | | --- | --- | --- | --- | --- | --- | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-3` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-3-fast` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-3-mini` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-3-mini-fast` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-2-1212` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-2-vision-1212` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-beta` | | | | | | [xAI Grok](/providers/ai-sdk-providers/xai) | `grok-vision-beta` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4.1` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4.1-mini` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4.1-nano` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4o` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4o-mini` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4-turbo` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `gpt-4` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o3-mini` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o3` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o4-mini` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o1` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o1-mini` | | | | | | [OpenAI](/providers/ai-sdk-providers/openai) | `o1-preview` | | | | | | [Anthropic](/providers/ai-sdk-providers/anthropic) | `claude-3-7-sonnet-20250219` | | | | | | [Anthropic](/providers/ai-sdk-providers/anthropic) | `claude-3-5-sonnet-20241022` | | | | | | [Anthropic](/providers/ai-sdk-providers/anthropic) | `claude-3-5-sonnet-20240620` | | | | | | [Anthropic](/providers/ai-sdk-providers/anthropic) | `claude-3-5-haiku-20241022` | | | | | | [Mistral](/providers/ai-sdk-providers/mistral) | `pixtral-large-latest` | | | | | | [Mistral](/providers/ai-sdk-providers/mistral) | `mistral-large-latest` | | | | | | [Mistral](/providers/ai-sdk-providers/mistral) | `mistral-small-latest` | | | | | | [Mistral](/providers/ai-sdk-providers/mistral) | `pixtral-12b-2409` | | | | | | [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai) | `gemini-2.0-flash-exp` | | | | | | [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai) | `gemini-1.5-flash` | | | | | | [Google Generative AI](/providers/ai-sdk-providers/google-generative-ai) | `gemini-1.5-pro` | | | | | | [Google Vertex](/providers/ai-sdk-providers/google-vertex) | `gemini-2.0-flash-exp` | | | | | | [Google Vertex](/providers/ai-sdk-providers/google-vertex) | `gemini-1.5-flash` | | | | | | [Google Vertex](/providers/ai-sdk-providers/google-vertex) | `gemini-1.5-pro` | | | | | | [DeepSeek](/providers/ai-sdk-providers/deepseek) | `deepseek-chat` | | | | | | [DeepSeek](/providers/ai-sdk-providers/deepseek) | `deepseek-reasoner` | | | | | | [Cerebras](/providers/ai-sdk-providers/cerebras) | `llama3.1-8b` | | | | | | [Cerebras](/providers/ai-sdk-providers/cerebras) | `llama3.1-70b` | | | | | | [Cerebras](/providers/ai-sdk-providers/cerebras) | `llama3.3-70b` | | | | | | [Groq](/providers/ai-sdk-providers/groq) | `meta-llama/llama-4-scout-17b-16e-instruct` | | | | | | [Groq](/providers/ai-sdk-providers/groq) | `llama-3.3-70b-versatile` | | | | | | [Groq](/providers/ai-sdk-providers/groq) | `llama-3.1-8b-instant` | | | | | | [Groq](/providers/ai-sdk-providers/groq) | `mixtral-8x7b-32768` | | | | | | [Groq](/providers/ai-sdk-providers/groq) | `gemma2-9b-it` | | | | | This table is not exhaustive. Additional models can be found in the provider documentation pages and on the provider websites. On this page [Providers and Models](#providers-and-models) [AI SDK Providers](#ai-sdk-providers) [Self-Hosted Models](#self-hosted-models) [Model Capabilities](#model-capabilities) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Getting Started](#getting-started) ==================================== The following guides are intended to provide you with an introduction to some of the core features provided by the AI SDK. [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [SvelteKit](/docs/getting-started/svelte) [Nuxt](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Backend Framework Examples](#backend-framework-examples) ---------------------------------------------------------- You can also use [AI SDK Core](/docs/ai-sdk-core/overview) and [AI SDK UI](/docs/ai-sdk-ui/overview) with the following backend frameworks: [Node.js HTTP Server\ \ Send AI responses from a Node.js HTTP server.](/examples/api-servers/node-js-http-server) [Express\ \ Send AI responses from an Express server.](/examples/api-servers/express) [Hono\ \ Send AI responses from a Hono server.](/examples/api-servers/hono) [Fastify\ \ Send AI responses from a Fastify server.](/examples/api-servers/fastify) [Nest.js\ \ Send AI responses from a Nest.js server.](/examples/api-servers/nest) On this page [Getting Started](#getting-started) [Backend Framework Examples](#backend-framework-examples) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Foundations: Agents [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Agents](#agents) ================== When building AI applications, you often need **systems that can understand context and take meaningful actions**. When building these systems, the key consideration is finding the right balance between flexibility and control. Let's explore different approaches and patterns for building these systems, with a focus on helping you match capabilities to your needs. [Building Blocks](#building-blocks) ------------------------------------ When building AI systems, you can combine these fundamental components: ### [Single-Step LLM Generation](#single-step-llm-generation) The basic building block - one call to an LLM to get a response. Useful for straightforward tasks like classification or text generation. ### [Tool Usage](#tool-usage) Enhanced capabilities through tools (like calculators, APIs, or databases) that the LLM can use to accomplish tasks. Tools provide a controlled way to extend what the LLM can do. When solving complex problems, **an LLM can make multiple tool calls across multiple steps without you explicity specifying the order** - for example, looking up information in a database, using that to make calculations, and then storing results. The AI SDK makes this [multi-step tool usage](#multi-step-tool-usage) straightforward through the `maxSteps` parameter. ### [Multi-Agent Systems](#multi-agent-systems) Multiple LLMs working together, each specialized for different aspects of a complex task. This enables sophisticated behaviors while keeping individual components focused. [Patterns](#patterns) ---------------------- These building blocks can be combined with workflow patterns that help manage complexity: * [Sequential Processing](#sequential-processing-chains) - Steps executed in order * [Parallel Processing](#parallel-processing) - Independent tasks run simultaneously * [Evaluation/Feedback Loops](#evaluator-optimizer) - Results checked and improved iteratively * [Orchestration](#orchestrator-worker) - Coordinating multiple components * [Routing](#routing) - Directing work based on context [Choosing Your Approach](#choosing-your-approach) -------------------------------------------------- The key factors to consider: * **Flexibility vs Control** - How much freedom does the LLM need vs how tightly must you constrain its actions? * **Error Tolerance** - What are the consequences of mistakes in your use case? * **Cost Considerations** - More complex systems typically mean more LLM calls and higher costs * **Maintenance** - Simpler architectures are easier to debug and modify **Start with the simplest approach that meets your needs**. Add complexity only when required by: 1. Breaking down tasks into clear steps 2. Adding tools for specific capabilities 3. Implementing feedback loops for quality control 4. Introducing multiple agents for complex workflows Let's look at examples of these patterns in action. [Patterns with Examples](#patterns-with-examples) -------------------------------------------------- The following patterns, adapted from [Anthropic's guide on building effective agents](https://www.anthropic.com/research/building-effective-agents) , serve as building blocks that can be combined to create comprehensive workflows. Each pattern addresses specific aspects of task execution, and by combining them thoughtfully, you can build reliable solutions for complex problems. ### [Sequential Processing (Chains)](#sequential-processing-chains) The simplest workflow pattern executes steps in a predefined order. Each step's output becomes input for the next step, creating a clear chain of operations. This pattern is ideal for tasks with well-defined sequences, like content generation pipelines or data transformation processes. import { openai } from '@ai-sdk/openai';import { generateText, generateObject } from 'ai';import { z } from 'zod'; async function generateMarketingCopy(input: string) { const model = openai('gpt-4o'); // First step: Generate marketing copy const { text: copy } = await generateText({ model, prompt: `Write persuasive marketing copy for: ${input}. Focus on benefits and emotional appeal.`, }); // Perform quality check on copy const { object: qualityMetrics } = await generateObject({ model, schema: z.object({ hasCallToAction: z.boolean(), emotionalAppeal: z.number().min(1).max(10), clarity: z.number().min(1).max(10), }), prompt: `Evaluate this marketing copy for: 1. Presence of call to action (true/false) 2. Emotional appeal (1-10) 3. Clarity (1-10) Copy to evaluate: ${copy}`, }); // If quality check fails, regenerate with more specific instructions if ( !qualityMetrics.hasCallToAction || qualityMetrics.emotionalAppeal < 7 || qualityMetrics.clarity < 7 ) { const { text: improvedCopy } = await generateText({ model, prompt: `Rewrite this marketing copy with: ${!qualityMetrics.hasCallToAction ? '- A clear call to action' : ''} ${qualityMetrics.emotionalAppeal < 7 ? '- Stronger emotional appeal' : ''} ${qualityMetrics.clarity < 7 ? '- Improved clarity and directness' : ''} Original copy: ${copy}`, }); return { copy: improvedCopy, qualityMetrics }; } return { copy, qualityMetrics };} ### [Routing](#routing) This pattern allows the model to make decisions about which path to take through a workflow based on context and intermediate results. The model acts as an intelligent router, directing the flow of execution between different branches of your workflow. This is particularly useful when handling varied inputs that require different processing approaches. In the example below, the results of the first LLM call change the properties of the second LLM call like model size and system prompt. import { openai } from '@ai-sdk/openai';import { generateObject, generateText } from 'ai';import { z } from 'zod'; async function handleCustomerQuery(query: string) { const model = openai('gpt-4o'); // First step: Classify the query type const { object: classification } = await generateObject({ model, schema: z.object({ reasoning: z.string(), type: z.enum(['general', 'refund', 'technical']), complexity: z.enum(['simple', 'complex']), }), prompt: `Classify this customer query: ${query} Determine: 1. Query type (general, refund, or technical) 2. Complexity (simple or complex) 3. Brief reasoning for classification`, }); // Route based on classification // Set model and system prompt based on query type and complexity const { text: response } = await generateText({ model: classification.complexity === 'simple' ? openai('gpt-4o-mini') : openai('o3-mini'), system: { general: 'You are an expert customer service agent handling general inquiries.', refund: 'You are a customer service agent specializing in refund requests. Follow company policy and collect necessary information.', technical: 'You are a technical support specialist with deep product knowledge. Focus on clear step-by-step troubleshooting.', }[classification.type], prompt: query, }); return { response, classification };} ### [Parallel Processing](#parallel-processing) Some tasks can be broken down into independent subtasks that can be executed simultaneously. This pattern takes advantage of parallel execution to improve efficiency while maintaining the benefits of structured workflows. For example, analyzing multiple documents or processing different aspects of a single input concurrently (like code review). import { openai } from '@ai-sdk/openai';import { generateText, generateObject } from 'ai';import { z } from 'zod'; // Example: Parallel code review with multiple specialized reviewersasync function parallelCodeReview(code: string) { const model = openai('gpt-4o'); // Run parallel reviews const [securityReview, performanceReview, maintainabilityReview] = await Promise.all([ generateObject({ model, system: 'You are an expert in code security. Focus on identifying security vulnerabilities, injection risks, and authentication issues.', schema: z.object({ vulnerabilities: z.array(z.string()), riskLevel: z.enum(['low', 'medium', 'high']), suggestions: z.array(z.string()), }), prompt: `Review this code: ${code}`, }),\ generateObject({ model, system: 'You are an expert in code performance. Focus on identifying performance bottlenecks, memory leaks, and optimization opportunities.', schema: z.object({ issues: z.array(z.string()), impact: z.enum(['low', 'medium', 'high']), optimizations: z.array(z.string()), }), prompt: `Review this code: ${code}`, }),\ generateObject({ model, system: 'You are an expert in code quality. Focus on code structure, readability, and adherence to best practices.', schema: z.object({ concerns: z.array(z.string()), qualityScore: z.number().min(1).max(10), recommendations: z.array(z.string()), }), prompt: `Review this code: ${code}`, }), ]); const reviews = [ { ...securityReview.object, type: 'security' }, { ...performanceReview.object, type: 'performance' }, { ...maintainabilityReview.object, type: 'maintainability' }, ]; // Aggregate results using another model instance const { text: summary } = await generateText({ model, system: 'You are a technical lead summarizing multiple code reviews.', prompt: `Synthesize these code review results into a concise summary with key actions: ${JSON.stringify(reviews, null, 2)}`, }); return { reviews, summary };} ### [Orchestrator-Worker](#orchestrator-worker) In this pattern, a primary model (orchestrator) coordinates the execution of specialized workers. Each worker is optimized for a specific subtask, while the orchestrator maintains overall context and ensures coherent results. This pattern excels at complex tasks requiring different types of expertise or processing. import { openai } from '@ai-sdk/openai';import { generateObject } from 'ai';import { z } from 'zod'; async function implementFeature(featureRequest: string) { // Orchestrator: Plan the implementation const { object: implementationPlan } = await generateObject({ model: openai('o3-mini'), schema: z.object({ files: z.array( z.object({ purpose: z.string(), filePath: z.string(), changeType: z.enum(['create', 'modify', 'delete']), }), ), estimatedComplexity: z.enum(['low', 'medium', 'high']), }), system: 'You are a senior software architect planning feature implementations.', prompt: `Analyze this feature request and create an implementation plan: ${featureRequest}`, }); // Workers: Execute the planned changes const fileChanges = await Promise.all( implementationPlan.files.map(async file => { // Each worker is specialized for the type of change const workerSystemPrompt = { create: 'You are an expert at implementing new files following best practices and project patterns.', modify: 'You are an expert at modifying existing code while maintaining consistency and avoiding regressions.', delete: 'You are an expert at safely removing code while ensuring no breaking changes.', }[file.changeType]; const { object: change } = await generateObject({ model: openai('gpt-4o'), schema: z.object({ explanation: z.string(), code: z.string(), }), system: workerSystemPrompt, prompt: `Implement the changes for ${file.filePath} to support: ${file.purpose} Consider the overall feature context: ${featureRequest}`, }); return { file, implementation: change, }; }), ); return { plan: implementationPlan, changes: fileChanges, };} ### [Evaluator-Optimizer](#evaluator-optimizer) This pattern introduces quality control into workflows by having dedicated evaluation steps that assess intermediate results. Based on the evaluation, the workflow can either proceed, retry with adjusted parameters, or take corrective action. This creates more robust workflows capable of self-improvement and error recovery. import { openai } from '@ai-sdk/openai';import { generateText, generateObject } from 'ai';import { z } from 'zod'; async function translateWithFeedback(text: string, targetLanguage: string) { let currentTranslation = ''; let iterations = 0; const MAX_ITERATIONS = 3; // Initial translation const { text: translation } = await generateText({ model: openai('gpt-4o-mini'), // use small model for first attempt system: 'You are an expert literary translator.', prompt: `Translate this text to ${targetLanguage}, preserving tone and cultural nuances: ${text}`, }); currentTranslation = translation; // Evaluation-optimization loop while (iterations < MAX_ITERATIONS) { // Evaluate current translation const { object: evaluation } = await generateObject({ model: openai('gpt-4o'), // use a larger model to evaluate schema: z.object({ qualityScore: z.number().min(1).max(10), preservesTone: z.boolean(), preservesNuance: z.boolean(), culturallyAccurate: z.boolean(), specificIssues: z.array(z.string()), improvementSuggestions: z.array(z.string()), }), system: 'You are an expert in evaluating literary translations.', prompt: `Evaluate this translation: Original: ${text} Translation: ${currentTranslation} Consider: 1. Overall quality 2. Preservation of tone 3. Preservation of nuance 4. Cultural accuracy`, }); // Check if quality meets threshold if ( evaluation.qualityScore >= 8 && evaluation.preservesTone && evaluation.preservesNuance && evaluation.culturallyAccurate ) { break; } // Generate improved translation based on feedback const { text: improvedTranslation } = await generateText({ model: openai('gpt-4o'), // use a larger model system: 'You are an expert literary translator.', prompt: `Improve this translation based on the following feedback: ${evaluation.specificIssues.join('\n')} ${evaluation.improvementSuggestions.join('\n')} Original: ${text} Current Translation: ${currentTranslation}`, }); currentTranslation = improvedTranslation; iterations++; } return { finalTranslation: currentTranslation, iterationsRequired: iterations, };} [Multi-Step Tool Usage](#multi-step-tool-usage) ------------------------------------------------ If your use case involves solving problems where the solution path is poorly defined or too complex to map out as a workflow in advance, you may want to provide the LLM with a set of lower-level tools and allow it to break down the task into small pieces that it can solve on its own iteratively, without discrete instructions. To implement this kind of agentic pattern, you need to call an LLM in a loop until a task is complete. The AI SDK makes this simple with the `maxSteps` parameter. With `maxSteps`, the AI SDK automatically triggers an additional request to the model after every tool result (each request is considered a "step"). If the model does not generate a tool call or the `maxSteps` threshold has been met, the generation is complete. `maxSteps` can be used with both `generateText` and `streamText` ### [Using maxSteps](#using-maxsteps) This example demonstrates how to create an agent that solves math problems. It has a calculator tool (using [math.js](https://mathjs.org/) ) that it can call to evaluate mathematical expressions. import { openai } from '@ai-sdk/openai';import { generateText, tool } from 'ai';import * as mathjs from 'mathjs';import { z } from 'zod'; const { text: answer } = await generateText({ model: openai('gpt-4o-2024-08-06', { structuredOutputs: true }), tools: { calculate: tool({ description: 'A tool for evaluating mathematical expressions. ' + 'Example expressions: ' + "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.", parameters: z.object({ expression: z.string() }), execute: async ({ expression }) => mathjs.evaluate(expression), }), }, maxSteps: 10, system: 'You are solving math problems. ' + 'Reason step by step. ' + 'Use the calculator when necessary. ' + 'When you give the final answer, ' + 'provide an explanation for how you arrived at it.', prompt: 'A taxi driver earns $9461 per 1-hour of work. ' + 'If he works 12 hours a day and in 1 hour ' + 'he uses 12 liters of petrol with a price of $134 for 1 liter. ' + 'How much money does he earn in one day?',}); console.log(`ANSWER: ${answer}`); ### [Structured Answers](#structured-answers) When building an agent for tasks like mathematical analysis or report generation, it's often useful to have the agent's final output structured in a consistent format that your application can process. You can use an **answer tool** and the `toolChoice: 'required'` setting to force the LLM to answer with a structured output that matches the schema of the answer tool. The answer tool has no `execute` function, so invoking it will terminate the agent. import { openai } from '@ai-sdk/openai';import { generateText, tool } from 'ai';import 'dotenv/config';import { z } from 'zod'; const { toolCalls } = await generateText({ model: openai('gpt-4o-2024-08-06', { structuredOutputs: true }), tools: { calculate: tool({ description: 'A tool for evaluating mathematical expressions. Example expressions: ' + "'1.2 * (2 + 4.5)', '12.7 cm to inch', 'sin(45 deg) ^ 2'.", parameters: z.object({ expression: z.string() }), execute: async ({ expression }) => mathjs.evaluate(expression), }), // answer tool: the LLM will provide a structured answer answer: tool({ description: 'A tool for providing the final answer.', parameters: z.object({ steps: z.array( z.object({ calculation: z.string(), reasoning: z.string(), }), ), answer: z.string(), }), // no execute function - invoking it will terminate the agent }), }, toolChoice: 'required', maxSteps: 10, system: 'You are solving math problems. ' + 'Reason step by step. ' + 'Use the calculator when necessary. ' + 'The calculator can only do simple additions, subtractions, multiplications, and divisions. ' + 'When you give the final answer, provide an explanation for how you got it.', prompt: 'A taxi driver earns $9461 per 1-hour work. ' + 'If he works 12 hours a day and in 1 hour he uses 14-liters petrol with price $134 for 1-liter. ' + 'How much money does he earn in one day?',}); console.log(`FINAL TOOL CALLS: ${JSON.stringify(toolCalls, null, 2)}`); You can also use the [`experimental_output`](/docs/ai-sdk-core/generating-structured-data#structured-output-with-generatetext) setting for `generateText` to generate structured outputs. ### [Accessing all steps](#accessing-all-steps) Calling `generateText` with `maxSteps` can result in several calls to the LLM (steps). You can access information from all steps by using the `steps` property of the response. import { generateText } from 'ai'; const { steps } = await generateText({ model: openai('gpt-4o'), maxSteps: 10, // ...}); // extract all tool calls from the steps:const allToolCalls = steps.flatMap(step => step.toolCalls); ### [Getting notified on each completed step](#getting-notified-on-each-completed-step) You can use the `onStepFinish` callback to get notified on each completed step. It is triggered when a step is finished, i.e. all text deltas, tool calls, and tool results for the step are available. import { generateText } from 'ai'; const result = await generateText({ model: yourModel, maxSteps: 10, onStepFinish({ text, toolCalls, toolResults, finishReason, usage }) { // your own logic, e.g. for saving the chat history or recording usage }, // ...}); On this page [Agents](#agents) [Building Blocks](#building-blocks) [Single-Step LLM Generation](#single-step-llm-generation) [Tool Usage](#tool-usage) [Multi-Agent Systems](#multi-agent-systems) [Patterns](#patterns) [Choosing Your Approach](#choosing-your-approach) [Patterns with Examples](#patterns-with-examples) [Sequential Processing (Chains)](#sequential-processing-chains) [Routing](#routing) [Parallel Processing](#parallel-processing) [Orchestrator-Worker](#orchestrator-worker) [Evaluator-Optimizer](#evaluator-optimizer) [Multi-Step Tool Usage](#multi-step-tool-usage) [Using maxSteps](#using-maxsteps) [Structured Answers](#structured-answers) [Accessing all steps](#accessing-all-steps) [Getting notified on each completed step](#getting-notified-on-each-completed-step) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Navigating the Library [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Navigating the Library](#navigating-the-library) ================================================== the AI SDK is a powerful toolkit for building AI applications. This page will help you pick the right tools for your requirements. Let’s start with a quick overview of the AI SDK, which is comprised of three parts: * **[AI SDK Core](/docs/ai-sdk-core/overview) :** A unified, provider agnostic API for generating text, structured objects, and tool calls with LLMs. * **[AI SDK UI](/docs/ai-sdk-ui/overview) :** A set of framework-agnostic hooks for building chat and generative user interfaces. * [AI SDK RSC](/docs/ai-sdk-rsc/overview) : Stream generative user interfaces with React Server Components (RSC). Development is currently experimental and we recommend using [AI SDK UI](/docs/ai-sdk-ui/overview) . [Choosing the Right Tool for Your Environment](#choosing-the-right-tool-for-your-environment) ---------------------------------------------------------------------------------------------- When deciding which part of the AI SDK to use, your first consideration should be the environment and existing stack you are working with. Different components of the SDK are tailored to specific frameworks and environments. | Library | Purpose | Environment Compatibility | | --- | --- | --- | | [AI SDK Core](/docs/ai-sdk-core/overview) | Call any LLM with unified API (e.g. [generateText](/docs/reference/ai-sdk-core/generate-text)
and [generateObject](/docs/reference/ai-sdk-core/generate-object)
) | Any JS environment (e.g. Node.js, Deno, Browser) | | [AI SDK UI](/docs/ai-sdk-ui/overview) | Build streaming chat and generative UIs (e.g. [useChat](/docs/reference/ai-sdk-ui/use-chat)
) | React & Next.js, Vue & Nuxt, Svelte & SvelteKit, Solid.js & SolidStart | | [AI SDK RSC](/docs/ai-sdk-rsc/overview) | Stream generative UIs from Server to Client (e.g. [streamUI](/docs/reference/ai-sdk-rsc/stream-ui)
). Development is currently experimental and we recommend using [AI SDK UI](/docs/ai-sdk-ui/overview)
. | Any framework that supports React Server Components (e.g. Next.js) | [Environment Compatibility](#environment-compatibility) -------------------------------------------------------- These tools have been designed to work seamlessly with each other and it's likely that you will be using them together. Let's look at how you could decide which libraries to use based on your application environment, existing stack, and requirements. The following table outlines AI SDK compatibility based on environment: | Environment | [AI SDK Core](/docs/ai-sdk-core/overview) | [AI SDK UI](/docs/ai-sdk-ui/overview) | [AI SDK RSC](/docs/ai-sdk-rsc/overview) | | --- | --- | --- | --- | | None / Node.js / Deno | | | | | Vue / Nuxt | | | | | Svelte / SvelteKit | | | | | Solid.js / SolidStart | | | | | Next.js Pages Router | | | | | Next.js App Router | | | | [When to use AI SDK UI](#when-to-use-ai-sdk-ui) ------------------------------------------------ AI SDK UI provides a set of framework-agnostic hooks for quickly building **production-ready AI-native applications**. It offers: * Full support for streaming chat and client-side generative UI * Utilities for handling common AI interaction patterns (i.e. chat, completion, assistant) * Production-tested reliability and performance * Compatibility across popular frameworks [AI SDK UI Framework Compatibility](#ai-sdk-ui-framework-compatibility) ------------------------------------------------------------------------ AI SDK UI supports the following frameworks: [React](https://react.dev/) , [Svelte](https://svelte.dev/) , [Vue.js](https://vuejs.org/) , and [SolidJS](https://www.solidjs.com/) . Here is a comparison of the supported functions across these frameworks: | Function | React | Svelte | Vue.js | SolidJS | | --- | --- | --- | --- | --- | | [useChat](/docs/reference/ai-sdk-ui/use-chat) | | | | | | [useChat](/docs/reference/ai-sdk-ui/use-chat)
tool calling | | | | | | [useCompletion](/docs/reference/ai-sdk-ui/use-completion) | | | | | | [useObject](/docs/reference/ai-sdk-ui/use-object) | | | | | | [useAssistant](/docs/reference/ai-sdk-ui/use-assistant) | | | | | [Contributions](https://github.com/vercel/ai/blob/main/CONTRIBUTING.md) are welcome to implement missing features for non-React frameworks. [When to use AI SDK RSC](#when-to-use-ai-sdk-rsc) -------------------------------------------------- AI SDK RSC is currently experimental. We recommend using [AI SDK UI](/docs/ai-sdk-ui/overview) for production. For guidance on migrating from RSC to UI, see our [migration guide](/docs/ai-sdk-rsc/migrating-to-ui) . [React Server Components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) (RSCs) provide a new approach to building React applications that allow components to render on the server, fetch data directly, and stream the results to the client, reducing bundle size and improving performance. They also introduce a new way to call server-side functions from anywhere in your application called [Server Actions](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations) . AI SDK RSC provides a number of utilities that allow you to stream values and UI directly from the server to the client. However, **it's important to be aware of current limitations**: * **Cancellation**: currently, it is not possible to abort a stream using Server Actions. This will be improved in future releases of React and Next.js. * **Increased Data Transfer**: using [`createStreamableUI`](/docs/reference/ai-sdk-rsc/create-streamable-ui) can lead to quadratic data transfer (quadratic to the length of generated text). You can avoid this using [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value) instead, and rendering the component client-side. * **Re-mounting Issue During Streaming**: when using `createStreamableUI`, components re-mount on `.done()`, causing [flickering](https://github.com/vercel/ai/issues/2232) . Given these limitations, **we recommend using [AI SDK UI](/docs/ai-sdk-ui/overview) for production applications**. On this page [Navigating the Library](#navigating-the-library) [Choosing the Right Tool for Your Environment](#choosing-the-right-tool-for-your-environment) [Environment Compatibility](#environment-compatibility) [When to use AI SDK UI](#when-to-use-ai-sdk-ui) [AI SDK UI Framework Compatibility](#ai-sdk-ui-framework-compatibility) [When to use AI SDK RSC](#when-to-use-ai-sdk-rsc) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Next.js Pages Router [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Next.js Pages Router Quickstart](#nextjs-pages-router-quickstart) =================================================================== The AI SDK is a powerful Typescript library designed to help developers build AI-powered applications. In this quickstart tutorial, you'll build a simple AI-chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming) , you can optionally read these documents first. [Prerequisites](#prerequisites) -------------------------------- To follow this quickstart, you'll need: * Node.js 18+ and pnpm installed on your local development machine. * An OpenAI API key. If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. [Setup Your Application](#setup-your-application) -------------------------------------------------- Start by creating a new Next.js application. This command will create a new directory named `my-ai-app` and set up a basic Next.js application inside it. Be sure to select no when prompted to use the App Router. If you are looking for the Next.js App Router quickstart guide, you can find it [here](/docs/getting-started/nextjs-app-router) . pnpm create next-app@latest my-ai-app Navigate to the newly created directory: cd my-ai-app ### [Install dependencies](#install-dependencies) Install `ai`, `@ai-sdk/react`, and `@ai-sdk/openai`, the AI package, AI SDK's React hooks, and AI SDK's [OpenAI provider](/providers/ai-sdk-providers/openai) respectively. The AI SDK is designed to be a unified interface to interact with any large language model. This means that you can change model and providers with just one line of code! Learn more about [available providers](/providers) and [building custom providers](/providers/community-providers/custom-providers) in the [providers](/providers) section. pnpm npm yarn pnpm add ai @ai-sdk/openai zod Make sure you are using `ai` version 3.1 or higher. ### [Configure OpenAI API Key](#configure-openai-api-key) Create a `.env.local` file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. touch .env.local Edit the `.env.local` file: .env.local OPENAI_API_KEY=xxxxxxxxx Replace `xxxxxxxxx` with your actual OpenAI API key. The AI SDK's OpenAI Provider will default to using the `OPENAI_API_KEY` environment variable. [Create a Route Handler](#create-a-route-handler) -------------------------------------------------- As long as you are on Next.js 13+, you can use Route Handlers (using the App Router) alongside the Pages Router. This is recommended to enable you to use the Web APIs interface/signature and to better support streaming. Create a Route Handler (`app/api/chat/route.ts`) and add the following code: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText } from 'ai'; // Allow streaming responses up to 30 secondsexport const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, }); return result.toDataStreamResponse();} Let's take a look at what is happening in this code: 1. Define an asynchronous `POST` request handler and extract `messages` from the body of the request. The `messages` variable contains a history of the conversation between you and the chatbot and provides the chatbot with the necessary context to make the next generation. 2. Call [`streamText`](/docs/reference/ai-sdk-core/stream-text) , which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider (imported from `@ai-sdk/openai`) and `messages` (defined in step 1). You can pass additional [settings](/docs/ai-sdk-core/settings) to further customise the model's behaviour. 3. The `streamText` function returns a [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text#result-object) . This result object contains the [`toDataStreamResponse`](/docs/reference/ai-sdk-core/stream-text#to-data-stream-response) function which converts the result to a streamed response object. 4. Finally, return the result to the client to stream the response. This Route Handler creates a POST request endpoint at `/api/chat`. [Wire up the UI](#wire-up-the-ui) ---------------------------------- Now that you have an API route that can query an LLM, it's time to setup your frontend. The AI SDK's [UI](/docs/ai-sdk-ui) package abstract the complexity of a chat interface into one hook, [`useChat`](/docs/reference/ai-sdk-ui/use-chat) . Update your root page (`pages/index.tsx`) with the following code to show a list of chat messages and provide a user message input: pages/index.tsx import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat(); return (
{messages.map(message => (
{message.role === 'user' ? 'User: ' : 'AI: '} {message.parts.map((part, i) => { switch (part.type) { case 'text': return
{part.text}
; } })}
))}
);} This page utilizes the `useChat` hook, which will, by default, use the `POST` API route you created earlier (`/api/chat`). The hook provides functions and state for handling user input and form submission. The `useChat` hook provides multiple utility functions and state variables: * `messages` - the current chat messages (an array of objects with `id`, `role`, and `parts` properties). * `input` - the current value of the user's input field. * `handleInputChange` and `handleSubmit` - functions to handle user interactions (typing into the input field and submitting the form, respectively). The LLM's response is accessed through the message `parts` array. Each message contains an ordered array of `parts` that represents everything the model generated in its response. These parts can include plain text, reasoning tokens, and more that you will see later. The `parts` array preserves the sequence of the model's outputs, allowing you to display or process each component in the order it was generated. [Running Your Application](#running-your-application) ------------------------------------------------------ With that, you have built everything you need for your chatbot! To start your application, use the command: pnpm run dev Head to your browser and open [http://localhost:3000](http://localhost:3000) . You should see an input field. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Next.js. [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) -------------------------------------------------------------------- While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. Let's enhance your chatbot by adding a simple weather tool. ### [Update Your Route Handler](#update-your-route-handler) Modify your `app/api/chat/route.ts` file to include the new weather tool: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; export const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), }, }); return result.toDataStreamResponse();} In this updated code: 1. You import the `tool` function from the `ai` package and `z` from `zod` for schema validation. 2. You define a `tools` object with a `weather` tool. This tool: * Has a description that helps the model understand when to use it. * Defines parameters using a Zod schema, specifying that it requires a `location` string to execute this tool. The model will attempt to extract this parameter from the context of the conversation. If it can't, it will ask the user for the missing information. * Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function running on the server so you can fetch real data from an external API. Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary parameters. The `execute` function will then be automatically run, and you can access the results via `toolInvocations` that is available on the message object. Try asking something like "What's the weather in New York?" and see how the model uses the new tool. Notice the blank response in the UI? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result in the `toolInvocations` key of the message object. ### [Update the UI](#update-the-ui) To display the tool invocations in your UI, update your `pages/index.tsx` file: pages/index.tsx import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat(); return (
{messages.map(message => (
{message.role === 'user' ? 'User: ' : 'AI: '} {message.parts.map((part, i) => { switch (part.type) { case 'text': return
{part.text}
; case 'tool-invocation': return ( 
                    {JSON.stringify(part.toolInvocation, null, 2)}
); } })}
))}
);} With this change, you're updating the UI to handle different message parts. For text parts, you display the text content as before. For tool invocations, you display a JSON representation of the tool call and its result. Now, when you ask about the weather, you'll see the tool invocation and its result displayed in your chat interface. [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) ------------------------------------------------------------------ You may have noticed that while the tool results are visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. To solve this, you can enable multi-step tool calls using the `maxSteps` option in your `useChat` hook. This feature will automatically send tool results back to the model to trigger an additional generation. In this case, you want the model to answer your question using the results from the weather tool. ### [Update Your Client-Side Code](#update-your-client-side-code) Modify your `pages/index.tsx` file to include the `maxSteps` option: pages/index.tsx import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat({ maxSteps: 5, }); // ... rest of your component code} Head back to the browser and ask about the weather in a location. You should now see the model using the weather tool results to answer your question. By setting `maxSteps` to 5, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Fahrenheit to Celsius. ### [Update Your Route Handler](#update-your-route-handler-1) Update your `app/api/chat/route.ts` file to add a new tool to convert the temperature from Fahrenheit to Celsius: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; export const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), convertFahrenheitToCelsius: tool({ description: 'Convert a temperature in fahrenheit to celsius', parameters: z.object({ temperature: z .number() .describe('The temperature in fahrenheit to convert'), }), execute: async ({ temperature }) => { const celsius = Math.round((temperature - 32) * (5 / 9)); return { celsius, }; }, }), }, }); return result.toDataStreamResponse();} Now, when you ask "What's the weather in New York in celsius?", you should see a more complete interaction: 1. The model will call the weather tool for New York. 2. You'll see the tool result displayed. 3. It will then call the temperature conversion tool to convert the temperature from Fahrenheit to Celsius. 4. The model will then use that information to provide a natural language response about the weather in New York. This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. This simple example demonstrates how tools can expand your model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. [Where to Next?](#where-to-next) --------------------------------- You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: * To learn more about the AI SDK, read through the [documentation](/docs) . * If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. * To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai) . On this page [Next.js Pages Router Quickstart](#nextjs-pages-router-quickstart) [Prerequisites](#prerequisites) [Setup Your Application](#setup-your-application) [Install dependencies](#install-dependencies) [Configure OpenAI API Key](#configure-openai-api-key) [Create a Route Handler](#create-a-route-handler) [Wire up the UI](#wire-up-the-ui) [Running Your Application](#running-your-application) [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) [Update Your Route Handler](#update-your-route-handler) [Update the UI](#update-the-ui) [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) [Update Your Client-Side Code](#update-your-client-side-code) [Update Your Route Handler](#update-your-route-handler-1) [Where to Next?](#where-to-next) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Next.js App Router [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Next.js App Router Quickstart](#nextjs-app-router-quickstart) =============================================================== In this quick start tutorial, you'll build a simple AI-chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. Check out [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming) if you haven't heard of them. [Prerequisites](#prerequisites) -------------------------------- To follow this quickstart, you'll need: * Node.js 18+ and pnpm installed on your local development machine. * An OpenAI API key. If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. [Create Your Application](#create-your-application) ---------------------------------------------------- Start by creating a new Next.js application. This command will create a new directory named `my-ai-app` and set up a basic Next.js application inside it. Be sure to select yes when prompted to use the App Router and Tailwind CSS. If you are looking for the Next.js Pages Router quickstart guide, you can find it [here](/docs/getting-started/nextjs-pages-router) . pnpm create next-app@latest my-ai-app Navigate to the newly created directory: cd my-ai-app ### [Install dependencies](#install-dependencies) Install `ai`, `@ai-sdk/react`, and `@ai-sdk/openai`, the AI package, AI SDK's React hooks, and AI SDK's [OpenAI provider](/providers/ai-sdk-providers/openai) respectively. The AI SDK is designed to be a unified interface to interact with any large language model. This means that you can change model and providers with just one line of code! Learn more about [available providers](/providers) and [building custom providers](/providers/community-providers/custom-providers) in the [providers](/providers) section. pnpm npm yarn pnpm add ai @ai-sdk/react @ai-sdk/openai zod Make sure you are using `ai` version 3.1 or higher. ### [Configure OpenAI API key](#configure-openai-api-key) Create a `.env.local` file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. touch .env.local Edit the `.env.local` file: .env.local OPENAI_API_KEY=xxxxxxxxx Replace `xxxxxxxxx` with your actual OpenAI API key. The AI SDK's OpenAI Provider will default to using the `OPENAI_API_KEY` environment variable. [Create a Route Handler](#create-a-route-handler) -------------------------------------------------- Create a route handler, `app/api/chat/route.ts` and add the following code: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText } from 'ai'; // Allow streaming responses up to 30 secondsexport const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, }); return result.toDataStreamResponse();} Let's take a look at what is happening in this code: 1. Define an asynchronous `POST` request handler and extract `messages` from the body of the request. The `messages` variable contains a history of the conversation between you and the chatbot and provides the chatbot with the necessary context to make the next generation. 2. Call [`streamText`](/docs/reference/ai-sdk-core/stream-text) , which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider (imported from `@ai-sdk/openai`) and `messages` (defined in step 1). You can pass additional [settings](/docs/ai-sdk-core/settings) to further customise the model's behaviour. 3. The `streamText` function returns a [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text#result-object) . This result object contains the [`toDataStreamResponse`](/docs/reference/ai-sdk-core/stream-text#to-data-stream-response) function which converts the result to a streamed response object. 4. Finally, return the result to the client to stream the response. This Route Handler creates a POST request endpoint at `/api/chat`. [Wire up the UI](#wire-up-the-ui) ---------------------------------- Now that you have a Route Handler that can query an LLM, it's time to setup your frontend. The AI SDK's [UI](/docs/ai-sdk-ui) package abstracts the complexity of a chat interface into one hook, [`useChat`](/docs/reference/ai-sdk-ui/use-chat) . Update your root page (`app/page.tsx`) with the following code to show a list of chat messages and provide a user message input: app/page.tsx 'use client'; import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat(); return (
{messages.map(message => (
{message.role === 'user' ? 'User: ' : 'AI: '} {message.parts.map((part, i) => { switch (part.type) { case 'text': return
{part.text}
; } })}
))}
);} Make sure you add the `"use client"` directive to the top of your file. This allows you to add interactivity with Javascript. This page utilizes the `useChat` hook, which will, by default, use the `POST` API route you created earlier (`/api/chat`). The hook provides functions and state for handling user input and form submission. The `useChat` hook provides multiple utility functions and state variables: * `messages` - the current chat messages (an array of objects with `id`, `role`, and `parts` properties). * `input` - the current value of the user's input field. * `handleInputChange` and `handleSubmit` - functions to handle user interactions (typing into the input field and submitting the form, respectively). The LLM's response is accessed through the message `parts` array. Each message contains an ordered array of `parts` that represents everything the model generated in its response. These parts can include plain text, reasoning tokens, and more that you will see later. The `parts` array preserves the sequence of the model's outputs, allowing you to display or process each component in the order it was generated. [Running Your Application](#running-your-application) ------------------------------------------------------ With that, you have built everything you need for your chatbot! To start your application, use the command: pnpm run dev Head to your browser and open [http://localhost:3000](http://localhost:3000) . You should see an input field. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Next.js. [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) -------------------------------------------------------------------- While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. Let's enhance your chatbot by adding a simple weather tool. ### [Update Your Route Handler](#update-your-route-handler) Modify your `app/api/chat/route.ts` file to include the new weather tool: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; export const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), }, }); return result.toDataStreamResponse();} In this updated code: 1. You import the `tool` function from the `ai` package and `z` from `zod` for schema validation. 2. You define a `tools` object with a `weather` tool. This tool: * Has a description that helps the model understand when to use it. * Defines parameters using a Zod schema, specifying that it requires a `location` string to execute this tool. The model will attempt to extract this parameter from the context of the conversation. If it can't, it will ask the user for the missing information. * Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function running on the server so you can fetch real data from an external API. Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary parameters. The `execute` function will then be automatically run, and you can access the results via `tool-invocations` part that is available on the `message.parts` array. Try asking something like "What's the weather in New York?" and see how the model uses the new tool. Notice the blank response in the UI? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result via the `tool-invocation` part of the `message.parts` array. ### [Update the UI](#update-the-ui) To display the tool invocations in your UI, update your `app/page.tsx` file: app/page.tsx 'use client'; import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat(); return (
{messages.map(message => (
{message.role === 'user' ? 'User: ' : 'AI: '} {message.parts.map((part, i) => { switch (part.type) { case 'text': return
{part.text}
; case 'tool-invocation': return ( 
                    {JSON.stringify(part.toolInvocation, null, 2)}
); } })}
))}
);} With this change, you're updating the UI to handle different message parts. For text parts, you display the text content as before. For tool invocations, you display a JSON representation of the tool call and its result. Now, when you ask about the weather, you'll see the tool invocation and its result displayed in your chat interface. [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) ------------------------------------------------------------------ You may have noticed that while the tool results are visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. To solve this, you can enable multi-step tool calls using the `maxSteps` option in your `useChat` hook. This feature will automatically send tool results back to the model to trigger an additional generation. In this case, you want the model to answer your question using the results from the weather tool. ### [Update Your Client-Side Code](#update-your-client-side-code) Modify your `app/page.tsx` file to include the `maxSteps` option: app/page.tsx 'use client'; import { useChat } from '@ai-sdk/react'; export default function Chat() { const { messages, input, handleInputChange, handleSubmit } = useChat({ maxSteps: 5, }); // ... rest of your component code} Head back to the browser and ask about the weather in a location. You should now see the model using the weather tool results to answer your question. By setting `maxSteps` to 5, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Fahrenheit to Celsius. ### [Update Your Route Handler](#update-your-route-handler-1) Update your `app/api/chat/route.ts` file to add a new tool to convert the temperature from Fahrenheit to Celsius: app/api/chat/route.ts import { openai } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; export const maxDuration = 30; export async function POST(req: Request) { const { messages } = await req.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), convertFahrenheitToCelsius: tool({ description: 'Convert a temperature in fahrenheit to celsius', parameters: z.object({ temperature: z .number() .describe('The temperature in fahrenheit to convert'), }), execute: async ({ temperature }) => { const celsius = Math.round((temperature - 32) * (5 / 9)); return { celsius, }; }, }), }, }); return result.toDataStreamResponse();} Now, when you ask "What's the weather in New York in celsius?", you should see a more complete interaction: 1. The model will call the weather tool for New York. 2. You'll see the tool result displayed. 3. It will then call the temperature conversion tool to convert the temperature from Fahrenheit to Celsius. 4. The model will then use that information to provide a natural language response about the weather in New York. This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. This simple example demonstrates how tools can expand your model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. [Where to Next?](#where-to-next) --------------------------------- You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: * To learn more about the AI SDK, read through the [documentation](/docs) . * If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. * To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai) . On this page [Next.js App Router Quickstart](#nextjs-app-router-quickstart) [Prerequisites](#prerequisites) [Create Your Application](#create-your-application) [Install dependencies](#install-dependencies) [Configure OpenAI API key](#configure-openai-api-key) [Create a Route Handler](#create-a-route-handler) [Wire up the UI](#wire-up-the-ui) [Running Your Application](#running-your-application) [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) [Update Your Route Handler](#update-your-route-handler) [Update the UI](#update-the-ui) [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) [Update Your Client-Side Code](#update-your-client-side-code) [Update Your Route Handler](#update-your-route-handler-1) [Where to Next?](#where-to-next) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Svelte [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Svelte Quickstart](#svelte-quickstart) ======================================== The AI SDK is a powerful Typescript library designed to help developers build AI-powered applications. In this quickstart tutorial, you'll build a simple AI-chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming) , you can optionally read these documents first. [Prerequisites](#prerequisites) -------------------------------- To follow this quickstart, you'll need: * Node.js 18+ and pnpm installed on your local development machine. * An OpenAI API key. If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. [Set Up Your Application](#set-up-your-application) ---------------------------------------------------- This guide applies to SvelteKit versions 4 and below. Start by creating a new SvelteKit application. This command will create a new directory named `my-ai-app` and set up a basic SvelteKit application inside it. npx sv create my-ai-app Navigate to the newly created directory: cd my-ai-app ### [Install Dependencies](#install-dependencies) Install `ai` and `@ai-sdk/openai`, the AI SDK's OpenAI provider. The AI SDK is designed to be a unified interface to interact with any large language model. This means that you can change model and providers with just one line of code! Learn more about [available providers](/providers) and [building custom providers](/providers/community-providers/custom-providers) in the [providers](/providers) section. pnpm npm yarn pnpm add -D ai @ai-sdk/openai @ai-sdk/svelte zod Make sure you are using `ai` version 3.1 or higher. ### [Configure OpenAI API Key](#configure-openai-api-key) Create a `.env.local` file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. touch .env.local Edit the `.env.local` file: .env.local OPENAI_API_KEY=xxxxxxxxx Replace `xxxxxxxxx` with your actual OpenAI API key. Vite does not automatically load environment variables onto `process.env`, so you'll need to import `OPENAI_API_KEY` from `$env/static/private` in your code (see below). [Create an API route](#create-an-api-route) -------------------------------------------- Create a SvelteKit Endpoint, `src/routes/api/chat/+server.ts` and add the following code: src/routes/api/chat/+server.ts import { createOpenAI } from '@ai-sdk/openai';import { streamText } from 'ai'; import { OPENAI_API_KEY } from '$env/static/private'; const openai = createOpenAI({ apiKey: OPENAI_API_KEY,}); export async function POST({ request }) { const { messages } = await request.json(); const result = streamText({ model: openai('gpt-4o'), messages, }); return result.toDataStreamResponse();} If you see type errors with `OPENAI_API_KEY` or your `POST` function, run the dev server. Let's take a look at what is happening in this code: 1. Create an OpenAI provider instance with the `createOpenAI` function from the `@ai-sdk/openai` package. 2. Define a `POST` request handler and extract `messages` from the body of the request. The `messages` variable contains a history of the conversation with you and the chatbot and will provide the chatbot with the necessary context to make the next generation. 3. Call [`streamText`](/docs/reference/ai-sdk-core/stream-text) , which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider (defined in step 1) and `messages` (defined in step 2). You can pass additional [settings](/docs/ai-sdk-core/settings) to further customise the model's behaviour. 4. The `streamText` function returns a [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text#result-object) . This result object contains the [`toDataStreamResponse`](/docs/reference/ai-sdk-core/stream-text#to-data-stream-response) function which converts the result to a streamed response object. 5. Return the result to the client to stream the response. [Wire up the UI](#wire-up-the-ui) ---------------------------------- Now that you have an API route that can query an LLM, it's time to set up your frontend. The AI SDK's [UI](/docs/ai-sdk-ui) package abstracts the complexity of a chat interface into one class, `Chat`. Its properties and API are largely the same as React's [`useChat`](/docs/reference/ai-sdk-ui/use-chat) . Update your root page (`src/routes/+page.svelte`) with the following code to show a list of chat messages and provide a user message input: src/routes/+page.svelte
This page utilizes the `Chat` class, which will, by default, use the `POST` route handler you created earlier. The hook provides functions and state for handling user input and form submission. The `Chat` class provides multiple utility functions and state variables: * `messages` - the current chat messages (an array of objects with `id`, `role`, and `parts` properties). * `input` - the current value of the user's input field. * `handleSubmit` - function to handle form submission. The LLM's response is accessed through the message `parts` array. Each message contains an ordered array of `parts` that represents everything the model generated in its response. These parts can include plain text, reasoning tokens, and more that you will see later. The `parts` array preserves the sequence of the model's outputs, allowing you to display or process each component in the order it was generated. [Running Your Application](#running-your-application) ------------------------------------------------------ With that, you have built everything you need for your chatbot! To start your application, use the command: pnpm run dev Head to your browser and open [http://localhost:5173](http://localhost:5173) . You should see an input field. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Svelte. [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) -------------------------------------------------------------------- While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. Let's enhance your chatbot by adding a simple weather tool. ### [Update Your API Route](#update-your-api-route) Modify your `src/routes/api/chat/+server.ts` file to include the new weather tool: src/routes/api/chat/+server.ts import { createOpenAI } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; import { OPENAI_API_KEY } from '$env/static/private'; const openai = createOpenAI({ apiKey: OPENAI_API_KEY,}); export async function POST({ request }) { const { messages } = await request.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), }, }); return result.toDataStreamResponse();} In this updated code: 1. You import the `tool` function from the `ai` package and `z` from `zod` for schema validation. 2. You define a `tools` object with a `weather` tool. This tool: * Has a description that helps the model understand when to use it. * Defines parameters using a Zod schema, specifying that it requires a `location` string to execute this tool. The model will attempt to extract this parameter from the context of the conversation. If it can't, it will ask the user for the missing information. * Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function running on the server so you can fetch real data from an external API. Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary parameters. The `execute` function will then be automatically run, and you can access the results via `tool-invocations` part that is available on the `message.parts` array. Try asking something like "What's the weather in New York?" and see how the model uses the new tool. Notice the blank response in the UI? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result via the `tool-invocation` part of the `message.parts` array. ### [Update the UI](#update-the-ui) To display the tool invocations in your UI, update your `src/routes/+page.svelte` file: src/routes/+page.svelte
With this change, you're updating the UI to handle different message parts. For text parts, you display the text content as before. For tool invocations, you display a JSON representation of the tool call and its result. Now, when you ask about the weather, you'll see the tool invocation and its result displayed in your chat interface. [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) ------------------------------------------------------------------ You may have noticed that while the tool results are visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. To solve this, you can enable multi-step tool calls using the `maxSteps` option in your `Chat` class. This feature will automatically send tool results back to the model to trigger an additional generation. In this case, you want the model to answer your question using the results from the weather tool. ### [Update Your UI](#update-your-ui) Modify your `src/routes/+page.svelte` file to include the `maxSteps` option: src/routes/+page.svelte Head back to the browser and ask about the weather in a location. You should now see the model using the weather tool results to answer your question. By setting `maxSteps` to 5, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Fahrenheit to Celsius. ### [Update Your API Route](#update-your-api-route-1) Update your `src/routes/api/chat/+server.ts` file to add a new tool to convert the temperature from Fahrenheit to Celsius: src/routes/api/chat/+server.ts import { createOpenAI } from '@ai-sdk/openai';import { streamText, tool } from 'ai';import { z } from 'zod'; import { OPENAI_API_KEY } from '$env/static/private'; const openai = createOpenAI({ apiKey: OPENAI_API_KEY,}); export async function POST({ request }) { const { messages } = await request.json(); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z.string().describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), convertFahrenheitToCelsius: tool({ description: 'Convert a temperature in fahrenheit to celsius', parameters: z.object({ temperature: z .number() .describe('The temperature in fahrenheit to convert'), }), execute: async ({ temperature }) => { const celsius = Math.round((temperature - 32) * (5 / 9)); return { celsius, }; }, }), }, }); return result.toDataStreamResponse();} Now, when you ask "What's the weather in New York in celsius?", you should see a more complete interaction: 1. The model will call the weather tool for New York. 2. You'll see the tool result displayed. 3. It will then call the temperature conversion tool to convert the temperature from Fahrenheit to Celsius. 4. The model will then use that information to provide a natural language response about the weather in New York. This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. This simple example demonstrates how tools can expand your model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. [How does `@ai-sdk/svelte` differ from `@ai-sdk/react`?](#how-does-ai-sdksvelte-differ-from-ai-sdkreact) --------------------------------------------------------------------------------------------------------- The surface-level difference is that Svelte uses classes to manage state, whereas React uses hooks, so `useChat` in React is `Chat` in Svelte. Other than that, there are a few things to keep in mind: ### [1\. Arguments to classes aren't reactive by default](#1-arguments-to-classes-arent-reactive-by-default) Unlike in React, where hooks are rerun any time their containing component is invalidated, code in the `script` block of a Svelte component is only run once when the component is created. This means that, if you want arguments to your class to be reactive, you need to make sure you pass a _reference_ into the class, rather than a value: Keep in mind that this normally doesn't matter; most parameters you'll pass into the Chat class are static (for example, you typically wouldn't expect your `onError` handler to change). ### [2\. You can't destructure class properties](#2-you-cant-destructure-class-properties) In vanilla JavaScript, destructuring class properties copies them by value and "disconnects" them from their class instance: const classInstance = new Whatever();classInstance.foo = 'bar';const { foo } = classInstance;classInstance.foo = 'baz'; console.log(foo); // 'bar' The same is true of classes in Svelte: ### [3\. Instance synchronization requires context](#3-instance-synchronization-requires-context) In React, hook instances with the same `id` are synchronized -- so two instances of `useChat` will have the same `messages`, `status`, etc. if they have the same `id`. For most use cases, you probably don't need this behavior -- but if you do, you can create a context in your root layout file using `createAIContext`: {@render children()} [Where to Next?](#where-to-next) --------------------------------- You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: * To learn more about the AI SDK, read through the [documentation](/docs) . * If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. * To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai) . * To learn more about Svelte, check out the [official documentation](https://svelte.dev/docs/svelte) . On this page [Svelte Quickstart](#svelte-quickstart) [Prerequisites](#prerequisites) [Set Up Your Application](#set-up-your-application) [Install Dependencies](#install-dependencies) [Configure OpenAI API Key](#configure-openai-api-key) [Create an API route](#create-an-api-route) [Wire up the UI](#wire-up-the-ui) [Running Your Application](#running-your-application) [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) [Update Your API Route](#update-your-api-route) [Update the UI](#update-the-ui) [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) [Update Your UI](#update-your-ui) [Update Your API Route](#update-your-api-route-1) [How does @ai-sdk/svelte differ from @ai-sdk/react?](#how-does-ai-sdksvelte-differ-from-ai-sdkreact) [1\. Arguments to classes aren't reactive by default](#1-arguments-to-classes-arent-reactive-by-default) [2\. You can't destructure class properties](#2-you-cant-destructure-class-properties) [3\. Instance synchronization requires context](#3-instance-synchronization-requires-context) [Where to Next?](#where-to-next) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Guides [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Guides](#guides) ================== These use-case specific guides are intended to help you build real applications with the AI SDK. [RAG Chatbot\ \ Learn how to build a retrieval-augmented generation chatbot with the AI SDK.](/docs/guides/rag-chatbot) [Multimodal Chatbot\ \ Learn how to build a multimodal chatbot with the AI SDK.](/docs/guides/multi-modal-chatbot) [Get started with Llama 3.1\ \ Get started with Llama 3.1 using the AI SDK.](/docs/guides/llama-3_1) [Get started with OpenAI o1\ \ Get started with OpenAI o1 using the AI SDK.](/docs/guides/o1) On this page [Guides](#guides) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Node.js [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Node.js Quickstart](#nodejs-quickstart) ========================================= In this quickstart tutorial, you'll build a simple AI chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming) , you can optionally read these documents first. [Prerequisites](#prerequisites) -------------------------------- To follow this quickstart, you'll need: * Node.js 18+ and pnpm installed on your local development machine. * An OpenAI API key. If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. [Setup Your Application](#setup-your-application) -------------------------------------------------- Start by creating a new directory using the `mkdir` command. Change into your new directory and then run the `pnpm init` command. This will create a `package.json` in your new directory. mkdir my-ai-appcd my-ai-apppnpm init ### [Install Dependencies](#install-dependencies) Install `ai` and `@ai-sdk/openai`, the AI SDK's OpenAI provider, along with other necessary dependencies. The AI SDK is designed to be a unified interface to interact with any large language model. This means that you can change model and providers with just one line of code! Learn more about [available providers](/providers) and [building custom providers](/providers/community-providers/custom-providers) in the [providers](/providers) section. pnpm add ai @ai-sdk/openai zod dotenvpnpm add -D @types/node tsx typescript Make sure you are using `ai` version 3.1 or higher. The `ai` and `@ai-sdk/openai` packages contain the AI SDK and the [AI SDK OpenAI provider](/providers/ai-sdk-providers/openai) , respectively. You will use `zod` to define type-safe schemas that you will pass to the large language model (LLM). You will use `dotenv` to access environment variables (your OpenAI key) within your application. There are also three development dependencies, installed with the `-D` flag, that are necessary to run your Typescript code. ### [Configure OpenAI API key](#configure-openai-api-key) Create a `.env` file in your project's root directory and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. touch .env Edit the `.env` file: .env OPENAI_API_KEY=xxxxxxxxx Replace `xxxxxxxxx` with your actual OpenAI API key. The AI SDK's OpenAI Provider will default to using the `OPENAI_API_KEY` environment variable. [Create Your Application](#create-your-application) ---------------------------------------------------- Create an `index.ts` file in the root of your project and add the following code: index.ts import { openai } from '@ai-sdk/openai';import { CoreMessage, streamText } from 'ai';import dotenv from 'dotenv';import * as readline from 'node:readline/promises'; dotenv.config(); const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,}); const messages: CoreMessage[] = []; async function main() { while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: openai('gpt-4o'), messages, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); messages.push({ role: 'assistant', content: fullResponse }); }} main().catch(console.error); Let's take a look at what is happening in this code: 1. Set up a readline interface to take input from the terminal, enabling interactive sessions directly from the command line. 2. Initialize an array called `messages` to store the history of your conversation. This history allows the model to maintain context in ongoing dialogues. 3. In the `main` function: * Prompt for and capture user input, storing it in `userInput`. * Add user input to the `messages` array as a user message. * Call [`streamText`](/docs/reference/ai-sdk-core/stream-text) , which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider and `messages`. * Iterate over the text stream returned by the `streamText` function (`result.textStream`) and print the contents of the stream to the terminal. * Add the assistant's response to the `messages` array. [Running Your Application](#running-your-application) ------------------------------------------------------ With that, you have built everything you need for your chatbot! To start your application, use the command: pnpm tsx index.ts You should see a prompt in your terminal. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Node.js. [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) -------------------------------------------------------------------- While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered for the next response. For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. Let's enhance your chatbot by adding a simple weather tool. ### [Update Your Application](#update-your-application) Modify your `index.ts` file to include the new weather tool: index.ts import { openai } from '@ai-sdk/openai';import { CoreMessage, streamText, tool } from 'ai';import dotenv from 'dotenv';import { z } from 'zod';import * as readline from 'node:readline/promises'; dotenv.config(); const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,}); const messages: CoreMessage[] = []; async function main() { while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (in Celsius)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: Math.round((Math.random() * 30 + 5) * 10) / 10, // Random temp between 5°C and 35°C }), }), }, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); messages.push({ role: 'assistant', content: fullResponse }); }} main().catch(console.error); In this updated code: 1. You import the `tool` function from the `ai` package. 2. You define a `tools` object with a `weather` tool. This tool: * Has a description that helps the model understand when to use it. * Defines parameters using a Zod schema, specifying that it requires a `location` string to execute this tool. * Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function, so you could fetch real data from an external API. Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary parameters. The `execute` function will then be automatically run, and the results will be used by the model to generate its response. Try asking something like "What's the weather in New York?" and see how the model uses the new tool. Notice the blank "assistant" response? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result in the `toolCall` and `toolResult` keys of the result object. import { openai } from '@ai-sdk/openai';import { CoreMessage, streamText, tool } from 'ai';import dotenv from 'dotenv';import { z } from 'zod';import * as readline from 'node:readline/promises'; dotenv.config(); const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,}); const messages: CoreMessage[] = []; async function main() { while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (in Celsius)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: Math.round((Math.random() * 30 + 5) * 10) / 10, // Random temp between 5°C and 35°C }), }), }, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); console.log(await result.toolCalls); console.log(await result.toolResults); messages.push({ role: 'assistant', content: fullResponse }); }} main().catch(console.error); Now, when you ask about the weather, you'll see the tool call and its result displayed in your chat interface. [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) ------------------------------------------------------------------ You may have noticed that while the tool results are visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. To solve this, you can enable multi-step tool calls using `maxSteps`. This feature will automatically send tool results back to the model to trigger an additional generation. In this case, you want the model to answer your question using the results from the weather tool. ### [Update Your Application](#update-your-application-1) Modify your `index.ts` file to include the `maxSteps` option: index.ts import { openai } from '@ai-sdk/openai';import { CoreMessage, streamText, tool } from 'ai';import dotenv from 'dotenv';import { z } from 'zod';import * as readline from 'node:readline/promises'; dotenv.config(); const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,}); const messages: CoreMessage[] = []; async function main() { while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (in Celsius)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: Math.round((Math.random() * 30 + 5) * 10) / 10, // Random temp between 5°C and 35°C }), }), }, maxSteps: 5, onStepFinish: step => { console.log(JSON.stringify(step, null, 2)); }, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); messages.push({ role: 'assistant', content: fullResponse }); }} main().catch(console.error); In this updated code: 1. You set `maxSteps` to 5, allowing the model to use up to 5 "steps" for any given generation. 2. You add an `onStepFinish` callback to log each step of the interaction, helping you understand the model's tool usage. This means we can also delete the `toolCall` and `toolResult` `console.log` statements from the previous example. Now, when you ask about the weather in a location, you should see the model using the weather tool results to answer your question. By setting `maxSteps` to 5, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Celsius to Fahrenheit. ### [Adding a second tool](#adding-a-second-tool) Update your `index.ts` file to add a new tool to convert the temperature from Celsius to Fahrenheit: index.ts import { openai } from '@ai-sdk/openai';import { CoreMessage, streamText, tool } from 'ai';import dotenv from 'dotenv';import { z } from 'zod';import * as readline from 'node:readline/promises'; dotenv.config(); const terminal = readline.createInterface({ input: process.stdin, output: process.stdout,}); const messages: CoreMessage[] = []; async function main() { while (true) { const userInput = await terminal.question('You: '); messages.push({ role: 'user', content: userInput }); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (in Celsius)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => ({ location, temperature: Math.round((Math.random() * 30 + 5) * 10) / 10, // Random temp between 5°C and 35°C }), }), convertCelsiusToFahrenheit: tool({ description: 'Convert a temperature from Celsius to Fahrenheit', parameters: z.object({ celsius: z .number() .describe('The temperature in Celsius to convert'), }), execute: async ({ celsius }) => { const fahrenheit = (celsius * 9) / 5 + 32; return { fahrenheit: Math.round(fahrenheit * 100) / 100 }; }, }), }, maxSteps: 5, onStepFinish: step => { console.log(JSON.stringify(step, null, 2)); }, }); let fullResponse = ''; process.stdout.write('\nAssistant: '); for await (const delta of result.textStream) { fullResponse += delta; process.stdout.write(delta); } process.stdout.write('\n\n'); messages.push({ role: 'assistant', content: fullResponse }); }} main().catch(console.error); Now, when you ask "What's the weather in New York in Celsius?", you should see a more complete interaction: 1. The model will call the weather tool for New York. 2. You'll see the tool result logged. 3. It will then call the temperature conversion tool to convert the temperature from Celsius to Fahrenheit. 4. The model will then use that information to provide a natural language response about the weather in New York. This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. This example shows how tools can expand the model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. [Where to Next?](#where-to-next) --------------------------------- You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: * To learn more about the AI SDK, read through the [documentation](/docs) . * If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. * To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai) . On this page [Node.js Quickstart](#nodejs-quickstart) [Prerequisites](#prerequisites) [Setup Your Application](#setup-your-application) [Install Dependencies](#install-dependencies) [Configure OpenAI API key](#configure-openai-api-key) [Create Your Application](#create-your-application) [Running Your Application](#running-your-application) [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) [Update Your Application](#update-your-application) [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) [Update Your Application](#update-your-application-1) [Adding a second tool](#adding-a-second-tool) [Where to Next?](#where-to-next) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) --- # Getting Started: Vue.js (Nuxt) [](https://vercel.com/) [AI SDK](/) Menu [AI SDK by Vercel](/docs/introduction) [Foundations](/docs/foundations) [Overview](/docs/foundations/overview) [Providers and Models](/docs/foundations/providers-and-models) [Prompts](/docs/foundations/prompts) [Tools](/docs/foundations/tools) [Streaming](/docs/foundations/streaming) [Agents](/docs/foundations/agents) [Getting Started](/docs/getting-started) [Navigating the Library](/docs/getting-started/navigating-the-library) [Next.js App Router](/docs/getting-started/nextjs-app-router) [Next.js Pages Router](/docs/getting-started/nextjs-pages-router) [Svelte](/docs/getting-started/svelte) [Vue.js (Nuxt)](/docs/getting-started/nuxt) [Node.js](/docs/getting-started/nodejs) [Expo](/docs/getting-started/expo) [Guides](/docs/guides) [RAG Chatbot](/docs/guides/rag-chatbot) [Multi-Modal Chatbot](/docs/guides/multi-modal-chatbot) [Slackbot Guide](/docs/guides/slackbot) [Natural Language Postgres](/docs/guides/natural-language-postgres) [Get started with Computer Use](/docs/guides/computer-use) [OpenAI Responses API](/docs/guides/openai-responses) [Get started with Claude 3.7 Sonnet](/docs/guides/sonnet-3-7) [Get started with Llama 3.1](/docs/guides/llama-3_1) [Get started with OpenAI GPT-4.5](/docs/guides/gpt-4-5) [Get started with OpenAI o1](/docs/guides/o1) [Get started with OpenAI o3-mini](/docs/guides/o3) [Get started with DeepSeek R1](/docs/guides/r1) [AI SDK Core](/docs/ai-sdk-core) [Overview](/docs/ai-sdk-core/overview) [Generating Text](/docs/ai-sdk-core/generating-text) [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data) [Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling) [Prompt Engineering](/docs/ai-sdk-core/prompt-engineering) [Settings](/docs/ai-sdk-core/settings) [Embeddings](/docs/ai-sdk-core/embeddings) [Image Generation](/docs/ai-sdk-core/image-generation) [Transcription](/docs/ai-sdk-core/transcription) [Speech](/docs/ai-sdk-core/speech) [Language Model Middleware](/docs/ai-sdk-core/middleware) [Provider & Model Management](/docs/ai-sdk-core/provider-management) [Error Handling](/docs/ai-sdk-core/error-handling) [Testing](/docs/ai-sdk-core/testing) [Telemetry](/docs/ai-sdk-core/telemetry) [AI SDK UI](/docs/ai-sdk-ui) [Overview](/docs/ai-sdk-ui/overview) [Chatbot](/docs/ai-sdk-ui/chatbot) [Chatbot Message Persistence](/docs/ai-sdk-ui/chatbot-message-persistence) [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage) [Generative User Interfaces](/docs/ai-sdk-ui/generative-user-interfaces) [Completion](/docs/ai-sdk-ui/completion) [Object Generation](/docs/ai-sdk-ui/object-generation) [OpenAI Assistants](/docs/ai-sdk-ui/openai-assistants) [Streaming Custom Data](/docs/ai-sdk-ui/streaming-data) [Error Handling](/docs/ai-sdk-ui/error-handling) [Smooth streaming japanese text](/docs/ai-sdk-ui/smooth-stream-japanese) [Smooth streaming chinese text](/docs/ai-sdk-ui/smooth-stream-chinese) [Stream Protocols](/docs/ai-sdk-ui/stream-protocol) [AI SDK RSC](/docs/ai-sdk-rsc) [Advanced](/docs/advanced) [Reference](/docs/reference) [AI SDK Core](/docs/reference/ai-sdk-core) [AI SDK UI](/docs/reference/ai-sdk-ui) [AI SDK RSC](/docs/reference/ai-sdk-rsc) [Stream Helpers](/docs/reference/stream-helpers) [AI SDK Errors](/docs/reference/ai-sdk-errors) [Migration Guides](/docs/migration-guides) [Troubleshooting](/docs/troubleshooting) [Vue.js (Nuxt) Quickstart](#vuejs-nuxt-quickstart) =================================================== The AI SDK is a powerful Typescript library designed to help developers build AI-powered applications. In this quickstart tutorial, you'll build a simple AI-chatbot with a streaming user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the SDK in your own projects. If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/advanced/why-streaming) , you can optionally read these documents first. [Prerequisites](#prerequisites) -------------------------------- To follow this quickstart, you'll need: * Node.js 18+ and pnpm installed on your local development machine. * An OpenAI API key. If you haven't obtained your OpenAI API key, you can do so by [signing up](https://platform.openai.com/signup/) on the OpenAI website. [Setup Your Application](#setup-your-application) -------------------------------------------------- Start by creating a new Nuxt application. This command will create a new directory named `my-ai-app` and set up a basic Nuxt application inside it. pnpm create nuxt my-ai-app Navigate to the newly created directory: cd my-ai-app ### [Install dependencies](#install-dependencies) Install `ai` and `@ai-sdk/openai`, the AI SDK's OpenAI provider. The AI SDK is designed to be a unified interface to interact with any large language model. This means that you can change model and providers with just one line of code! Learn more about [available providers](/providers) and [building custom providers](/providers/community-providers/custom-providers) in the [providers](/providers) section. pnpm npm yarn pnpm add ai @ai-sdk/openai @ai-sdk/vue zod Make sure you are using `ai` version 3.1 or higher. ### [Configure OpenAI API key](#configure-openai-api-key) Create a `.env` file in your project root and add your OpenAI API Key. This key is used to authenticate your application with the OpenAI service. touch .env Edit the `.env` file: .env OPENAI_API_KEY=xxxxxxxxx Replace `xxxxxxxxx` with your actual OpenAI API key and configure the environment variable in `nuxt.config.ts`: nuxt.config.ts export default defineNuxtConfig({ // rest of your nuxt config runtimeConfig: { openaiApiKey: process.env.OPENAI_API_KEY, },}); The AI SDK's OpenAI Provider will default to using the `OPENAI_API_KEY` environment variable. [Create an API route](#create-an-api-route) -------------------------------------------- Create an API route, `server/api/chat.ts` and add the following code: server/api/chat.ts import { streamText } from 'ai';import { createOpenAI } from '@ai-sdk/openai'; export default defineLazyEventHandler(async () => { const apiKey = useRuntimeConfig().openaiApiKey; if (!apiKey) throw new Error('Missing OpenAI API key'); const openai = createOpenAI({ apiKey: apiKey, }); return defineEventHandler(async (event: any) => { const { messages } = await readBody(event); const result = streamText({ model: openai('gpt-4o'), messages, }); return result.toDataStreamResponse(); });}); Let's take a look at what is happening in this code: 1. Create an OpenAI provider instance with the `createOpenAI` function from the `@ai-sdk/openai` package. 2. Define an Event Handler and extract `messages` from the body of the request. The `messages` variable contains a history of the conversation with you and the chatbot and will provide the chatbot with the necessary context to make the next generation. 3. Call [`streamText`](/docs/reference/ai-sdk-core/stream-text) , which is imported from the `ai` package. This function accepts a configuration object that contains a `model` provider (defined in step 1) and `messages` (defined in step 2). You can pass additional [settings](/docs/ai-sdk-core/settings) to further customise the model's behaviour. 4. The `streamText` function returns a [`StreamTextResult`](/docs/reference/ai-sdk-core/stream-text#result) . This result object contains the [`toDataStreamResponse`](/docs/reference/ai-sdk-core/stream-text#to-data-stream-response) function which converts the result to a streamed response object. 5. Return the result to the client to stream the response. [Wire up the UI](#wire-up-the-ui) ---------------------------------- Now that you have an API route that can query an LLM, it's time to setup your frontend. The AI SDK's [UI](/docs/ai-sdk-ui/overview) package abstract the complexity of a chat interface into one hook, [`useChat`](/docs/reference/ai-sdk-ui/use-chat) . Update your root page (`pages/index.vue`) with the following code to show a list of chat messages and provide a user message input: pages/index.vue If your project has `app.vue` instead of `pages/index.vue`, delete the `app.vue` file and create a new `pages/index.vue` file with the code above. This page utilizes the `useChat` hook, which will, by default, use the API route you created earlier (`/api/chat`). The hook provides functions and state for handling user input and form submission. The `useChat` hook provides multiple utility functions and state variables: * `messages` - the current chat messages (an array of objects with `id`, `role`, and `parts` properties). * `input` - the current value of the user's input field. * `handleSubmit` - function to handle form submission. The LLM's response is accessed through the message `parts` array. Each message contains an ordered array of `parts` that represents everything the model generated in its response. These parts can include plain text, reasoning tokens, and more that you will see later. The `parts` array preserves the sequence of the model's outputs, allowing you to display or process each component in the order it was generated. [Running Your Application](#running-your-application) ------------------------------------------------------ With that, you have built everything you need for your chatbot! To start your application, use the command: pnpm run dev Head to your browser and open [http://localhost:3000](http://localhost:3000) . You should see an input field. Test it out by entering a message and see the AI chatbot respond in real-time! The AI SDK makes it fast and easy to build AI chat interfaces with Nuxt. [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) -------------------------------------------------------------------- While large language models (LLMs) have incredible generation capabilities, they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). This is where [tools](/docs/ai-sdk-core/tools-and-tool-calling) come in. Tools are actions that an LLM can invoke. The results of these actions can be reported back to the LLM to be considered in the next response. For example, if a user asks about the current weather, without tools, the model would only be able to provide general information based on its training data. But with a weather tool, it can fetch and provide up-to-date, location-specific weather information. Let's enhance your chatbot by adding a simple weather tool. ### [Update Your API Route](#update-your-api-route) Modify your `server/api/chat.ts` file to include the new weather tool: server/api/chat.ts import { streamText, tool } from 'ai';import { createOpenAI } from '@ai-sdk/openai';import { z } from 'zod'; export default defineLazyEventHandler(async () => { const apiKey = useRuntimeConfig().openaiApiKey; if (!apiKey) throw new Error('Missing OpenAI API key'); const openai = createOpenAI({ apiKey: apiKey, }); return defineEventHandler(async (event: any) => { const { messages } = await readBody(event); const result = streamText({ model: openai('gpt-4o'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), }, }); return result.toDataStreamResponse(); });}); In this updated code: 1. You import the `tool` function from the `ai` package and `z` from `zod` for schema validation. 2. You define a `tools` object with a `weather` tool. This tool: * Has a description that helps the model understand when to use it. * Defines parameters using a Zod schema, specifying that it requires a `location` string to execute this tool. The model will attempt to extract this parameter from the context of the conversation. If it can't, it will ask the user for the missing information. * Defines an `execute` function that simulates getting weather data (in this case, it returns a random temperature). This is an asynchronous function running on the server so you can fetch real data from an external API. Now your chatbot can "fetch" weather information for any location the user asks about. When the model determines it needs to use the weather tool, it will generate a tool call with the necessary parameters. The `execute` function will then be automatically run, and you can access the results via `tool-invocations` part that is available on the `message.parts` array. Try asking something like "What's the weather in New York?" and see how the model uses the new tool. Notice the blank response in the UI? This is because instead of generating a text response, the model generated a tool call. You can access the tool call and subsequent tool result via the `tool-invocation` part of the `message.parts` array. ### [Update the UI](#update-the-ui) To display the tool invocations in your UI, update your `pages/index.vue` file: pages/index.vue With this change, you're updating the UI to handle different message parts. For text parts, you display the text content as before. For tool invocations, you display a JSON representation of the tool call and its result. Now, when you ask about the weather, you'll see the tool invocation and its result displayed in your chat interface. [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) ------------------------------------------------------------------ You may have noticed that while the tool results are visible in the chat interface, the model isn't using this information to answer your original query. This is because once the model generates a tool call, it has technically completed its generation. To solve this, you can enable multi-step tool calls using the `maxSteps` option in your `useChat` hook. This feature will automatically send tool results back to the model to trigger an additional generation. In this case, you want the model to answer your question using the results from the weather tool. ### [Update Your Client-Side Code](#update-your-client-side-code) Modify your `pages/index.vue` file to include the `maxSteps` option: pages/index.vue Head back to the browser and ask about the weather in a location. You should now see the model using the weather tool results to answer your question. By setting `maxSteps` to 5, you're allowing the model to use up to 5 "steps" for any given generation. This enables more complex interactions and allows the model to gather and process information over several steps if needed. You can see this in action by adding another tool to convert the temperature from Fahrenheit to Celsius. ### [Update Your API Route](#update-your-api-route-1) Update your `server/api/chat.ts` file to add a new tool to convert the temperature from Fahrenheit to Celsius: server/api/chat.ts import { streamText, tool } from 'ai';import { createOpenAI } from '@ai-sdk/openai';import { z } from 'zod'; export default defineLazyEventHandler(async () => { const apiKey = useRuntimeConfig().openaiApiKey; if (!apiKey) throw new Error('Missing OpenAI API key'); const openai = createOpenAI({ apiKey: apiKey, }); return defineEventHandler(async (event: any) => { const { messages } = await readBody(event); const result = streamText({ model: openai('gpt-4o-preview'), messages, tools: { weather: tool({ description: 'Get the weather in a location (fahrenheit)', parameters: z.object({ location: z .string() .describe('The location to get the weather for'), }), execute: async ({ location }) => { const temperature = Math.round(Math.random() * (90 - 32) + 32); return { location, temperature, }; }, }), convertFahrenheitToCelsius: tool({ description: 'Convert a temperature in fahrenheit to celsius', parameters: z.object({ temperature: z .number() .describe('The temperature in fahrenheit to convert'), }), execute: async ({ temperature }) => { const celsius = Math.round((temperature - 32) * (5 / 9)); return { celsius, }; }, }), }, }); return result.toDataStreamResponse(); });}); Now, when you ask "What's the weather in New York in celsius?", you should see a more complete interaction: 1. The model will call the weather tool for New York. 2. You'll see the tool result displayed. 3. It will then call the temperature conversion tool to convert the temperature from Fahrenheit to Celsius. 4. The model will then use that information to provide a natural language response about the weather in New York. This multi-step approach allows the model to gather information and use it to provide more accurate and contextual responses, making your chatbot considerably more useful. This simple example demonstrates how tools can expand your model's capabilities. You can create more complex tools to integrate with real APIs, databases, or any other external systems, allowing the model to access and process real-world data in real-time. Tools bridge the gap between the model's knowledge cutoff and current information. [Where to Next?](#where-to-next) --------------------------------- You've built an AI chatbot using the AI SDK! From here, you have several paths to explore: * To learn more about the AI SDK, read through the [documentation](/docs) . * If you're interested in diving deeper with guides, check out the [RAG (retrieval-augmented generation)](/docs/guides/rag-chatbot) and [multi-modal chatbot](/docs/guides/multi-modal-chatbot) guides. * To jumpstart your first AI project, explore available [templates](https://vercel.com/templates?type=ai) . On this page [Vue.js (Nuxt) Quickstart](#vuejs-nuxt-quickstart) [Prerequisites](#prerequisites) [Setup Your Application](#setup-your-application) [Install dependencies](#install-dependencies) [Configure OpenAI API key](#configure-openai-api-key) [Create an API route](#create-an-api-route) [Wire up the UI](#wire-up-the-ui) [Running Your Application](#running-your-application) [Enhance Your Chatbot with Tools](#enhance-your-chatbot-with-tools) [Update Your API Route](#update-your-api-route) [Update the UI](#update-the-ui) [Enabling Multi-Step Tool Calls](#enabling-multi-step-tool-calls) [Update Your Client-Side Code](#update-your-client-side-code) [Update Your API Route](#update-your-api-route-1) [Where to Next?](#where-to-next) Elevate your AI applications with Vercel. Trusted by OpenAI, Replicate, Suno, Pinecone, and more. Vercel provides tools and infrastructure to deploy AI apps and features at scale. [Talk to an expert](https://vercel.com/contact/sales?utm_source=ai_sdk&utm_medium=web&utm_campaign=contact_sales_cta&utm_content=talk_to_an_expert_sdk_docs) ---