Tutorial Vercel AI SDK 7 pentru Next.js și Nuxt (2026)

Tutorial Vercel AI SDK 7 despre chat cu streaming prin useChat, tool-uri, generative UI și aprobări în Next.js și Nuxt, plus un checklist de producție.
· 13 min de citit
Vercel AI SDK e biblioteca TypeScript pe care o aleg cele mai multe echipe React și Vue când adaugă într-un produs un chat, un asistent sau un agent. Versiunea 7 a apărut pe 25 iunie 2026 și a redenumit o bună parte din API, așa că multe tutoriale scrise pentru versiunile 5 sau 6 nu mai compilează.
Construiesc front-end-uri în Nuxt și React cu funcționalități AI, așa că pentru acest ghid am construit de două ori același asistent de suport pentru comenzi, o dată în Next.js și o dată în Nuxt 4. Răspunde în streaming, caută comenzi cu un tool, afișează rezultatul ca pe un card și cere confirmare înainte să anuleze ceva. Fiecare fragment de cod e verificat cu TypeScript pe ai 7.0.173, versiunea curentă la momentul scrierii, alături de @ai-sdk/react 4.0.177 și @ai-sdk/vue 4.0.173. Am rulat și ambele route handler-e cu modelul simulat din SDK, așa că apelurile de tool-uri și aprobările de mai jos se comportă cum le descriu.
Ce este Vercel AI SDK?
AI SDK e un toolkit TypeScript gratuit și open source, creat de Vercel, pentru funcționalități AI și agenți care merg cu orice furnizor de modele. Nucleul apelează modelele (text, output structurat, tool-uri, streaming), iar pachetele UI le dau aplicațiilor React, Vue, Svelte și Angular un hook useChat care afișează răspunsul pe măsură ce vine.
Pe scurt:
- Cine îl face. Vercel. Codul e pe github.com/vercel/ai, sub licența Apache-2.0, iar documentația e pe ai-sdk.dev.
- Stadiu. Stabil, versiunea 7, lansată pe 25 iunie 2026. La lansarea versiunii 7, Vercel vorbea de peste 16 milioane de descărcări pe săptămână.
- Cerințe. Node.js 22 sau mai nou și ESM, pentru că versiunea 7 a renunțat la CommonJS.
- Furnizori. OpenAI, Anthropic, Google și zeci de alții, prin pachete dedicate. Furnizorul Vercel AI Gateway vine inclus în
ai, așa că un simplu string ca"anthropic/claude-sonnet-5.5"funcționează cu o singură cheie de gateway.
| Pachet | Ce face | Folosit în ghid |
|---|---|---|
ai | AI SDK Core, cu streamText, generateText, tool-uri, agenți, stream-uri de mesaje UI și furnizorul AI Gateway | Ambele aplicații |
@ai-sdk/react | AI SDK UI pentru React și Next.js, cu useChat, useCompletion și useObject | Next.js |
@ai-sdk/vue | Aceleași hook-uri, ca composables Vue | Nuxt |
@ai-sdk/svelte, @ai-sdk/angular | La fel, pentru Svelte și Angular | Nu |
@ai-sdk/openai, @ai-sdk/anthropic și altele | Acces direct la un furnizor, fără gateway | Opțional |
zod | Scheme pentru inputul tool-urilor | Ambele aplicații |
Vercel are și o bibliotecă nouă, fără legătură cu asta, cu un nume asemănător, UI SDK, care construiește componente accesibile și le lasă pe mâna agenților. Am scris despre ea în Ghid de instalare Vercel UI SDK în Next.js și Nuxt. Articolul de față e despre AI SDK, cel care vorbește cu modelele.
Ce e nou în AI SDK 7?
AI SDK 7 e despre agenți care rulează în producție, cu aprobări, context tipizat, timeout-uri, rulări durabile și telemetrie. A redenumit și opțiuni folosite peste tot, de aceea tutorialele mai vechi nu mai merg.
Ce aduce nou:
- O singură opțiune
reasoningpegenerateTextșistreamText, de la"none"la"max", tradusă în setarea de raționament a fiecărui furnizor. - Context tipizat pentru tool-uri. Un tool își declară
contextSchema, iar tu îi dai valorile, pentru fiecare tool, întoolsContext. Mai jos îl folosesc ca să le dau tool-urilor ID-ul utilizatorului autentificat. - Aprobări pentru tool-uri cu
toolApprovalpegenerateText,streamTextșiToolLoopAgent. Poți întreba mereu, poți decide pentru fiecare apel printr-o funcție sau poți aproba și refuza automat. Aprobările pot fi semnate HMAC, ca un client să nu poată falsifica una. - Agenți durabili.
WorkflowAgentdin@ai-sdk/workflowsupraviețuiește restart-urilor, deploy-urilor și aprobărilor care întârzie. - Timeout-uri pentru tot apelul, pentru fiecare pas, fiecare chunk și fiecare tool, care opresc execuția cu un
TimeoutError. - Telemetrie cu
registerTelemetryși integrări ca@ai-sdk/otel. - Și altele, mai ales experimentale. MCP Apps, un
HarnessAgentcare rulează harness-uri ca Claude Code și Codex, sesiuni în sandbox, o interfață în terminal, voce și video.
Dacă faci upgrade de la versiunea 6, astea sunt redenumirile peste care dai primele:
| AI SDK 6 | AI SDK 7 |
|---|---|
system: "…" | instructions: "…" |
stopWhen: stepCountIs(5) | stopWhen: isStepCount(5) |
onFinish, onStepFinish | onEnd, onStepEnd |
result.fullStream | result.stream |
return result.toUIMessageStreamResponse() | return createUIMessageStreamResponse({ stream: toUIMessageStream({ stream: result.stream }) }) |
needsApproval pe tool | toolApproval pe apel |
experimental_context | context, completat din toolsContext |
new Chat() din @ai-sdk/vue | useChat() din @ai-sdk/vue |
Unele nume vechi, ca system, onFinish, toUIMessageStreamResponse() și clasa Chat din Vue, merg în continuare ca alias-uri depreciate. O schimbare poate totuși strica o aplicație care mergea. Mesajele de sistem din messages sunt acum respinse, dacă nu setezi allowSystemInMessages: true. Codemod-ul se ocupă de majoritatea redenumirilor:
npx @ai-sdk/codemod v7
Cum funcționează useChat?
useChat ține conversația în browser, ca listă de mesaje UI. La fiecare trimitere, postează tot istoricul la /api/chat și afișează răspunsul venit în streaming ca părți tipizate.
sendMessage({ text })adaugă mesajul utilizatorului și trimite toate mesajele la/api/chat.- Route handler-ul le transformă în mesaje pentru model cu
convertToModelMessages, apeleazăstreamTextși trimite rezultatul înapoi cutoUIMessageStreamșicreateUIMessageStreamResponse. - Hook-ul adaugă părțile la mesajul asistentului pe măsură ce sosesc, iar
statustrece de lasubmittedlastreamingși apoi laready(sauerror). - Tu afișezi
message.partsîn ordine, cu câte o ramură pentru fiecare tip de parte.
| Tipul părții | Ce conține |
|---|---|
text | Textul modelului, venit în streaming |
reasoning | Raționamentul, când modelul îl trimite |
tool-<name> | Un apel al unui tool definit de tine, de exemplu tool-getOrder, cu inputul, starea și outputul lui |
dynamic-tool | Un tool necunoscut la compilare, de exemplu unul încărcat dintr-un server MCP |
data-<name> | Date proprii trimise în streaming de pe server |
source-url, file | Surse și fișiere întoarse de model |
step-start | Granița dintre doi pași ai unui apel în mai mulți pași |
Pentru că clientul trimite tot istoricul de fiecare dată, serverul trebuie să-l trateze ca input nesigur. Revin la asta în checklist.
Cum instalezi AI SDK în Next.js
Instalezi trei pachete, adaugi o cheie de AI Gateway, scrii un route handler și o componentă client. Pașii urmează quickstart-ul oficial pentru App Router.
1. Creează aplicația și instalează pachetele
Ai nevoie de Node.js 22 sau mai nou.
pnpm create next-app@latest my-ai-app
cd my-ai-app
pnpm add ai @ai-sdk/react zod
2. Adaugă cheia de AI Gateway
Creează o cheie API în secțiunea AI Gateway din dashboard-ul Vercel și pune-o în .env.local:
# .env.local
AI_GATEWAY_API_KEY=cheia-ta
Furnizorul de gateway citește singur AI_GATEWAY_API_KEY, așa că string-uri de model ca "anthropic/claude-sonnet-5.5" merg direct. Ca să apelezi direct un furnizor, instalează-i pachetul (de exemplu @ai-sdk/openai) și dă-i modelul în locul string-ului.
3. Creează route handler-ul
// app/api/chat/route.ts
import {
convertToModelMessages,
createUIMessageStreamResponse,
streamText,
toUIMessageStream,
type UIMessage,
} from "ai"
export const maxDuration = 30
export async function POST(req: Request) {
const { messages }: { messages: UIMessage[] } = await req.json()
const result = streamText({
model: "anthropic/claude-sonnet-5.5",
instructions: "Ești asistentul de suport al unui magazin online. Răspunde scurt.",
messages: await convertToModelMessages(messages),
})
return createUIMessageStreamResponse({
stream: toUIMessageStream({ stream: result.stream }),
})
}
instructions e promptul de sistem (înainte de versiunea 7 se numea system). maxDuration îi permite funcției să trimită răspunsul în streaming până la 30 de secunde pe Vercel.
4. Construiește pagina de chat
// app/page.tsx
"use client"
import { useChat } from "@ai-sdk/react"
import { useState } from "react"
export default function ChatPage() {
const [input, setInput] = useState("")
const { messages, sendMessage, status, stop, error } = useChat()
const busy = status === "submitted" || status === "streaming"
return (
<main className="mx-auto max-w-xl p-6">
{messages.map((message) => (
<div key={message.id} className="mb-4">
<strong>{message.role === "user" ? "Tu" : "Asistent"}</strong>
{message.parts.map((part, i) =>
part.type === "text" ? <p key={i}>{part.text}</p> : null,
)}
</div>
))}
{error && <p role="alert">Ceva n-a mers. Încearcă din nou.</p>}
<form
onSubmit={(e) => {
e.preventDefault()
if (!input.trim()) return
sendMessage({ text: input })
setInput("")
}}
>
<input
value={input}
onChange={(e) => setInput(e.target.value)}
placeholder="Întreabă de o comandă"
/>
{busy ? (
<button type="button" onClick={() => stop()}>Oprește</button>
) : (
<button type="submit">Trimite</button>
)}
</form>
</main>
)
}
useChat trimite implicit la /api/chat, deci n-ai nimic de configurat. Hook-ul nu mai gestionează câmpul de input, cum făcea înainte de versiunea 5, de aceea pagina îl ține în useState. Rulează pnpm dev, deschide http://localhost:3000 și răspunsul apare cuvânt cu cuvânt.
Cum adaugi tool-uri unui chatbot AI SDK
Un tool e o funcție pe care modelul poate decide s-o apeleze. Îl definești cu tool() (o descriere, o schemă Zod pentru input și o funcție execute), îl dai lui streamText și setezi stopWhen, ca modelul să poată răspunde după ce vede rezultatul.
1. Simulează baza de date
Asistentul are nevoie de comenzi pe care să le caute. Într-o aplicație reală, asta e baza ta de date. Pentru tutorial, ajunge un obiect în memorie:
// lib/orders.ts: o bază de date simulată, în memorie
export type Order = {
id: string
status: "processing" | "shipped" | "delivered"
total: string
eta: string
}
const orders: Record<string, Order & { userId: string }> = {
A1001: { id: "A1001", userId: "u_1", status: "processing", total: "84,00 €", eta: "joi" },
}
export async function findOrder(userId: string, orderId: string): Promise<Order | undefined> {
const order = orders[orderId]
if (!order || order.userId !== userId) return undefined
return { id: order.id, status: order.status, total: order.total, eta: order.eta }
}
export async function cancelOrder(userId: string, orderId: string): Promise<boolean> {
const order = orders[orderId]
if (!order || order.userId !== userId || order.status !== "processing") return false
delete orders[orderId]
return true
}
Ambele funcții primesc ID-ul utilizatorului, așa că nimeni nu ajunge la comenzile altcuiva.
2. Definește tool-urile
// lib/ai/tools.ts
import { tool, type InferUITools, type UIDataTypes, type UIMessage } from "ai"
import { z } from "zod"
import { cancelOrder, findOrder } from "@/lib/orders"
const userContext = z.object({ userId: z.string() })
export const tools = {
getOrder: tool({
description: "Caută o comandă după număr. Utilizatorul vede rezultatul ca pe un card.",
inputSchema: z.object({
orderId: z.string().describe("Numărul comenzii, de exemplu A1001"),
}),
contextSchema: userContext,
execute: async ({ orderId }, { context }) => {
const order = await findOrder(context.userId, orderId)
if (!order) throw new Error(`Nu există comanda ${orderId} în acest cont.`)
return order
},
}),
cancelOrder: tool({
description: "Anulează o comandă care n-a fost încă expediată.",
inputSchema: z.object({ orderId: z.string() }),
contextSchema: userContext,
execute: async ({ orderId }, { context }) => {
const cancelled = await cancelOrder(context.userId, orderId)
return { orderId, cancelled }
},
}),
}
export type ChatMessage = UIMessage<never, UIDataTypes, InferUITools<typeof tools>>
Modelul alege orderId, dar niciodată userId. Acela vine prin context, pe care îl completează serverul tău, așa că un prompt ca „arată-mi comanda A1002” nu poate ajunge la comanda altui client.
ChatMessage e tipul de mesaj care conține tool-urile tale. Dă-l lui useChat și fiecare parte de tool își știe tipurile de input și output.
3. Folosește tool-urile în route handler
// app/api/chat/route.ts
import {
convertToModelMessages,
createUIMessageStreamResponse,
isStepCount,
streamText,
toUIMessageStream,
validateUIMessages,
} from "ai"
import { tools, type ChatMessage } from "@/lib/ai/tools"
import { getUserId } from "@/lib/auth"
export const maxDuration = 30
export async function POST(req: Request) {
const userId = await getUserId(req)
if (!userId) return new Response("Unauthorized", { status: 401 })
const body = await req.json()
const messages = await validateUIMessages<ChatMessage>({ messages: body.messages, tools })
const result = streamText({
model: "anthropic/claude-sonnet-5.5",
instructions:
"Ești asistentul de suport al unui magazin online. Folosește tool-urile ca să cauți și să anulezi comenzi. Răspunde scurt.",
messages: await convertToModelMessages(messages),
tools,
toolsContext: {
getOrder: { userId },
cancelOrder: { userId },
},
toolApproval: { cancelOrder: "user-approval" },
stopWhen: isStepCount(5),
})
return createUIMessageStreamResponse({
stream: toUIMessageStream({ stream: result.stream }),
})
}
Ce s-a schimbat față de prima versiune:
getUserIdține locul autentificării tale (Auth.js, Clerk, Supabase sau propria sesiune). Fără utilizator nu există chat.validateUIMessagesverifică istoricul trimis de client, inclusiv fiecare parte de tool, după schemele tool-urilor tale.toolsContextîi dă fiecărui tool ID-ul utilizatorului.toolApprovalîl face pecancelOrdersă aștepte utilizatorul. Detalii mai jos.stopWhen: isStepCount(5)îi permite modelului să apeleze un tool, să citească rezultatul și să continue, în cel mult cinci pași. Fără el, răspunsul se oprește la apelul tool-ului și utilizatorul nu primește niciun răspuns.
Cum afișezi generative UI din rezultatele tool-urilor
În AI SDK UI, generative UI înseamnă să afișezi componente proprii pornind de la părțile de tool. Fiecare apel de tool ajunge la client ca parte tool-<name>, iar tu afișezi ceva pentru fiecare stare a ei, de exemplu un indicator cât rulează, o componentă când sosește outputul și o eroare când pică.
| Stare | Când | Ce afișez |
|---|---|---|
input-streaming | Modelul încă scrie inputul tool-ului | Un placeholder |
input-available | Inputul e complet și tool-ul rulează | „Caut comanda…” |
approval-requested | Tool-ul are nevoie mai întâi de aprobarea unui om | Butoane de aprobare și refuz |
approval-responded | Omul a răspuns, tool-ul n-a terminat | Un status scurt |
output-available | Tool-ul a întors rezultatul | Componenta, construită din part.output |
output-error | Tool-ul a aruncat o eroare sau inputul era invalid | part.errorText |
output-denied | Aprobarea a fost refuzată | „Comanda a rămas activă.” |
Componenta e React simplu. Nu știe nimic despre AI:
// components/order-card.tsx
import type { Order } from "@/lib/orders"
export function OrderCard({ order }: { order: Order }) {
return (
<article className="rounded-lg border p-4">
<h3 className="font-semibold">Comanda {order.id}</h3>
<p>{order.status === "delivered" ? "Livrată" : `Sosește ${order.eta}`}</p>
<p>Total: {order.total}</p>
</article>
)
}
Pagina afișează fiecare parte după tip și stare:
// app/page.tsx
"use client"
import { useChat } from "@ai-sdk/react"
import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai"
import { useState } from "react"
import { OrderCard } from "@/components/order-card"
import type { ChatMessage } from "@/lib/ai/tools"
export default function ChatPage() {
const [input, setInput] = useState("")
const { messages, sendMessage, addToolApprovalResponse, status, stop } = useChat<ChatMessage>({
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
})
const busy = status === "submitted" || status === "streaming"
return (
<main className="mx-auto max-w-xl p-6">
{messages.map((message) => (
<div key={message.id} className="mb-4">
<strong>{message.role === "user" ? "Tu" : "Asistent"}</strong>
{message.parts.map((part, i) => {
const key = `${message.id}-${i}`
switch (part.type) {
case "text":
return <p key={key}>{part.text}</p>
case "tool-getOrder":
if (part.state === "output-available") {
return <OrderCard key={key} order={part.output} />
}
if (part.state === "output-error") {
return <p key={key} role="alert">{part.errorText}</p>
}
return <p key={key}>Caut comanda…</p>
case "tool-cancelOrder":
if (part.state === "approval-requested") {
return (
<div key={key}>
<p>Anulezi comanda {part.input.orderId}?</p>
<button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: true })}>
Anulează
</button>
<button onClick={() => addToolApprovalResponse({ id: part.approval.id, approved: false })}>
Păstreaz-o
</button>
</div>
)
}
if (part.state === "output-available") {
return (
<p key={key}>
{part.output.cancelled
? `Comanda ${part.output.orderId} a fost anulată.`
: "Comanda nu mai poate fi anulată."}
</p>
)
}
if (part.state === "output-denied") return <p key={key}>Comanda a rămas activă.</p>
return null
default:
return null
}
})}
</div>
))}
<form
onSubmit={(e) => {
e.preventDefault()
if (!input.trim()) return
sendMessage({ text: input })
setInput("")
}}
>
<input value={input} onChange={(e) => setInput(e.target.value)} placeholder="Întreabă de o comandă" />
{busy ? (
<button type="button" onClick={() => stop()}>Oprește</button>
) : (
<button type="submit">Trimite</button>
)}
</form>
</main>
)
}
Datorită lui useChat<ChatMessage>, TypeScript știe că part.output e un Order în ramura tool-getOrder și că part.input.orderId e un string. Când am folosit intenționat outputul cu un tip greșit, verificarea de tipuri a picat, exact ce vrei când tool-urile și interfața se schimbă separat.
Întreabă „Unde e comanda A1001?” și modelul apelează getOrder, cardul ia locul placeholderului, iar un al doilea pas adaugă o propoziție de genul „Sosește joi.”
N-ai nevoie de o bibliotecă de componente pentru asta. AI Elements, setul de componente de chat de la Vercel construit pe shadcn/ui, se mută în shadcn/ui și va fi depreciat la sfârșitul lui noiembrie 2026, așa că aș construi pe componentele tale sau direct pe shadcn/ui.
Cum ceri aprobare înainte să ruleze un tool
Setezi toolApproval: { cancelOrder: "user-approval" } pe streamText. Partea tool-ului se oprește atunci în starea approval-requested. Interfața ta apelează addToolApprovalResponse, iar useChat trimite răspunsul înapoi, ca serverul să ruleze tool-ul sau să renunțe la el.
Iată ce se întâmplă când utilizatorul scrie „Anuleaz-o”:
- Modelul apelează
cancelOrder. Serverul nu-l rulează și trimite în stream o partetool-cancelOrderîn stareaapproval-requested. - Pagina afișează „Anulezi comanda A1001?” cu două butoane.
- Un click apelează
addToolApprovalResponse({ id: part.approval.id, approved }), iar partea trece înapproval-responded. - Datorită lui
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,useChatretrimite singur conversația. - Serverul vede aprobarea și rulează tool-ul sau, dacă a fost refuzat, îi spune modelului că apelul a fost respins. Modelul își scrie apoi răspunsul în același mesaj al asistentului.
Am testat fluxul ăsta cu modelul simulat. Comanda exista în continuare cât timp partea stătea în approval-requested și a fost ștearsă abia după ce a venit aprobarea.
toolApproval acceptă mai mult decât "user-approval". O funcție pentru fiecare tool poate aproba automat cazurile mărunte și le poate trimite pe celelalte utilizatorului, iar deciziile automate apar în aceleași stări, cu part.approval.isAutomatic setat.
Există o capcană. Clientul trimite tot istoricul la fiecare request, deci un client modificat ar putea fabrica o aprobare. Pentru orice mută bani sau șterge date, adaugă experimental_toolApprovalSecret (îl găsești în checklist), ca serverul să accepte doar aprobările semnate de el. Tot cu aprobări aș proteja și tool-urile care scriu printr-un server MCP, despre care am scris în Servere MCP pentru SaaS. AI SDK poate folosi tool-urile oricărui server MCP prin createMCPClient din @ai-sdk/mcp.
Cum instalezi AI SDK în Nuxt
Nuxt folosește același cod de server, într-un handler h3, iar @ai-sdk/vue oferă useChat ca composable Vue. Tool-urile și tipul de mesaj rămân la fel.
1. Creează aplicația și instalează pachetele
pnpm create nuxt my-ai-app
cd my-ai-app
pnpm add ai @ai-sdk/vue zod
2. Pune cheia în runtime config
# .env
NUXT_AI_GATEWAY_API_KEY=cheia-ta
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
aiGatewayApiKey: "", // completat din NUXT_AI_GATEWAY_API_KEY
},
})
Prefixul NUXT_ îi permite lui Nuxt să suprascrie runtimeConfig.aiGatewayApiKey la rulare, iar cheia nu ajunge niciodată în bundle-ul de client.
3. Mută tool-urile pe server
Copiază lib/orders.ts și lib/ai/tools.ts din secțiunea Next.js în server/ai/orders.ts și server/ai/tools.ts și schimbă un singur import în fișierul cu tool-uri:
// server/ai/tools.ts
import { cancelOrder, findOrder } from "./orders"
Le țin intenționat în afara server/utils. Nuxt importă automat tot ce e în folderul ăla, în tot serverul, iar eu prefer să văd de unde vine tools.
4. Scrie ruta de API
// server/api/chat.post.ts
import {
convertToModelMessages,
createGateway,
createUIMessageStreamResponse,
isStepCount,
streamText,
toUIMessageStream,
validateUIMessages,
} from "ai"
import { tools, type ChatMessage } from "~~/server/ai/tools"
export default defineLazyEventHandler(() => {
const apiKey = useRuntimeConfig().aiGatewayApiKey
if (!apiKey) throw new Error("Missing NUXT_AI_GATEWAY_API_KEY")
const gateway = createGateway({ apiKey })
return defineEventHandler(async (event) => {
const userId = await getUserId(event) // autentificarea ta, din server/utils
if (!userId) throw createError({ statusCode: 401 })
const body = await readBody(event)
const messages = await validateUIMessages<ChatMessage>({ messages: body.messages, tools })
const result = streamText({
model: gateway("anthropic/claude-sonnet-5.5"),
instructions:
"Ești asistentul de suport al unui magazin online. Folosește tool-urile ca să cauți și să anulezi comenzi. Răspunde scurt.",
messages: await convertToModelMessages(messages),
tools,
toolsContext: {
getOrder: { userId },
cancelOrder: { userId },
},
toolApproval: { cancelOrder: "user-approval" },
stopWhen: isStepCount(5),
})
return createUIMessageStreamResponse({
stream: toUIMessageStream({ stream: result.stream }),
})
})
})
defineLazyEventHandler creează gateway-ul o singură dată, la primul request, iar h3 trimite Response-ul întors exact cum e, cu stream cu tot. getUserId e o funcție de-a ta din server/utils, de exemplu una construită pe getUserSession din nuxt-auth-utils.
5. Adaugă componenta de card
<!-- app/components/OrderCard.vue -->
<script setup lang="ts">
import type { Order } from "~~/server/ai/orders"
defineProps<{ order: Order }>()
</script>
<template>
<article class="rounded-lg border p-4">
<h3 class="font-semibold">Comanda {{ order.id }}</h3>
<p>{{ order.status === "delivered" ? "Livrată" : `Sosește ${order.eta}` }}</p>
<p>Total: {{ order.total }}</p>
</article>
</template>
Importul doar de tip din server/ dispare la build, deci niciun cod de server nu ajunge în browser.
6. Construiește pagina de chat
<!-- app/pages/index.vue -->
<script setup lang="ts">
import { useChat } from "@ai-sdk/vue"
import { lastAssistantMessageIsCompleteWithApprovalResponses } from "ai"
import type { ChatMessage } from "~~/server/ai/tools"
const input = ref("")
const { messages, sendMessage, addToolApprovalResponse, status, stop } = useChat<ChatMessage>({
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithApprovalResponses,
})
const busy = computed(() => status.value === "submitted" || status.value === "streaming")
function onSubmit() {
if (!input.value.trim()) return
sendMessage({ text: input.value })
input.value = ""
}
</script>
<template>
<main class="mx-auto max-w-xl p-6">
<div v-for="message in messages" :key="message.id" class="mb-4">
<strong>{{ message.role === "user" ? "Tu" : "Asistent" }}</strong>
<template v-for="(part, i) in message.parts" :key="`${message.id}-${i}`">
<p v-if="part.type === 'text'">{{ part.text }}</p>
<template v-else-if="part.type === 'tool-getOrder'">
<OrderCard v-if="part.state === 'output-available'" :order="part.output" />
<p v-else-if="part.state === 'output-error'" role="alert">{{ part.errorText }}</p>
<p v-else>Caut comanda…</p>
</template>
<template v-else-if="part.type === 'tool-cancelOrder'">
<div v-if="part.state === 'approval-requested'">
<p>Anulezi comanda {{ part.input.orderId }}?</p>
<button @click="addToolApprovalResponse({ id: part.approval.id, approved: true })">Anulează</button>
<button @click="addToolApprovalResponse({ id: part.approval.id, approved: false })">Păstreaz-o</button>
</div>
<p v-else-if="part.state === 'output-available'">
{{ part.output.cancelled ? `Comanda ${part.output.orderId} a fost anulată.` : "Comanda nu mai poate fi anulată." }}
</p>
<p v-else-if="part.state === 'output-denied'">Comanda a rămas activă.</p>
</template>
</template>
</div>
<form @submit.prevent="onSubmit">
<input v-model="input" placeholder="Întreabă de o comandă">
<button v-if="busy" type="button" @click="stop()">Oprește</button>
<button v-else type="submit">Trimite</button>
</form>
</main>
</template>
În versiunea 7, useChat din Vue întoarce ref-uri. messages, status și error sunt ShallowRef-uri, despachetate automat în template și citite cu .value în script. Dacă chatul depinde de valori reactive, de exemplu un ID de chat din rută, dă-i un getter, useChat(() => ({ … })), iar composable-ul recreează chatul când se schimbă.
Lanțul de v-if restrânge tipul părții la fel ca switch-ul din React, iar vue-tsc verifică și template-ul. Când am scris intenționat greșit part.approval.id, verificarea de tipuri a picat.
Ce diferă între Next.js și Nuxt?
Foarte puțin. Tool-urile, tipul de mesaj și protocolul de streaming sunt aceleași; se schimbă doar legătura cu framework-ul.
| Next.js | Nuxt | |
|---|---|---|
| Pachetul de client | @ai-sdk/react | @ai-sdk/vue |
| Starea chatului | Valori simple din useChat | Ref-uri din useChat |
| Ruta | app/api/chat/route.ts, care exportă POST | server/api/chat.post.ts, un handler h3 |
| Citirea body-ului | await req.json() | await readBody(event) |
| Cheia de gateway | AI_GATEWAY_API_KEY, citită automat | NUXT_AI_GATEWAY_API_KEY, prin runtimeConfig și createGateway |
| Granița cu clientul | "use client" pe pagină | Niciuna; composable-ul rulează unde rulează componenta |
| Afișarea părților | switch (part.type) în JSX | Un lanț de v-if în template |
Dacă alegi framework-ul, nu SDK-ul, le-am comparat în React vs Vue în 2026.
Checklist de producție pentru AI SDK
Un chat care merge pe localhost e cam o treime din treabă. Înainte să-l primească utilizatori reali, trec prin lista asta:
- Autentifică ruta și ia utilizatorul din sesiune. Dă-le tool-urilor ce le trebuie prin
toolsContext, niciodată prin prompt. - Validează istoricul cu
validateUIMessagesși tool-urile tale. Când aruncă o eroare, întoarce 400, nu 500. - Ține erorile tool-urilor sigure. Aruncă mesaje scurte din
executeși loghează detaliile pe server.redactToolErrors: trueînlocuiește textul care ajunge la client, cu o rezervă pentru modelele cu raționament, descrisă în documentație. - Pune
toolApprovalpe fiecare scriere și semnează aprobările cuexperimental_toolApprovalSecret. - Limitează bucla și timpul cu
isStepCount, untimeoutșimaxDurationpe Vercel. - Limitează request-urile per utilizator și notează consumul de tokeni din
onEnd, ca un singur utilizator să nu-ți umfle factura. - Salvează conversațiile cu
originalMessagesșionEndpetoUIMessageStream, ca un refresh să nu piardă chatul. - Urmărește apelurile cu
registerTelemetryși o integrare ca@ai-sdk/otel. - Testează fără cheie API.
MockLanguageModelV4dinai/testșisimulateReadableStreamscriptează răspunsurile modelului, cu apeluri de tool-uri cu tot. Așa am verificat rutele din acest articol. - Fă upgrade intenționat. Ține
aiși@ai-sdk/reactsau@ai-sdk/vuepe aceeași linie de versiuni și rulează codemod-ul la versiunile majore.
Punctele 3, 4, 5 și 7 arată împreună așa. Le-am verificat cu TypeScript, ca rută completă, pe ai 7.0.173:
const result = streamText({
// model, instructions, messages, tools, toolsContext și toolApproval, ca înainte
experimental_toolApprovalSecret: process.env.TOOL_APPROVAL_SECRET,
stopWhen: isStepCount(5),
timeout: { totalMs: 60_000, stepMs: 20_000, toolMs: 10_000 },
})
return createUIMessageStreamResponse({
stream: toUIMessageStream({
stream: result.stream,
redactToolErrors: true,
originalMessages: messages,
onEnd: ({ messages }) => saveChat({ chatId: body.id, messages }),
}),
})
saveChat îl scrii tu, de exemplu un tabel de chaturi cu cheia dată de ID-ul de chat pe care useChat îl trimite la fiecare request. Dacă și aplicația din jurul chatului a fost construită rapid cu unelte AI, checklistul meu de producție pentru aplicații vibe-coded acoperă restul, de la autentificare și reguli de acces la date până la secrete și monitorizare.
Cum te pot ajuta
Adaug funcționalități AI în produse Nuxt și React, de la un prim asistent până la agenți cu tool-uri și aprobări, din România, cu echipe din UE, Marea Britanie și SUA. Dacă plănuiești un chat cu AI SDK, sau ai unul care merge în demo, dar încă nu în producție, paginile de mai jos arată cum lucrez:
Spune-mi ce construiești și cere o ofertă. Îți răspund în cel mult o zi lucrătoare.
FAQ
Vercel AI SDK e gratuit?
Da. E open source, sub licența Apache-2.0, și se instalează din npm. Plătești doar consumul modelelor, fie direct furnizorului, fie prin Vercel AI Gateway.
Trebuie să fac deploy pe Vercel ca să folosesc AI SDK?
Nu. E o bibliotecă, iar route handler-ele întorc obiecte Response standard și rulează pe orice host cu Node.js 22 sau mai nou. Nici AI Gateway nu e obligatoriu, pentru că orice pachet de furnizor, ca @ai-sdk/openai, merge și fără el.
Merge AI SDK cu Nuxt și Vue?
Da. @ai-sdk/vue oferă useChat, useCompletion și useObject ca composables. Din versiunea 7, Vue folosește composable-ul useChat, care întoarce ref-uri; vechea clasă Chat e depreciată. Partea de server e o rută de API Nuxt obișnuită.
Care e diferența dintre AI SDK Core și AI SDK UI?
AI SDK Core (pachetul ai) rulează pe server și apelează modelele cu streamText, generateText, tool-uri și agenți. AI SDK UI (@ai-sdk/react, @ai-sdk/vue și celelalte) rulează în browser, ține starea chatului și afișează răspunsul venit în streaming cu useChat.
Ce e generative UI în AI SDK?
Înseamnă să afișezi componente proprii pornind de la apelurile de tool-uri ale modelului. Modelul apelează un tool ca getOrder, rezultatul ajunge la client ca parte tipizată tool-getOrder, iar tu afișezi o componentă, de exemplu un card de comandă, când starea ei e output-available.
Cum fac upgrade de la AI SDK 6 la 7?
Treci pe Node.js 22 și ESM, actualizează împreună ai și pachetele @ai-sdk/*, apoi rulează npx @ai-sdk/codemod v7. Redenumește, printre altele, system în instructions, stepCountIs în isStepCount și onFinish în onEnd. Ce rămâne, verifici de mână după ghidul oficial de migrare.
