Einen KI-Agenten zu bauen klingt komplex – und das kann es auch sein, wenn man alles von Grund auf selbst entwickeln will. Aber das Kernmuster ist einfach: Gib einem Sprachmodell Zugriff auf Werkzeuge, lass es entscheiden, welches Werkzeug es wann einsetzt, und wiederhole den Vorgang, bis das Ziel erreicht ist.
Diese Anleitung führt dich Schritt für Schritt durch den Bau eines KI-Agenten, von der Architektur bis zum funktionsfähigen Code. Am Ende hast du einen einsatzfähigen Agenten, der das Web durchsuchen, Bilder generieren und Ergebnisse liefern kann – alles über eine einzige CLI.
Was ist ein KI-Agent?
Bevor wir Code schreiben, sollten wir klären, was wir eigentlich bauen.
Ein KI-Agent ist ein System, das ein Ziel entgegennimmt, eine Abfolge von Aktionen plant, Werkzeuge zur Ausführung dieser Aktionen einsetzt, die Ergebnisse beobachtet und sich anpasst. Anders als ein Chatbot, der auf eine einzelne Eingabeaufforderung antwortet, arbeitet ein Agent autonom auf ein Ziel hin – potenziell über Dutzende von Werkzeugaufrufen hinweg.
Chatbot: "Fasse diesen Artikel zusammen." → Gibt eine Zusammenfassung zurück. KI-Agent: "Recherchiere dieses Thema, finde die besten Quellen, schreibe einen Bericht und veröffentliche ihn." → Plant, sucht, liest, schreibt, veröffentlicht.
Die Stärke des Agenten liegt in seinen Werkzeugen – den Fähigkeiten, die er aufrufen kann. Ohne Werkzeuge ist ein Agent nur ein Sprachmodell mit einem langen Prompt. Mit Werkzeugen kann er mit der Welt interagieren.
Die Architektur eines KI-Agenten
Jeder Agent folgt derselben grundlegenden Schleife:
┌─────────────────────────────────────────┐
│ AGENTEN-SCHLEIFE │
│ │
│ 1. Ziel empfangen │
│ 2. Denken: Was soll ich als Nächstes tun?│
│ 3. Handeln: Werkzeug auswählen und aufrufen│
│ 4. Beobachten: Was war das Ergebnis? │
│ 5. Entscheiden: Ist das Ziel erreicht? │
│ → Nein? Zurück zu Schritt 2. │
│ → Ja? Ergebnisse zurückgeben. │
└─────────────────────────────────────────┘
Dies wird als ReAct-Muster (Reasoning + Acting) bezeichnet. Jedes Agenten-Framework – LangChain, CrewAI, AutoGen, OpenAI Agents SDK – implementiert eine Version dieser Schleife.
Die drei benötigten Komponenten:
- Ein Sprachmodell – die Reasoning-Engine (Claude, GPT-4o, Gemini)
- Eine Reihe von Werkzeugen – was der Agent tun kann (suchen, crawlen, generieren, speichern, veröffentlichen)
- Ein Orchestrator – die Schleife, die entscheidet, welches Werkzeug als Nächstes aufgerufen wird
Schritt 1: Wähle deine Werkzeuge
Die Werkzeuge bestimmen, was dein Agent erreichen kann. Beginne mit der Frage: "Was muss mein Agent in der realen Welt tun?"
Gängige Agenten-Werkzeuge:
| Fähigkeit | Warum sie wichtig ist |
|---|---|
| Websuche | Recherche, Faktenfindung, Wettbewerbsanalyse |
| Web-Crawling | Tiefgehendes Lesen bestimmter Seiten, Datenextraktion |
| Bilderzeugung | Erstellen von Visuals, Diagrammen, Assets |
| Dateispeicherung | Persistente Ausgabe, Teilen, Asset-Management |
| Web-Publishing | Bereitstellung fertiger Arbeiten als Live-Seiten |
| Code-Ausführung | Skripte ausführen, Datenverarbeitung, Automatisierung |
Der häufigste Fehler von Anfängern: einem Agenten zu wenige Werkzeuge zu geben und sich dann zu wundern, warum er nichts zustande bringt. Ein reiner Such-Agent kann nur Links zurückgeben. Ein Agent mit Suche + Crawling + Speicherung + Publishing kann fertige, auslieferbare Ergebnisse produzieren.
Der einfachste Weg, Werkzeuge bereitzustellen: Verwende eine einheitliche Fähigkeitsschicht, die Suche, Crawling, Bilderzeugung, Speicherung und Publishing hinter einer Schnittstelle bündelt. Anstatt fünf separate APIs zu konfigurieren und fünf Sätze von Zugangsdaten zu verwalten, ruft dein Agent eine CLI mit einem Authentifizierungsablauf auf. Das hält die Agenten-Schleife einfach und den Token-Overhead niedrig.
Schritt 2: Definiere den System-Prompt deines Agenten
Der System-Prompt ist die "Bedienungsanleitung" des Agenten. Er sagt dem Modell, was es ist, welche Werkzeuge es hat und wie es sie einsetzen soll.
Ein guter System-Prompt hat vier Teile:
- Identität: Was der Agent ist
- Ziel: Was er erreichen soll
- Werkzeuge: Was er verwenden kann und wann
- Einschränkungen: Was er nicht tun soll
Beispiel:
Du bist ein Recherche-Agent. Dein Ziel ist es, ein gegebenes Thema
gründlich zu recherchieren und einen umfassenden Bericht zu erstellen.
Du hast Zugriff auf folgende Werkzeuge:
- search: Finde Informationen im Web. Für breite Recherchen.
- crawl: Lies eine bestimmte Webseite vollständig. Nachdem du
vielversprechende Quellen gefunden hast.
- drive upload: Speichere Berichte und Assets dauerhaft.
- page deploy: Veröffentliche den finalen Bericht als Webseite.
Arbeitsablauf:
1. Beginne mit breiten Suchanfragen, um die Landschaft zu verstehen.
2. Identifiziere die maßgeblichsten Quellen und crawle sie.
3. Fasse die Erkenntnisse in einem strukturierten Bericht zusammen.
4. Lade den Bericht zur sicheren Aufbewahrung in Drive hoch.
5. Stelle den Bericht als veröffentlichte Seite bereit.
Einschränkungen:
- Zitiere immer deine Quellen.
- Wenn eine Quelle einer anderen widerspricht, recherchiere weiter.
- Erfinde niemals Informationen.
Schritt 3: Implementiere die Agenten-Schleife
Hier ist eine minimale Agenten-Schleife in Python. Das Muster ist produktionsreif – denken, handeln, beobachten, wiederholen:
import subprocess
import json
def call_tool(tool_name, **params):
"""Führe ein Werkzeug aus und gib das Ergebnis zurück."""
if tool_name == "search":
result = subprocess.run(
["anycap", "search", "--prompt", params["query"]],
capture_output=True, text=True
)
return json.loads(result.stdout)
elif tool_name == "crawl":
result = subprocess.run(
["anycap", "crawl", params["url"]],
capture_output=True, text=True
)
return result.stdout
elif tool_name == "drive_upload":
subprocess.run(
["anycap", "drive", "upload", params["file"]],
capture_output=True
)
return {"status": "uploaded", "file": params["file"]}
elif tool_name == "page_deploy":
result = subprocess.run(
["anycap", "page", "deploy", params["file"]],
capture_output=True, text=True
)
return json.loads(result.stdout)
# Die Agenten-Schleife
def agent_loop(goal, tools, max_steps=20):
memory = [{"role": "system", "content": SYSTEM_PROMPT}]
memory.append({"role": "user", "content": goal})
for step in range(max_steps):
response = llm_call(memory, tools)
if response.get("done"):
return response["result"]
tool_name = response["tool"]
tool_params = response["params"]
result = call_tool(tool_name, **tool_params)
memory.append({"role": "assistant", "content": str(response)})
memory.append({"role": "tool", "content": str(result)})
return "Agent hat die maximale Anzahl an Schritten erreicht, ohne das Ziel abzuschließen."
Schritt 4: Fehlerbehandlung
Agenten scheitern. Die Frage ist, wie sie damit umgehen. Baue von Anfang an folgende Sicherheitsvorkehrungen ein:
Timeout-Schutz
Lass einen Agenten nicht ewig in der Schleife laufen. Setze eine maximale Anzahl von Schritten und ein Zeitlimit. Wenn der Agent eines von beiden überschreitet, sollte er das zurückgeben, was er bisher hat – und nicht stillschweigend abstürzen.
Wiederherstellung bei Werkzeugfehlern
Wenn ein Werkzeugaufruf fehlschlägt – eine URL ist nicht erreichbar, eine API gibt einen Fehler zurück – sollte der Agent die Fehlermeldung erhalten und entscheiden, was als Nächstes zu tun ist. Verstecke Fehler nicht vor dem Agenten. Er muss wissen, wenn etwas nicht funktioniert hat.
try:
result = call_tool(tool_name, **tool_params)
except Exception as e:
result = {"error": str(e), "suggestion": "Versuche einen alternativen Ansatz"}
Kostenbewusstsein
Jede Suche, jeder Crawl, jede Bilderzeugung kostet Credits. Gib dem Agenten ein Budget und mach ihm die Kosten bewusst. Ein Agent, der 100 Suchen durchführt, um eine einfache Frage zu beantworten, ist schlecht konzipiert.
Schritt 5: Der Unterschied zwischen Demo und Produktion
Der Unterschied zwischen einem Demo-Agenten und einem nützlichen Agenten ist echter Werkzeugzugriff. Ein Demo-Agent gibt Text zurück. Ein nützlicher Agent gibt einen veröffentlichten Bericht, ein generiertes Bild oder eine bereitgestellte Webseite zurück.
Produktionsagenten benötigen fünf Fähigkeiten: das Web durchsuchen, bestimmte Seiten lesen, Visuals generieren, Ausgaben dauerhaft speichern und fertige Arbeiten veröffentlichen. Der Code des Agenten bleibt einfach – er ruft nur die benötigten Werkzeuge auf. Die Komplexität von API-Integration, Authentifizierung und Fehlerbehandlung liegt in der Runtime, nicht in deiner Agenten-Schleife.
Häufige Fehler beim Bau von Agenten
Fehler 1: Keine Abbruchbedingung
Ein Agent ohne klares "Fertig"-Signal wird ewig weiterlaufen. Definiere Erfolg explizit: Der Agent ist fertig, wenn er eine bestimmte Ausgabe (einen Bericht, eine bereitgestellte Seite) produziert oder wenn er bestätigt, dass das Ziel unerreichbar ist.
Fehler 2: Zu wenige Werkzeuge
"Reine Suche"-Agenten sind glorifizierte Suchmaschinen. Gib deinem Agenten die vollständige Pipeline: Finden → Lesen → Erstellen → Speichern → Ausliefern.
Fehler 3: Ignorieren von Werkzeugergebnissen
Agenten rufen manchmal ein Werkzeug auf und ignorieren die Ausgabe, indem sie auf der Grundlage ihrer Annahmen über das Ergebnis weitermachen. Zwinge den Agenten, jedes Werkzeugergebnis in seine nächste Entscheidung einzubeziehen.
Fehler 4: Over-Engineering der Schleife
Für die meisten Anwendungsfälle brauchst du kein benutzerdefiniertes Orchestrierungs-Framework. Eine einfache ReAct-Schleife mit einem guten System-Prompt und leistungsfähigen Werkzeugen übertrifft ein komplexes Multi-Agenten-Setup bei 80 % der Aufgaben.
Vom Tutorial zur Produktion
Der hier gebaute Agent ist ein Ausgangspunkt. Um ihn produktionsreif zu machen:
- Logging hinzufügen: Zeichne jeden Werkzeugaufruf, sein Ergebnis und die Überlegungen des Agenten für das Debugging auf.
- Human-in-the-Loop hinzufügen: Für risikoreiche Aktionen (Veröffentlichen, E-Mails senden) muss eine menschliche Genehmigung eingeholt werden.
- Monitoring hinzufügen: Verfolge die Erfolgsquote, die durchschnittlichen Schritte pro Aufgabe und die Verteilung der Werkzeugaufrufe, um Engpässe zu identifizieren.
- System-Prompt iterieren: Der Prompt ist das Gehirn des Agenten. Optimiere ihn basierend auf realen Nutzungsmustern.
Einen KI-Agenten zu bauen, dreht sich nicht um komplexe Architektur. Es geht darum, einer Reasoning-Engine die richtigen Werkzeuge und ein klares Ziel zu geben. Fang einfach an: ein Modell, 3-5 Werkzeuge, eine grundlegende Schleife. Füge Komplexität nur dann hinzu, wenn die einfache Version an ihre Grenzen stößt.