Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Vercel AI SDK
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Das AI SDK von Vercel ist eine Bibliothek für TypeScript und JavaScript, mit der man Sprachmodelle in eigene Programme einbindet. Eine einheitliche Schnittstelle spricht viele Anbieter an. Die Bibliothek erzeugt Text, streamt Antworten Stück für Stück und baut mit ToolLoopAgent Agenten, die selbstständig Werkzeuge aufrufen. Sie läuft in Node.js-Programmen ebenso wie in Webanwendungen, etwa mit Next.js.
Vorbemerkungen
- Viele Anbieter: Für jeden Anbieter gibt es ein eigenes Paket, z. B.
@ai-sdk/openaioder@ai-sdk/anthropic. Diese Anleitung verwendet ein lokales Modell über Ollama, angebunden mit dem Paket@ai-sdk/openai-compatible. Es fallen also keine Kosten an und keine Daten verlassen den Rechner. - Voraussetzung: Ein laufendes Ollama mit dem Modell
qwen3:4b-instruct. Es kann Werkzeuge aufrufen. - Node.js aus Ubuntu: Das AI SDK braucht Node.js 22 oder neuer. Ubuntu 26.04 liefert Node.js 22.22, das reicht. Dieses Node.js kann TypeScript-Dateien aber nicht selbst ausführen: Es wurde ohne diese Funktion übersetzt und meldet
ERR_NO_TYPESCRIPT. Die Anleitung verwendet deshalb das kleine Werkzeugtsx, das TypeScript direkt startet. - Installation pro Projekt: Die Pakete lädt
npmin den Projektordner, zusammen rund 70 MB. - Version: Getestet mit ai 7.0.118, @ai-sdk/openai-compatible 3.0, zod 4.6, tsx 4.23 und TypeScript 7.0 unter Node.js 22.22 und npm 9.2 aus Ubuntu 26.04.
Installation
1. Paketlisten aktualisieren
Damit apt die aktuellen Versionen kennt.
sudo apt update
2. Node.js und npm installieren
Ist beides schon vorhanden (z. B. aus der Express-Anleitung), meldet apt das nur.
sudo apt install nodejs npm
Prüfen: Die Versionsnummer beginnt mit v22 oder höher.
node --version
3. Projektordner anlegen
mkdir ~/agent-aisdk
4. In den Projektordner wechseln
Alle weiteren Befehle werden hier ausgeführt.
cd ~/agent-aisdk
5. Projekt anlegen
Legt die Datei package.json mit Vorgabewerten an. Darin hält npm fest, welche Pakete das Projekt braucht.
npm init -y
6. Moderne Module einschalten
Stellt das Projekt auf ES-Module um. Erst dann funktionieren import … from … und await direkt in der Datei, ohne umschließende Funktion.
npm pkg set type=module
7. AI SDK installieren
ai– der Kern mit Textgenerierung, Streaming, Werkzeugen und Agenten@ai-sdk/openai-compatible– die Anbindung an Dienste mit der Schnittstelle von OpenAI, hier Ollamazod– beschreibt, welche Eingaben ein Werkzeug erwartet, und prüft sie
npm install ai @ai-sdk/openai-compatible zod
Prüfen: Die Ausgabe endet mit found 0 vulnerabilities.
8. Werkzeuge für TypeScript installieren
--save-dev kennzeichnet sie als Werkzeuge nur für die Entwicklung. tsx führt TypeScript-Dateien aus, typescript prüft die Typen, @types/node beschreibt die Typen von Node.js selbst.
npm install --save-dev tsx typescript @types/node@22
Prüfen: Die Liste nennt ai@7.0.118 (oder neuer), @ai-sdk/openai-compatible, zod, tsx, typescript und @types/node.
npm ls --depth=0
Beispiel 1: Ein Agent mit Werkzeug
9. Programm anlegen
nano agent.ts
Füge diesen Inhalt ein (Strg+Umschalt+V):
import { ToolLoopAgent, tool } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { z } from "zod";
// Ollama über die OpenAI-kompatible Schnittstelle
const ollama = createOpenAICompatible({
name: "ollama",
baseURL: "http://localhost:11434/v1",
});
const HAUPTSTAEDTE: Record<string, string> = {
"schleswig-holstein": "Kiel",
hamburg: "Hamburg",
niedersachsen: "Hannover",
bayern: "München",
};
const agent = new ToolLoopAgent({
model: ollama("qwen3:4b-instruct"),
instructions:
"Du beantwortest Fragen zu deutschen Bundesländern kurz auf Deutsch. " +
"Nutze für Landeshauptstädte immer das Werkzeug landeshauptstadt.",
tools: {
landeshauptstadt: tool({
description: "Liefert die Landeshauptstadt eines deutschen Bundeslands.",
inputSchema: z.object({
bundesland: z.string().describe("Name des Bundeslands, z. B. Bayern"),
}),
execute: async ({ bundesland }) => {
console.log(` [Werkzeug] landeshauptstadt(${bundesland})`);
return HAUPTSTAEDTE[bundesland.toLowerCase()] ?? "unbekannt";
},
}),
},
});
const ergebnis = await agent.generate({
prompt: "Was ist die Hauptstadt von Schleswig-Holstein und von Bayern?",
});
console.log(ergebnis.text);
console.log(`Schritte: ${ergebnis.steps.length}`);
- Modell:
createOpenAICompatiblelegt eine Anbindung an Ollama an.ollama("qwen3:4b-instruct")wählt daraus das Modell. - Werkzeug:
tool({ … })beschreibt ein Werkzeug mitdescription, den erwarteten Eingaben als zod-Schema (inputSchema) und der Funktionexecute, die es ausführt. zod prüft die Eingaben des Modells, bevorexecutesie bekommt. TypeScript kennt dadurch auch den Typ vonbundesland. - Agent:
ToolLoopAgentwiederholt die Schleife „Modell fragen → Werkzeuge ausführen → Ergebnisse zurückgeben“, bis das Modell eine Antwort liefert.generatestartet den Lauf.ergebnis.stepsenthält jeden Durchgang dieser Schleife.
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
10. Programm ausführen
npx startet tsx aus dem Ordner node_modules des Projekts.
npx tsx agent.ts
Prüfen: Die Ausgabe lautet nach einigen Sekunden:
[Werkzeug] landeshauptstadt(Schleswig-Holstein)
[Werkzeug] landeshauptstadt(Bayern)
Die Hauptstadt von Schleswig-Holstein ist Kiel und die Hauptstadt von Bayern ist München.
Schritte: 2
Im ersten Schritt hat das Modell die Werkzeuge aufgerufen, im zweiten mit den Ergebnissen geantwortet.
Beispiel 2: Antwort streamen
11. Programm anlegen
Bei längeren Antworten will man nicht warten, bis alles fertig ist. streamText liefert den Text Stück für Stück, sobald das Modell ihn erzeugt.
nano stream.ts
Füge diesen Inhalt ein:
import { streamText } from "ai";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
const ollama = createOpenAICompatible({
name: "ollama",
baseURL: "http://localhost:11434/v1",
});
const ergebnis = streamText({
model: ollama("qwen3:4b-instruct"),
prompt: "Schreibe ein kurzes Gedicht mit vier Zeilen über den Herbst an der Ostsee.",
});
// Text Stück für Stück ausgeben, sobald er ankommt
for await (const stueck of ergebnis.textStream) {
process.stdout.write(stueck);
}
process.stdout.write("\n");
textStream liefert die Textstücke nacheinander, for await wartet jeweils auf das nächste. process.stdout.write gibt sie ohne Zeilenumbruch aus, damit der Text zusammenhängend erscheint.
Speichere mit Strg+O und Enter und beende nano mit Strg+X.
12. Programm ausführen
npx tsx stream.ts
Prüfen: Das Gedicht erscheint Wort für Wort im Terminal. Es ist bei jedem Lauf anders.
Für Fragen nach Fakten eignen sich kleine Modelle wie qwen3:4b-instruct nur bedingt. Im Test erfand das Modell auf die Frage, wofür Ahrensburg bekannt ist, eine „historische Stadtbahn“. Für Faktenfragen gibt man einem Agenten deshalb Werkzeuge, die verlässliche Daten liefern, wie in Beispiel 1.
13. Typen prüfen
tsx entfernt die Typangaben nur und prüft sie nicht. Die Prüfung übernimmt der TypeScript-Compiler tsc. --noEmit prüft nur, ohne JavaScript-Dateien zu schreiben.
npx tsc --noEmit --strict --module nodenext --target es2022 --skipLibCheck --types node agent.ts stream.ts
Prüfen: Der Befehl gibt nichts aus. Bei Fehlern nennt er Datei, Zeile und Grund, z. B. einen Tippfehler in einem Feldnamen.
Wie geht es weiter?
- Strukturierte Ergebnisse: Mit
output: Output.object({ schema: z.object({ … }) })liefertgenerateTextein geprüftes Objekt statt Text. - Weboberfläche: Das Paket
@ai-sdk/reactbringt Hooks wieuseChatfür Chat-Oberflächen in React und Next.js mit. Der Server-Teil streamt die Antwort mitstreamTextan den Browser. - Freigaben: Werkzeuge können mit
needsApproval: trueeine Bestätigung durch den Menschen verlangen, bevor sie laufen. - Andere Anbieter: Mit
@ai-sdk/anthropicoder@ai-sdk/openaiund einem kostenpflichtigen Schlüssel in einer Umgebungsvariable tauscht man nur die Zeile mitmodel:aus. - Dokumentation: Die Doku passend zur installierten Version liegt in
node_modules/ai/docs, online unter https://ai-sdk.dev/docs.
Deinstallieren
1. Projekt entfernen
Löscht den Projektordner samt node_modules.
rm -rf ~/agent-aisdk
2. npm-Zwischenspeicher leeren (optional)
npm bewahrt heruntergeladene Pakete in ~/.npm auf. Dieser Befehl leert den ganzen Speicher. Das betrifft alle Node.js-Projekte, die ihre Pakete dann beim nächsten Mal wieder aus dem Internet laden.
npm cache clean --force
3. Node.js und npm entfernen (optional)
Nur ausführen, wenn kein anderes Programm sie braucht, z. B. Express oder Next.js.
sudo apt purge nodejs npm
Der nächste Befehl entfernt die Pakete, die nur dafür mitinstalliert wurden. Er entfernt aber auch alle anderen nicht mehr benötigten Pakete, auch solche von früheren Installationen. Lies daher die Liste, bevor du mit J bestätigst. Stehen dort Pakete, die du noch brauchst, brich mit N ab.
sudo apt autoremove --purge
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.