Dein erster KI-Agent mit der Claude API — Schritt für Schritt

TL;DR — Was du nach diesem Artikel hast

• Einen lauffähigen KI-Agent in TypeScript, der Web-Search-Tools nutzen kann.
• Verständnis vom Agent-Loop: Plan → Tool-Call → Resultat → Re-Plan.
• Kompletten Code zum Kopieren, getestet auf Node 22+.
• Konkrete API-Kosten (~0,03 € pro Lauf bei Sonnet 4.6).
• Wissen, wie du eigene Tools dranhängst — Datei-System, Datenbank, eigene APIs.

Video

#7 KI-Agent ohne Framework: nur Python und Claude API

Einen eigenen KI-Agent zu bauen ist 2026 deutlich einfacher als die meisten denken. Wer JavaScript oder TypeScript kann, hat in unter 60 Minuten ein funktionierendes Setup, das echte Aufgaben erledigt. Dieses Tutorial zeigt den vollständigen Pfad — von API-Key bis zu einem Agent, der das Web durchsucht und strukturierte Antworten liefert.

Was du nicht brauchst: ein KI-Studium, eine Fancy-Cloud-Setup oder mehrere Tausend Euro Hardware. Was du brauchst: einen Anthropic API-Key, Node 22+, und 60 Minuten.

Was ist überhaupt ein KI-Agent?

Bevor wir Code schreiben, kurz die Theorie. Ein KI-Agent ist ein Sprachmodell mit zwei Erweiterungen gegenüber einem Chatbot:

1. Tool-Use: Der Agent kann externe Funktionen aufrufen — Web-Suche, Datei lesen, Datenbank-Query, API-Call.
2. Agent-Loop: Statt einer einzelnen Antwort führt der Agent eine Schleife aus: Plan → Tool aufrufen → Resultat lesen → erneut planen, bis die Aufgabe gelöst ist.

Was du in diesem Tutorial baust: einen Agent mit einem Web-Search-Tool. Frage: “Was ist die aktuelle Inflation in Deutschland?” Der Agent erkennt, dass er das nicht weiß, ruft die Web-Suche auf, liest die Ergebnisse, formuliert eine fundierte Antwort mit Quellenangabe.

Schritt 1: API-Key einrichten

Geh auf console.anthropic.com und erstelle einen Account. Unter API Keys klickst du Create Key. Den Key kopierst du in eine .env-Datei in deinem Projektordner:

ANTHROPIC_API_KEY=sk-ant-...

Wichtig: Diese Datei darf niemals ins Git-Repo committed werden. Füge .env zu deiner .gitignore hinzu, bevor du irgendetwas committest. Wer einen API-Key öffentlich macht, riskiert binnen Stunden eine fünfstellige Cloud-Rechnung.

Für die ersten Tests reicht der Free-Tier (5 USD Credits). Für Production solltest du Auto-Recharge aktivieren mit einem moderaten Limit (z.B. 50 USD/Monat).

Schritt 2: Node-Projekt initialisieren

In deinem Projektordner:

npm init -y
npm install @anthropic-ai/sdk dotenv
npm install -D typescript @types/node tsx

Erstelle eine tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "dist"
  }
}

In deiner package.json setzt du "type": "module", damit ESM funktioniert. Erstelle eine Datei src/agent.ts — das ist unser Hauptscript.

Schritt 3: Erster LLM-Call ohne Tools

Bevor wir Tools dranhängen, testen wir die API-Anbindung. In src/agent.ts:

import Anthropic from "@anthropic-ai/sdk";
import "dotenv/config";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function main() {
  const response = await client.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "Sag in einem Satz, was du gerade tust." },
    ],
  });
  console.log(response.content[0]);
}

main();

Starten mit:

npx tsx src/agent.ts

Wenn alles klappt, siehst du eine Antwort wie “Ich beantworte gerade deine Frage.” — das beweist, dass der API-Key korrekt ist und du Tokens verbrauchen kannst.

Was hier passiert: Wir nutzen claude-haiku-4-5 als günstigstes Modell für Tests. Dieser Call kostet ungefähr 0,0001 €. Wenn du den selben Test 10.000-mal startest, kostet es einen Euro.

Schritt 4: Tool definieren

Jetzt geben wir dem Agent ein Werkzeug. Wir bauen ein einfaches Web-Search-Tool, das eine Suchanfrage macht und die Top-3-Resultate zurückgibt.

Für echte Web-Suchen brauchst du eine Search-API. Die einfachsten Optionen 2026: Brave Search API (kostenlos bis 2.000 Queries/Monat) oder SerpAPI (kostenpflichtig, aber sehr robust). Wir nehmen Brave als Beispiel — registriere dich auf api.search.brave.com für einen Key.

