The Vercel AI SDK · Chapter 1 of 21
Meet Mali, your first AI SDK call
By the end of this chapter you can call a model from TypeScript with the Vercel AI SDK: make a provider, ask a question with generateText, give the model its instructions, keep a conversation it can follow, and say what every call costs. You will make your first call, give Mali who it is, hold a two-turn conversation, and measure a three-turn one in tokens and rupees. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: The SDK on the server
- 4 tasks
- TypeScript
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
Why you need this
HariBhari, in Bengaluru, delivers plants and pots across the city: a money plant for a desk, an areca palm for a cafe, twenty peace lilies for an office's Diwali gifts. Its customers ask the same things all day, on the website and on WhatsApp. Is the snake plant in stock? Do you deliver to Whitefield? Where is my order? My pot arrived cracked, what now? Deepa, who leads customer care, has three people answering six hundred messages a day, and Diwali week has just begun.
Ananya, HariBhari's founder, wants a helper on the website that answers in seconds: Mali, the plant helper. A chat box that streams its answers, looks up real stock and real orders, shows plants as cards a customer can tap, reads a photo of a sick plant, and never makes up a discount. That is a real AI feature, and you will build all of it in this lab.
You could build it with fetch and a provider's REST API. Then you would write the request format, parse the replies, glue streamed pieces together, run the tool calls, validate JSON, and do it all again when HariBhari moves to another provider. Farhan, HariBhari's staff engineer and your mentor here, has done that once. This time he picked the Vercel AI SDK, the most used AI library in the JavaScript world: one API for every model, on the server and in React.
The lesson
The AI SDK in three parts
The AI SDK is a few npm packages that work together:
| Package | What it gives you | In this lab |
|---|---|---|
ai | the core: generateText, streamText, tools, structured output, middleware, and the server side of a chat | every chapter |
@ai-sdk/openai-compatible, @ai-sdk/openai, ... | providers: one per model company, each turning the SDK's calls into that company's API | chapter 1, and chapter 17 for switching |
@ai-sdk/react | the UI hooks: useChat for a streaming chat in React | chapters 8 to 14 |
The idea that holds it together: your code talks to the SDK, never to a company's API. A provider does the translation. Switch providers and your code stays the same. This lab uses version 7 of ai, the current one; if you read older examples online, some names differ (chapter 1's instructions was called system, and chapter 2's stream was fullStream).
The lab model
Every call in this lab is answered by lab-chat, the lab's own model, on http://127.0.0.1:11500/v1, with the same API as OpenAI's. It is a predictable stand-in, not a neural network: it reads what it is sent and answers the same way every time, which is what lets a Check measure your code. It behaves the way real models do in the ways this lab teaches: it forgets between calls, it guesses when it has no tool to look something up, it picks tools from their descriptions. Where a real model would differ, the chapter says so.
(The terminal has OPENAI_BASE_URL and OPENAI_API_KEY set for the lab model. On a machine with internet, point them at a real provider with your own key, and the same code talks to a real model. lab models lists the lab's models and their prices.)
A provider
A provider is a function that turns a model's name into a model object the SDK can call. The lab model speaks OpenAI's API, so the OpenAI-compatible provider fits:
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
const lab = createOpenAICompatible({
name: 'lab',
baseURL: process.env.OPENAI_BASE_URL!,
apiKey: process.env.OPENAI_API_KEY,
});
const model = lab('lab-chat');
Making the provider sends nothing. It remembers the address and the key, so that lab('lab-chat') can give a model object that knows where to go. The same package talks to LM Studio, Ollama and many hosted models; the @ai-sdk/openai package talks to OpenAI itself, @ai-sdk/anthropic to Claude, @ai-sdk/google to Gemini. Each gives a model object of the same shape.
generateText
generateText asks a model once and waits for the whole answer:
import { generateText } from 'ai';
const result = await generateText({
model: lab('lab-chat'),
prompt: 'Why are the leaves of my plant turning yellow?',
});
console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
Yellow lower leaves usually mean too much water. Let the top of the soil dry out before you water again, and check that the pot drains.
stop
{
inputTokens: 16,
inputTokenDetails: { noCacheTokens: 16, cacheReadTokens: 0, cacheWriteTokens: undefined },
outputTokens: 29,
outputTokenDetails: { textTokens: 29, reasoningTokens: 0 },
totalTokens: 45,
raw: { prompt_tokens: 16, completion_tokens: 29, total_tokens: 45, ... }
}
(The usage is trimmed: raw is the provider's own numbers.) Three things came back:
text: the answer.finishReason: why the model stopped.stopmeans it finished its answer.lengthwould mean it ran out of room,tool-callsthat it wants a tool run (chapter 3),errorthat something failed.usage: the tokens. A token is a piece of a word, about four characters of English; models read and write in tokens, and providers charge by them.inputTokensis what you sent,outputTokenswhat it wrote.
The result has more (every step, the request and the response), and later chapters use it.
Instructions: who Mali is
Ask the same model a HariBhari question, and it has no idea what HariBhari is:
await generateText({ model: lab('lab-chat'), prompt: 'My pot arrived cracked. What do I do?' });
I'm not sure which shop you mean, so I can't tell you about its deliveries, prices or orders. Which store are you asking about?
A model knows only what it was trained on and what you send it. HariBhari's rules are in neither. Instructions are the text that tells the model who it is, what it knows and how to behave, sent before the customer's words on every call. HariBhari's are in /workspace/shared/mali.ts as MALI_INSTRUCTIONS: Mali's job, five facts (delivery hours, fees, damaged plants, payment, coupons) and two rules. With them:
await generateText({
model: lab('lab-chat'),
instructions: MALI_INSTRUCTIONS,
prompt: 'My pot arrived cracked. What do I do?',
});
If a plant or pot arrives damaged, send a photo within 48 hours and we replace it for free.
Step through what happened on that call:
On the wire, the SDK sent OpenAI's format: the instructions became a system message and the prompt a user message (lab requests shows every request the lab model received; this one is trimmed):
{
"model": "lab-chat",
"messages": [
{ "role": "system", "content": "You are Mali, the plant helper on HariBhari's website. ..." },
{ "role": "user", "content": "My pot arrived cracked. What do I do?" }
]
}
That call used 248 input tokens, against 16 for the yellow-leaves question: the instructions travel with every call. Keep them on their own, in instructions, and never glue them onto the customer's text: the model treats a system message as the app's voice and a user message as the customer's, and a customer's words should never pass for the app's.
The model remembers nothing
A customer asks two things, one after the other:
await generateText({ model: lab('lab-chat'), instructions: MALI_INSTRUCTIONS, prompt: 'Can I pay by UPI?' });
await generateText({ model: lab('lab-chat'), instructions: MALI_INSTRUCTIONS, prompt: 'And by cash?' });
You can pay by UPI, card, or cash on delivery for orders up to ₹2,000.
Could you tell me a little more? What would you like to know about cash?
The second call knows nothing of the first. A model has no memory between calls: each request is all it sees. A conversation is something your code keeps and sends again each time, as messages, each with a role:
| Role | Who says it | Where it comes from |
|---|---|---|
system | the app | instructions |
user | the customer | what they typed |
assistant | the model | its earlier replies |
tool | your code | a tool's result (chapter 3) |
messages replaces prompt when there is more than one:
const history: ModelMessage[] = [{ role: 'user', content: 'Can I pay by UPI?' }];
let result = await generateText({ model: lab('lab-chat'), instructions: MALI_INSTRUCTIONS, messages: history });
history.push(...result.responseMessages);
history.push({ role: 'user', content: 'And by cash?' });
result = await generateText({ model: lab('lab-chat'), instructions: MALI_INSTRUCTIONS, messages: history });
console.log(result.text);
You can pay by UPI, card, or cash on delivery for orders up to ₹2,000.
result.responseMessages is the model's reply as messages, ready to add to the history:
[{"role":"assistant","content":[{"type":"text","text":"You can pay by UPI, card, or cash on delivery for orders up to ₹2,000."}]}]
Its content is a list of parts (here one text part), because a reply can hold text, tool calls and files together. You will meet parts again in the chat UI.
Tokens and rupees
Vikram, who looks after HariBhari's costs, asks the question every AI feature gets: what does a chat cost? Providers price input and output tokens separately, per million. lab models shows the lab's prices: lab-chat is ₹200 a million input tokens and ₹800 a million output tokens (made up, in proportion to real ones). The cracked-pot answer cost 248 x ₹200 + 22 x ₹800, over a million: ₹0.0672.
Small. But the follow-up with its history sent 277 input tokens for a three-word question, because the instructions, the first question and the first answer went again. Every turn sends the whole conversation so far, so a long chat costs more per turn the longer it gets. The interview task measures it.
Your turn
Make your first call in task 1. Give Mali its instructions in task 2. Keep a conversation the model can follow in task 3. In the interview question, measure what three turns cost, and explain to Vikram why the shortest message costs the most.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
first-call.ts: your first AI SDK call
Make a provider for the lab model with createOpenAICompatible (from @ai-sdk/openai-compatible): name 'lab', baseURL process.env.OPENAI_BASE_URL, apiKey process.env.OPENAI_API_KEY. Call generateText (from 'ai') with the model lab('lab-chat') and the prompt, exactly: Which plants are easy to look after?
Print the answer (result.text), then finish: and result.finishReason, then the tokens from result.usage, as:
tokens: IN in, OUT out
- Task 2
mali.ts: who Mali is
Export an async function askMali(question) from mali.ts. It calls generateText with the model lab('lab-chat') and the instructions MALI_INSTRUCTIONS (both from ../../shared/mali.ts), with the question as the prompt, and returns result.text.
Under if (import.meta.main), ask exactly What time do you deliver on Sundays? and print the answer. The Check calls askMali with a question of its own and reads the request: one system message that is MALI_INSTRUCTIONS exactly, and the question as the only user message.
- Task 3
history.ts: a conversation the model can follow
Export an async function chat(history, text) from history.ts. Add { role: 'user', content: text } to a new array of the history, call generateText with lab('lab-chat'), instructions MALI_INSTRUCTIONS and messages (that array), and return { answer: result.text, history: the messages you sent followed by result.responseMessages }.
The Check asks How do I pay?, then a follow-up with the history it got back, and wants the second request to carry the user message, the model's reply and the follow-up, in that order, and an answer that reads the follow-up with the first question.
- Task 4 · interview question
Interview: turn-costs.ts, what does a turn cost?
Have a three-turn conversation with Mali (lab('lab-chat'), MALI_INSTRUCTIONS), keeping the history: Hi, who are you? then What time do you deliver on weekdays? then And on Sundays?
After each turn print turn N: IN in, OUT out, from that turn's result.usage. Then print the totals and the cost, with lab-chat at ₹200 a million input tokens and ₹800 a million output tokens, rupees with 4 decimals:
total: IN in, OUT out, ₹COST
Vikram will ask: the third message is the shortest, so why does turn 3 cost the most input tokens?
What you will learn
- The AI SDK's three parts: the core (ai), providers, and the UI hooks.
- A provider for the lab's model, and what it does with your call.
- generateText and its result: the text, why the model stopped, the tokens.
- Instructions: how Mali learns who it is and what HariBhari's rules are.
- Messages: why the model forgets everything, and how a conversation is kept.
- Tokens and cost: what each call costs, and why a conversation grows dearer.
More in The SDK on the server
Build "Meet Mali, your first AI SDK call" yourself
HariBhari, a Bengaluru plant shop, wants Mali, a plant helper on its website. You build it end to end, from the first call to a chat that streams cards, asks before it adds to the cart and stays within budget. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.