AI Engineer Summit 2025
Vercel AI SDK Masterclass: From Fundamentals to Deep Research
Loading slides…
Read the talk
Vercel AI SDK Masterclass: From Fundamentals to Deep Research
A simple text call grows into a Node.js research workflow with typed tools, relevance feedback, recursive searches, accumulated evidence, and Markdown report generation.
From a talk by Nico Albanese
Before you start: You should be comfortable with TypeScript, async/await, Node.js scripts, and environment variables for API credentials.
Start with a text response
What does it take to turn a Hello, world prompt into a research program that searches the web and writes a report? Nico Albanese, an AI SDK maintainer at Vercel, starts with a single index.ts file. To follow along, clone the starter project, install its dependencies, and copy the environment variables. Run the entry point with pnpm run dev; the pnd command in the recording is Albanese’s alias for that script.
The first building block is generateText. An asynchronous main function selects GPT-4o mini, supplies a prompt, and logs the returned text:
typescript
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
async function main() {
const result = await generateText({
model: openai('gpt-4o-mini'),
prompt: 'Hello, world',
});
console.log(result.text);
}
main().catch(console.error);
The recorded run returns a greeting and an offer to help. This is the smallest working layer: application input goes to a model, and generated text comes back.
The input can also be a messages array, with a role and content on each message. A single user message can express the same request as prompt, while an array can carry conversation history. The workshop’s generateText, streamText, generateObject, and streamObject functions share these input forms; most subsequent examples use prompt. The code here follows the workshop-era API names, including parameters, maxSteps, experimental_output, and generateObject.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
When the answer needs current information
The SDK’s unified interface makes model choice a small code change. Cost, latency, and suitability for a task can all motivate switching providers. Albanese makes the need concrete by asking when the AI Engineer Summit took place in 2025. GPT-4o mini, without web access in this call, says it does not have the information. Albanese attributes this to its training cutoff and lack of search; the original model announcement dates its knowledge to October 2023, earlier than the approximate 2024 cutoff he mentions.
There are two ways forward: give the model a tool that retrieves web content, or select a model with search built in. The demonstration first takes the second route, importing the Perplexity provider and selecting Sonar Pro:
typescript
import { generateText } from 'ai';
import { perplexity } from '@ai-sdk/perplexity';
async function main() {
const result = await generateText({
model: perplexity('sonar-pro'),
prompt: 'When was the AI Engineer Summit in 2025?',
});
console.log(result.text);
console.log(result.sources);
}
main().catch(console.error);
The response identifies February 19–22, 2025, in New York City, matching the event page. Because this provider returns sources, the result also exposes them through sources. The application can retain the evidence alongside the answer instead of relying only on citation text embedded in prose.
Albanese then switches to Google’s Gemini 1.5 Flash, enables search grounding, and repeats the query. It returns the same event dates with sources. The shared generation interface stays recognizable across providers, while provider-specific configuration supplies capabilities such as grounding. The SDK’s provider documentation is where he points readers to explore the available integrations.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Give the model an action it can request
A tool call is a request for application code to run. The model receives a tool’s name, description, and required inputs alongside the conversation. If it decides to use that tool, it generates the name and arguments. The application performs the action; the model does not execute JavaScript itself.
The first example asks GPT-4o to add 10 and 5. The tools object names the available operation addNumbers:
typescript
import { generateText, tool } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
async function main() {
const result = await generateText({
model: openai('gpt-4o'),
prompt: "What's 10 plus 5?",
tools: {
addNumbers: tool({
description: 'Add two numbers together',
parameters: z.object({
numOne: z.number(),
numTwo: z.number(),
}),
execute: async ({ numOne, numTwo }) => numOne + numTwo,
}),
},
});
console.log(result.toolResults);
}
main().catch(console.error);
The description helps the model decide when to select the operation. The parameters schema defines the arguments it must supply. The execute function contains the actual behavior and can run arbitrary asynchronous JavaScript.
The tool helper is optional, but it connects the parameter schema to TypeScript’s inference for execute. Albanese briefly changes numTwo from a number schema to a string schema; the editor immediately reflects that change in the argument’s type. At runtime, the SDK parses the model’s call, invokes execute, and returns a toolResults entry containing the tool name, parsed arguments, and computed result.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Feed the result back for another generation
A successful tool execution does not necessarily produce a user-facing answer. When Albanese switches the addition example from logging toolResults to logging text, the terminal is empty: that generation produced a tool call. The program could inspect the last result, branch on toolName, and manually ask the model to continue. But separate branches become cumbersome as the tool set grows.
The workshop API handles this continuation with maxSteps. After a generation produces an executable tool call and its result, the SDK sends the result back with the preceding conversation and starts another generation. It continues until the model produces an answer without another tool result or reaches the step budget. The budget counts generation steps, not individual tool calls. This lets the model select its next action without application code manually routing every possible output.
Inspecting result.steps makes the addition example’s sequence visible: the initial generation requests addNumbers with 10 and 5; a subsequent generation uses the returned value to explain that the sum is 15. result.steps.length provides the count, and stringifying the steps makes nested details easier to inspect. Raw request and response bodies are also available for debugging what went to and came back from the provider. This bounded choice of tools and subsequent steps is what Albanese calls a multi-step agent.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Combine independent retrieval with dependent arithmetic
A second tool makes the model’s choices more interesting. getWeather takes a latitude, longitude, and city. Its execute function fetches weather using the coordinates, unwraps the response, and returns the data. The user supplies city names; the model infers coordinates from its training data. Albanese explicitly discourages relying on this particular coordinate-inference shortcut in production, even though inferred tool arguments can be useful in other settings.
The new prompt asks for the weather in San Francisco and New York, then asks the model to add the temperatures. Both getWeather and addNumbers are available, with maxSteps: 3. In the recorded run, San Francisco returns 12.3°C and New York returns 15.2°C; the reported sum is 27.5°C.
The recorded weather workflow uses three generation steps: two parallel weather calls, one addition call, and a final text response.
| Step | Model output | Dependency |
|---|---|---|
| 1 | Two getWeather calls | City names from the prompt |
| 2 | One addNumbers call | Temperatures returned by both calls |
| 3 | Final answer | Computed sum and weather results |
The two weather lookups are independent, so the model requests them together. Addition must wait for their results, and the final explanation follows the calculation. A second run with stringified step output exposes the same sequence directly.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Make the final output usable by code
A prose weather answer is readable, but another function may only need the sum. The workshop introduces two structured-output paths: generateText with experimental_output, which can accompany tool use, and the dedicated generateObject function. For the weather workflow, Albanese adds Output.object from ai and gives it a Zod schema containing sum: z.number().
The script now logs result.experimental_output instead of the text or full step history. The visible result is { sum: 27.5 }. Application code can access result.experimental_output.sum as a number; output that fails the schema produces an error instead of silently becoming an unexpected value. The tool workflow gathers and computes the information, while the output schema determines the shape the next part of the program receives.
Next, generateObject tackles a deliberately less settled task: generating ten definitions of an AI agent. Albanese recalls Simon’s survey as collecting roughly 250 definitions across six categories, then asks GPT-4o mini for its own list. A schema with a definitions array of strings gives the application a typed collection even though the meaning of an agent remains disputed.
Zod’s .describe() adds instructions at the value they concern. Instead of expanding the top-level prompt, Albanese asks each definition to contain as much jargon as possible and be incoherent:
typescript
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
async function main() {
const { object } = await generateObject({
model: openai('gpt-4o-mini'),
prompt: 'Please come up with ten definitions for AI agents.',
schema: z.object({
definitions: z.array(
z.string().describe(
'Use as much jargon as possible. It should be completely incoherent.',
),
),
}),
});
console.log(object.definitions);
}
main().catch(console.error);
The resulting definitions invoke algorithmic heuristics and dynamic environments. The useful mechanism is field-level guidance: the schema describes both the expected data structure and the intended content of individual values.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Turn research into a bounded workflow
The second half builds a Node.js terminal script that accepts a research question and writes a Markdown report. It combines a prescribed workflow with autonomous decisions inside individual stages. The workshop companion supplies the workflow explanation and diagram. OpenAI’s and Gemini’s Deep Research products provide the reference behavior: search repeatedly, aggregate sources, follow new questions, and synthesize the collected information into a report.
The script decomposes that behavior into a repeatable procedure:
- Accept an overall research question.
- Generate several search queries.
- Search for relevant results for each query.
- Extract learnings and follow-up questions from accepted results.
- Use those follow-ups to research another level while retaining accumulated evidence.
- Synthesize the collected material into a report.
The recursive part re-enters the same process with more context. It does not start a fresh, disconnected investigation each time.
Breadth controls how many queries branch from a research prompt; depth controls how many levels of follow-up the process explores. For an initial electric-car question, breadth three might produce Model 3 specifications, charging infrastructure, and battery technology. At the next level, breadth two might split Model 3 research into range and pricing, and charging research into US fast-charging stations and home installation. These settings determine both the coverage of the topic and how far each line of inquiry develops.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Expand the research question into searches
The first function, generateSearchQueries, takes a question and a requested query count, defaulting to three. A shared mainModel keeps model selection in one place. The prompt asks for the requested number of queries, while the Zod schema allows between one and five strings:
typescript
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
const mainModel = openai('gpt-4o');
async function generateSearchQueries(query: string, count = 3) {
const { object } = await generateObject({
model: mainModel,
prompt: `Generate ${count} search queries for the following query: ${query}`,
schema: z.object({
queries: z.array(z.string()).min(1).max(5),
}),
});
return object.queries;
}
The distinction matters: the prompt requests a count; the schema validates a permitted range. It does not enforce exactly three results.
The working research question is what someone needs to become a D1 shot put athlete. Albanese attributes the choice to a Gemini team presentation about Deep Research, where he recalls it being used to evaluate the product’s progress. The initial run produces search-oriented queries about requirements, training regimens, and NCAA Division One qualifications. This gives the next stage concrete searches instead of asking a search engine to resolve the entire research problem at once.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Fetch page content and trim the payload
The retrieval function uses Exa. Albanese imports Exa from exa-js, initializes the client with an API key, defines a reusable search-result type, and wraps searchAndContents in searchWeb(query: string). The demo requests one result per search. He suggests making the count configurable, or potentially letting the model choose it, as an experiment beyond this minimal implementation.
The workshop also enables live crawling rather than relying on cached content. The companion implementation uses the historical option livecrawl: 'always'. Exa’s current freshness documentation replaces that option with maxAgeHours: 0 for always-live retrieval. The tradeoff discussed here is freshness versus additional retrieval latency; fetching a page again does not establish that its claims are accurate.
Before sending results to the model, searchWeb maps them down to the information needed for research. A favicon URL is the concrete example of metadata to discard: it consumes context without helping answer the question. Albanese reports that trimming irrelevant fields both reduces token costs and makes the model more effective. A tool’s return value is part of the model’s working context, so its shape deserves the same care as its input schema.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Search, evaluate, and retry with feedback
Retrieving a page is only part of finding a useful source. searchAndProcess adds an agentic loop around retrieval, using generateText with searchWeb and evaluate tools. Two local arrays track the page’s status: pendingSearchResults holds candidates awaiting evaluation, and searchResults holds accepted sources. Evaluation removes the latest pending candidate, keeps it if relevant, and otherwise discards it.
The prompt asks the model to search for the query, while a researcher system prompt instructs it to evaluate whether each result helps answer that query. The initial maxSteps value is five. That is a budget of five model-generation steps, not five complete search/evaluate cycles and not a guarantee that a relevant source will be found. Albanese discusses raising the limit but prefers relatively small bounds to constrain runaway work.
The searchWeb tool calls the retrieval function, pushes the returned candidates into pendingSearchResults, and returns them so the model can see them. The evaluate tool takes no arguments. Its execute function retrieves the latest pending candidate directly from local state and makes a nested generateObject call. That call receives the research query and the stringified candidate, separated with XML-style delimiters in the prompt.
This evaluator needs only a classification, so it uses generateObject in enum mode, restricted to relevant or irrelevant. An accepted candidate moves into searchResults. A rejected candidate produces a tool result telling the model to search again with a more specific query. When the outer generation loop continues, that feedback is now in the conversation and can influence the next search. The control flow is bounded by application settings, while query refinement remains a model decision.
The parameterless evaluator avoids an expensive form of copying. If the page were an argument to evaluate, the model would have to generate the page text again as part of its tool call—even though the application already has it. A long crawled page could require thousands of output tokens merely to reproduce existing data, introducing latency, cost, and copying errors. Local state lets code retrieve the original object instead.
The recorded run makes the feedback loop visible. A Throws University page about benchmark lifts for throwing 50 feet is rejected for the D1 requirements query. Another candidate is also rejected. A later page about men’s track recruiting standards is accepted, and its scraped content appears in the returned results. Acceptance here is the evaluator’s relevance judgment, which is the condition for advancing to the next stage.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Extract an insight and the next questions
Once a source is accepted, generateLearnings turns it into structured research material. It takes the query and scraped result, calls generateObject with mainModel, and asks for a learning plus follow-up questions. The source is again stringified and placed inside XML-style delimiters. Its schema contains a learning string and a followUpQuestions array of strings.
The main function now has a complete single-level pipeline: generate queries, call searchAndProcess for each query, then call generateLearnings for each accepted result. In the next run, the first candidate is rejected and the next is accepted and processed. The generated learning describes four years of varsity experience, strong state finishes, and national-event participation, with an approximately 60-foot target that Albanese tentatively reads for tier-one recruits. These are generated research claims, not established NCAA requirements. One follow-up asks about specific training regimens.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Keep evidence while following new questions
Another generated follow-up asks how Division 1 recruiting standards differ from Divisions 2 and 3. Answering that requires running the pipeline again with a new question. Albanese moves the working logic from main into deepResearch and introduces state outside the function so accumulated findings survive recursive calls. main now supplies the original prompt and calls this new function.
Two types organize the shared data. Learning pairs an insight with follow-up questions. Research holds the original query, active queries, accumulated search results, learnings, and completed queries. The accumulated object begins with an undefined original query and empty arrays. This store will eventually become the input to report generation.
The next edit makes each stage update that store. The function’s input is renamed from query to prompt; the original research query is initialized only when it is still undefined. Newly generated queries become the active queries, and completed work adds sources, learnings, and completed queries to the accumulated state. Depth and breadth become explicit inputs controlling how much further the function explores.
Recursion needs a stopping condition before it needs another model call. At depth zero, deepResearch returns the accumulated research. Otherwise it constructs the next prompt from the overall goal, previous searches, and follow-up questions, then calls itself again with a smaller budget. The companion specifies the reduction as depth - 1 and Math.ceil(breadth / 2). Depth therefore guarantees termination; breadth narrows the branches but can remain at one. These controls limit both waiting time and API spending.
In the next run, the search loop again rejects an unsuitable source and accepts recruiting standards. It then descends into a more specific question about the physical and technical skills essential for a D1 shot put athlete, followed by training and skills requirements. The output now shows research developing from earlier findings instead of merely repeating the initial query expansion.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Give the evaluator a history of used pages
Recursion exposes a missing piece of context: an evaluator working on one query does not yet know which pages other branches have already accepted. Reusing a large page can add substantial duplicate content to the final research context. Albanese therefore extends searchAndProcess with an accumulatedSources argument and makes source history part of evaluation.
The evaluator’s prompt now says to mark a page irrelevant if it already exists in the accumulated results. An existingResults section contains stringified URLs only, because duplicate checking does not require another copy of every page body. The caller passes accumulatedResearch.searchResults into the new argument. This is a prompt-based rejection rule: a duplicate should trigger the same retry feedback as an irrelevant result. The preceding run did not show a duplicate, so the recording explains the intended behavior rather than demonstrating that branch firing.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Synthesize the research and write a report
The accumulated evidence now needs a final synthesis. generateReport accepts the typed research object and calls generateText with o3-mini, rather than mainModel. Albanese prefers a reasoning model for this stage and reports good results with this choice, while encouraging experimentation. The initial prompt simply asks for a report based on the stringified research data, and the function returns the generated text.
The end-to-end main function awaits deepResearch, logs status updates, passes the resulting store to generateReport, and writes the returned text to a Markdown file using fs. The application has now closed the loop from an input question to a local artifact.
Albanese reports that the first completed report arrives after about a minute in this demonstration. It synthesizes the research into discussion of technique, training, and common beginner pitfalls. But the model has had to infer the report’s presentation because the program supplied no explicit instructions about format or structure. The next improvement is therefore in the report prompt, not in retrieval or recursion.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Specify the report the reader should receive
The final revision explicitly asks for Markdown and gives the report a more deliberate structure. A system prompt supplies an expert-researcher role, the current date, and research-oriented instructions. Speculation and prediction are allowed only when flagged. These instructions make the desired presentation part of the generation contract instead of leaving the model to infer it.
After rerunning the workflow, the report uses more structured Markdown and includes a date. Its recruiting discussion covers varsity participation, competitive exposure, performance benchmarks, and separate men’s and women’s categories. The generated report mentions typically four years of varsity participation and a 55-foot benchmark; Albanese’s spoken reading of an elite figure is ambiguous. These are demo outputs, not validated recruiting guidance: NCSA’s recruiting standards explicitly vary by college and conference, and its current figures cannot validate the historical output. Albanese reports that the completed workflow occupies 218 lines of code.
The finished artifact comes from a sequence of small, working layers: generation, tools, typed outputs, retrieval, relevance feedback, accumulated research, and a separate synthesis prompt. Albanese closes by inviting questions through X and directing readers to the AI SDK documentation and cookbook guides for further examples.
Suggest correction
This note stays in this page until you copy or download it. Nothing is submitted; reloading clears the draft.
Resources
From the talk
Companion guide covering SDK fundamentals and a Node.js Deep Research workflow.
Step-by-step code for query expansion, Exa retrieval, relevance evaluation, recursive research, and Markdown report generation.
Further reading
Starter repository, dependency installation, and environment configuration instructions.
Nico Albanese's starter repository linked from the workshop setup guide.
Original model capabilities and knowledge-cutoff information for the workshop's opening model.
Updates since the talk
Current cache-age and live-crawling controls, including migration context for the workshop's livecrawl option.
Full transcript
Loading transcript…