Tool-Definition für Claude:

const webSearchTool = {
  name: "web_search",
  description: "Sucht im Web nach aktuellen Informationen. Nutze dieses Tool, wenn du Fakten brauchst, die du nicht weißt oder die nach 2025 liegen.",
  input_schema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Die Suchanfrage in natürlicher Sprache.",
      },
    },
    required: ["query"],
  },
};

Und die zugehörige Funktion:

async function executeWebSearch(query: string): Promise<string> {
  const url = new URL("https://api.search.brave.com/res/v1/web/search");
  url.searchParams.set("q", query);
  url.searchParams.set("count", "3");

  const response = await fetch(url, {
    headers: {
      "X-Subscription-Token": process.env.BRAVE_API_KEY!,
      "Accept": "application/json",
    },
  });

  const data = await response.json();
  const results = data.web?.results ?? [];

  return results
    .map((r: any, i: number) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.description}`)
    .join("\n\n");
}

Der Agent ruft web_search auf, du übersetzt das in einen echten HTTP-Call, gibst das Resultat strukturiert zurück. Das ist die Brücke zwischen LLM und realer Welt.

Schritt 5: Agent-Loop bauen

Jetzt der Kern: die Schleife, die den Agent zum Agent macht.

async function runAgent(userQuestion: string): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userQuestion },
  ];

  // Maximal 5 Iterationen, um Endlos-Loops zu verhindern
  for (let i = 0; i < 5; i++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-6",
      max_tokens: 4096,
      tools: [webSearchTool],
      messages,
    });

    // Tool-Calls extrahieren
    const toolUseBlocks = response.content.filter(
      (block) => block.type === "tool_use"
    ) as Anthropic.ToolUseBlock[];

    if (toolUseBlocks.length === 0) {
      // Keine Tool-Calls mehr — finale Antwort
      const textBlock = response.content.find((b) => b.type === "text");
      return (textBlock as Anthropic.TextBlock)?.text ?? "(keine Antwort)";
    }

    // Assistant-Nachricht im Verlauf speichern
    messages.push({ role: "assistant", content: response.content });

    // Jeden Tool-Call ausführen und Resultat zurückschicken
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    for (const toolUse of toolUseBlocks) {
      let result: string;
      if (toolUse.name === "web_search") {
        const query = (toolUse.input as { query: string }).query;
        console.log(`[agent] web_search: ${query}`);
        result = await executeWebSearch(query);
      } else {
        result = `Unknown tool: ${toolUse.name}`;
      }
      toolResults.push({
        type: "tool_result",
        tool_use_id: toolUse.id,
        content: result,
      });
    }

    messages.push({ role: "user", content: toolResults });
  }

  return "(Maximale Iterationen erreicht)";
}

// Hauptaufruf
async function main() {
  const answer = await runAgent(
    "Was ist die aktuelle Inflationsrate in Deutschland? Bitte mit Quelle."
  );
  console.log("\n=== ANTWORT ===\n");
  console.log(answer);
}

main();

Was hier passiert, Schritt für Schritt:

1. Du stellst die Frage. Claude bekommt sie + die Tool-Definition.
2. Claude entscheidet: “Inflation 2026 weiß ich nicht aktuell, ich rufe web_search auf”. Das ist ein Tool-Use-Block in der Response.
3. Du extrahierst den Tool-Call, machst die echte Brave-Search-Anfrage.
4. Du gibst das Resultat als Tool-Result-Block zurück, zusammen mit dem bisherigen Verlauf.
5. Claude liest das Resultat und formuliert eine Antwort. Falls er weitere Recherche braucht, ruft er erneut web_search auf — die Schleife läuft weiter.
6. Sobald keine Tool-Calls mehr kommen, hast du die finale Antwort.

Das ist der Agent-Loop. Sobald du das einmal verstanden hast, kannst du jeden beliebigen Agent bauen — Datei-System-Agents, Datenbank-Agents, ganze Multi-Agent-Pipelines.

Schritt 6: Testen und Token-Verbrauch prüfen

Starte den Agent:

npx tsx src/agent.ts

Du solltest einen Output wie diesen sehen:

[agent] web_search: aktuelle Inflationsrate Deutschland 2026

=== ANTWORT ===

Die aktuelle Inflationsrate in Deutschland liegt im April 2026 bei
2,3 % (Verbraucherpreisindex, Vorjahresvergleich). Quelle: Statistisches
Bundesamt, Pressemitteilung vom 30. April 2026.

Im Anthropic-Dashboard siehst du den Token-Verbrauch — typischerweise 1.500–3.000 Input-Tokens und ~500 Output-Tokens für so einen Lauf. Mit Sonnet 4.6 sind das etwa 0,03 € pro Aufruf.

Was du jetzt erweitern kannst

Mit diesem Grundgerüst sind folgende Erweiterungen trivial:

• Datei-System-Tool: Tool, das eine Datei liest oder schreibt. Damit kann dein Agent Notion-Markdown-Files durchsuchen, Berichte schreiben, Code-Files modifizieren.
• Datenbank-Tool: SQL-Query-Tool gegen deine Postgres oder SQLite. Vorsicht: read-only erstmal, Write-Operations sind explizit risikoreich.
• API-Tool: Custom-Tool für deine eigene API. Dein Agent kann z.B. Stripe-Subscriptions abfragen, Notion-Pages aktualisieren, Slack-Nachrichten senden.

Statt jedes Mal eigenen Glue-Code zu schreiben, kannst du auch MCP-Server einsetzen — das ist der Standard für Tool-Anbindung 2026. Das Tutorial dazu findest du unter MCP-Server bauen.

Fortgeschritten: Multi-Agent-Setups

Sobald du einen Agent verstanden hast, kannst du mehrere zu einem Team zusammenstellen. Ein klassischer Aufbau:

• Planner-Agent: Zerlegt die Aufgabe in Teilschritte.
• Researcher-Agent: Sammelt Daten via Web-Search-Tool.
• Writer-Agent: Formuliert den Output.
• Reviewer-Agent: Prüft auf Halluzinationen und Style-Issues.

In Code: jeder Agent ist eine runAgent()-Funktion mit eigenem System-Prompt und eigenen Tools. Der Output von Agent A wird zum Input von Agent B. Wenn du das visuell siehst — auf der christianohle-Startseite gibt’s eine animierte Multi-Agent-Visualisierung, die genau das zeigt.

Häufige Stolpersteine

Drei Sachen, an denen ich beim ersten Bauen hängengeblieben bin:

1. max_tokens zu niedrig. Wenn das Modell mitten im Tool-Call abbricht, wird’s hässlich. Setz mindestens 4.096 für Sonnet, mehr für komplexe Aufgaben.
2. Tool-Result-Format. Das content im tool_result muss ein String sein. Wenn du JSON zurückgibst, übergib es als JSON.stringify(...).
3. Kostenexplosion bei Endlos-Loops. Begrenze die Iterationen (im Beispiel 5). Ein Agent, der unkontrolliert weiterlüpft, verbrennt in einer Stunde 50 €.

Wie geht’s weiter?

Wenn dieser Agent läuft, hast du die Grundlage für 80 % aller produktiven Agent-Use-Cases. Nächste Schritte:

1. Tools erweitern: Datei-System, eigene API. Mehr Werkzeuge = mehr Use-Cases.
2. MCP lernen: Standardisierte Tool-Anbindung statt jedes Mal Glue-Code. Siehe MCP-Server bauen.
3. Use-Cases identifizieren: Welche repetitiven Aufgaben in deinem Alltag könnte dieser Agent abnehmen? Inspiration in den 10 Agent-Use-Cases im Solo-Business.
4. Lokal hosten: Wer DSGVO-sensible Daten hat, kann das ganze Setup statt mit Claude API auch mit einem lokalen LLM via Ollama bauen — dieselbe Tool-Use-Logik, ohne dass Daten den Rechner verlassen.

Agents sind 2026 die mit Abstand interessanteste Kategorie der KI-Tool-Landschaft. Wer den Agent-Loop einmal verstanden hat, sieht sie überall — und kann eigene bauen, wo bisher Frustration war.

Meine Einschätzung

Ich habe in den letzten Monaten dutzende Solo-Selbstständige beim Bau ihres ersten Agents begleitet, und das Muster ist immer gleich: Der Agent-Loop ist in 60 Minuten verstanden, aber die wirkliche Arbeit beginnt danach — beim Definieren sauberer Tool-Beschreibungen und beim Begrenzen der Iterations. Was ich jedem rate: Bau nicht gleich den perfekten Agent, sondern einen, der eine einzige Aufgabe zuverlässig erledigt. In meiner eigenen Pipeline war der erste Agent ein simpler Web-Scraper mit einem Tool. Heute sind es 15 Agents — aber jeder einzelne hat als Minimal-Version angefangen. Wer zu früh zu komplex baut, debuggt statt zu liefern.

Quellen

• [Anthropic API Documentation — Tool Use](h