BBotnexio
EnglishDeutsch

Jetzt kaufen!

← Alle Ratgeber

KI-Agent erstellen mit TypeScript (ohne Framework, 2026)

English version

Ein KI-Agent ist eine Schleife: Gespräch und Tool-Liste an ein Modell schicken, das gewünschte Tool ausführen, das Ergebnis anhängen und das so lange wiederholen, bis das Modell ohne Tool-Aufruf antwortet. Dafür brauchst du kein Framework. Dieser Guide richtet sich an Entwickler und baut die Schleife in reinem TypeScript. Dazu kommen die Teile, die zählen, sobald Tools etwas verändern können: Limits, Prüfung der Argumente, Freigabe und Evals.

Schritt 1: Der Modellaufruf (jede OpenAI-kompatible API)

Viele Anbieter und lokale Laufzeiten (zum Beispiel Ollama) verstehen das Chat-Completions-Format von OpenAI. Eine kleine Funktion reicht:

type Msg = { role: "system" | "user" | "assistant" | "tool"; content: string | null; tool_calls?: any[]; tool_call_id?: string };

async function chat(messages: Msg[], tools: any[]) {
  const res = await fetch(`${process.env.LLM_BASE_URL}/chat/completions`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.LLM_API_KEY}` },
    body: JSON.stringify({ model: process.env.LLM_MODEL, messages, tools }),
  });
  if (!res.ok) throw new Error(`LLM-Fehler ${res.status}`);
  return (await res.json()).choices[0].message as Msg;
}

Nimm ein Modell, das Tool-Calling unterstützt. Die API-Kosten trägst du.

Schritt 2: Typisierte Tools mit zod

import { z } from "zod";

const tools = {
  get_weather: {
    description: "Aktuelles Wetter für eine Stadt",
    schema: z.object({ city: z.string().min(1) }),
    sideEffects: false,
    run: async ({ city }: { city: string }) => `Sonnig in ${city}`, // durch echten Aufruf ersetzen
  },
};

const toolSpecs = Object.entries(tools).map(([name, t]) => ({
  type: "function",
  function: { name, description: t.description, parameters: { type: "object", properties: { city: { type: "string" } }, required: ["city"] } },
}));

(Das JSON-Schema lässt sich mit einem Helfer aus dem zod-Schema erzeugen. Hier steht es von Hand da, damit das Beispiel kurz bleibt.)

Schritt 3: Die Schleife mit festen Limits

const MAX_STEPS = 8;
const MAX_TOOL_OUTPUT = 4_000; // Zeichen

async function runAgent(task: string) {
  const messages: Msg[] = [{ role: "system", content: "Du bist ein hilfreicher Agent." }, { role: "user", content: task }];
  for (let step = 0; step < MAX_STEPS; step++) {
    const reply = await chat(messages, toolSpecs);
    messages.push(reply);
    if (!reply.tool_calls?.length) return reply.content;

    for (const call of reply.tool_calls) {
      const tool = tools[call.function.name as keyof typeof tools];
      const parsed = tool?.schema.safeParse(JSON.parse(call.function.arguments || "{}"));
      let output: string;
      if (!tool) output = "Fehler: unbekanntes Tool";
      else if (!parsed!.success) output = `Fehler: ungültige Argumente ${parsed!.error.message}`;
      else if (tool.sideEffects && !(await askHuman(call.function.name, parsed!.data))) output = "Fehler: vom Nutzer abgelehnt";
      else output = String(await tool.run(parsed!.data));
      messages.push({ role: "tool", tool_call_id: call.id, content: output.slice(0, MAX_TOOL_OUTPUT) });
    }
  }
  throw new Error("Schrittlimit erreicht");
}

Drei Regeln tragen den größten Teil:

  • Limits stehen im Code, nicht im Prompt: maximale Schritte, ein Token-Budget, Timeouts und eine Obergrenze für Tool-Ausgaben. Ohne diese Obergrenze kann ein großes Ergebnis alles andere aus dem Kontext drängen.
  • Falsche Argumente gehen als Fehler an das Modell zurück, nicht ins Tool.
  • Aktionen mit Nebenwirkungen brauchen ein Ja von einem Menschen. askHuman kann eine CLI-Abfrage (readline) oder ein Button in deiner Oberfläche sein.

Schritt 4: Tools von MCP-Servern

Mit dem Model Context Protocol liegen Tools in eigenen Servern. Dein Agent ist dann ein MCP-Client (über stdio oder Streamable HTTP): Er liest die Tools des Servers, bildet sie auf dasselbe toolSpecs-Format ab und leitet die Aufrufe weiter. Tools von Servern, die du nicht als vertrauenswürdig markiert hast, behandelst du wie Nebenwirkungen und fragst immer vorher nach.

Schritt 5: Evals mit Mock-Modell

Ersetze chat() durch ein Mock, das vorgegebene Antworten liefert, etwa erst einen Tool-Aufruf und dann eine Antwort. So prüft die CI das Verhalten der Schleife ohne API-Kosten: Hält sie am Schrittlimit an? Lehnt sie falsche Argumente ab? Fragt sie vor Nebenwirkungen nach? Kürzt sie lange Tool-Ausgaben? Evals mit echten Modellen können getrennt laufen.

Schritt 6: Logging

Logge Schritte, Tool-Namen, Laufzeiten und Fehler. Prompts und Antworten bleiben standardmäßig draußen, damit du Logs teilen kannst, wenn etwas schiefgeht.

Aramac AI Agent Starter (TypeScript)

Der Aramac AI Agent Starter setzt diesen Ansatz als Vorlage um: rund 800 Zeilen lesbares TypeScript, ohne Framework. Laut Produktseite enthält er eine Agent-Schleife mit festen Limits (maximale Schritte, Token-Budget, Timeouts, maximale Tool-Ausgabe), Provider für jede OpenAI-kompatible API oder Ollama, typisierte Tools mit zod und einen MCP-Client (stdio und Streamable HTTP), der für das Aramac MCP Server Starter Kit ausgelegt ist. Vor jedem Tool mit Nebenwirkungen fragt er standardmäßig nach einer Freigabe. Dazu kommen Härtung gegen Prompt-Injection, Logs ohne Prompts und Antworten (Standard), ein Evals-Harness mit Mock-Modell (automatisierte Tests und Evals, vitest), CLI, Dockerfile, ein GitHub-Actions-Workflow und Doku auf DE/EN. Voraussetzungen: Node.js 22 (oder Docker). Eigenes Modell oder eigener API-Key nötig. Es sind keine Modelle enthalten, die API-Kosten trägst du. Preis: 39 € inkl. MwSt., verkauft von der Aramac GmbH. Lizenz: nur persönliche, nicht gewerbliche Nutzung (Lizenz). Nicht mit OpenAI, Ollama oder anderen genannten Anbietern verbunden.

FAQ

Brauche ich ein Framework, um einen KI-Agent in TypeScript zu bauen?
Nein. Der Kern ist eine Schleife um einen Modellaufruf und eine Tool-Liste. Frameworks bringen zusätzliche Abstraktionen mit. Die Schleife oben reicht, um anzufangen und zu verstehen, was passiert.

Welche Modelle funktionieren?
Jedes Modell hinter einer OpenAI-kompatiblen Chat-Completions-API, das Tool-Calling unterstützt, auch lokale Modelle über Ollama. Ob dein Anbieter Tool-Calling unterstützt, steht in seiner Doku.

Erinnert sich der Agent an frühere Gespräche?
In diesem Aufbau nicht. Der Agent hat Gesprächskontext pro Lauf. Alles darüber hinaus müsstest du selbst ergänzen.

Wie verhindere ich, dass ein Agent Schaden anrichtet?
Indem du begrenzt, was Tools dürfen, Argumente prüfst, für Nebenwirkungen eine Freigabe verlangst und die Schritte deckelst. KI-Ausgaben können falsch sein, deshalb bleiben Tool-Aktionen in deiner Verantwortung.

Ist der AI Agent Starter ein Abo?
Nein. 39 € inkl. MwSt., einmal bezahlt, Lieferung als ZIP. Kostenlose Updates bis 16.04.2027 laut Lizenz.

Weitere Guides

→ AI Agent Starter für 39 € holen

_Nicht mit OpenAI, Ollama, Anthropic oder anderen genannten Anbietern verbunden. Produktnamen sind Marken ihrer Inhaber._