Zum Hauptinhalt springen

Lokale KI-Agenten bauen

Experte

Ein lokaler KI-Agent ist eine autonome Schleife, die vollständig auf Ihrer eigenen Hardware läuft: Ein Open-Weight-Modell (bereitgestellt von Ollama oder LM Studio) entscheidet, was zu tun ist, ruft die Tools auf, die Sie ihm geben, liest die Ergebnisse und macht weiter, bis die Aufgabe erledigt ist — wobei nichts Ihren Rechner verlässt. Keine Cloud-API, keine Kosten pro Aufruf, kein Internet erforderlich. Der Haken: Ein Modell, das klein genug ist, um auf einem Laptop zu laufen, ist bei schwierigem Reasoning und langfristiger Planung schwächer als ein Frontier-Modell, und Sie sind für seine Zuverlässigkeit und Sicherheit verantwortlich. Diese Seite behandelt die ehrliche Begründung für lokale Agenten, die minimale Architektur, was tatsächlich lokal läuft und einen realistischen Weg zu Ihrem ersten Agenten.

What you'll learn
  • Wissen, WARUM Sie einen Agenten bauen würden, der lokal läuft — und die ehrlichen Kompromisse gegenüber einem Cloud-API-Agenten
  • Die minimale Architektur verstehen: lokales Modell + Tool-Calling-Schleife + Tools + ein Schutzmechanismus/eine Abbruchbedingung
  • Ein lokales Modell wählen, das tatsächlich Tool-Nutzung / agentische Arbeit leisten kann
  • Wissen, welche Agenten-Frameworks lokal laufen, indem man sie auf einen lokalen Endpunkt zeigen lässt (LangGraph, CrewAI, OpenAI Agents SDK)
  • Einem 'simpel anfangen'-Pfad von einem einmaligen Tool-Aufruf bis zu einer abgesicherten Schleife folgen
  • Den Agenten in eine Sandbox stecken und mit einem Budget-Limit versehen, damit eine autonome Schleife keinen echten Schaden anrichten kann

Warum einen lokalen Agenten bauen (und wann nicht)​

Ein gewöhnlicher Tool-Use-Agent ruft ein Cloud-Modell auf. Ein lokaler Agent tauscht diesen Cloud-Aufruf gegen ein Modell aus, das auf Ihrem eigenen Rechner läuft. Sie geben etwas Leistungsfähigkeit auf und übernehmen einen gewissen Betriebsaufwand; im Gegenzug erhalten Sie vier Dinge, die auf anderem Wege schwer zu bekommen sind:

  • Privatsphäre — Prompts, Tool-Eingaben und Tool-Ausgaben verlassen niemals den Rechner. Das ist der einzige Grund, warum Teams in regulierten, sensiblen oder vom Netz getrennten (air-gapped) Umgebungen lokale Agenten bauen: Die Daten können physisch nicht zu einem Dritten gelangen.
  • Offline — kein Internet, keine API-Abhängigkeit, kein Ausfall des Anbieters. Der Agent besteht aus Dateien auf Ihrer Festplatte; er läuft im Flugzeug oder hinter einer Firewall.
  • Keine Kosten pro Aufruf — eine Agenten-Schleife kann pro Aufgabe Dutzende Modellaufrufe auslösen. Lokal sind diese Aufrufe „kostenlos“ (Sie zahlen mit Strom und Hardware, nicht mit Tokens), sodass Sie ihn iterieren lassen können, ohne auf einen Zähler zu schauen.
  • Volle Kontrolle — eine exakte Modellversion festnageln, das Verhalten anpassen und ohne Ratenbegrenzungen oder Überraschungen in den Nutzungsbedingungen laufen lassen.

Die ehrlichen Kompromisse — seien Sie sich darüber im Klaren, bevor Sie sich festlegen:

  • Leistungslücke. Der schwierigste Teil eines Agenten ist das Reasoning: mehrstufige Arbeit planen, sich von einem fehlgeschlagenen Tool-Aufruf erholen, wissen, wann man aufhören soll. Ein Modell, das Sie auf einem Laptop laufen lassen können (etwa 1B–14B Parameter), ist hier deutlich schwächer als ein Frontier-Modell. Einfache, gut abgegrenzte Schleifen funktionieren lokal gut; langfristige, offene Aufgaben sind der Punkt, an dem lokale Agenten am häufigsten entgleisen.
  • Sie sind für Zuverlässigkeit und Sicherheit verantwortlich. Kein Anbieter filtert, überwacht oder sichert für Sie ab. Wenn der Agent endlos in einer Schleife hängt, das falsche Tool aufruft oder eine destruktive Aktion ausführt, liegt das an Ihrem Design. (Siehe die Warnung unten — diesen Teil unterschätzen die Leute.)
  • Hardware-Grenzen. Größere, intelligentere Modelle benötigen mehr RAM/VRAM, als die meisten Rechner haben. Sie wählen normalerweise das größte leistungsfähige Modell, das Ihre Hardware betreiben kann, nicht das beste existierende Modell.

Eine dauerhafte Faustregel: lokal anfangen, eskalieren, wenn die Aufgabe es erfordert. Verwenden Sie einen lokalen Agenten für private/offline/im großen Maßstab günstige Arbeit und gut abgegrenzte Schleifen; greifen Sie zu einem Frontier-API-Agenten, wenn die Aufgabe wirklich das zusätzliche Reasoning benötigt. Die Architektur unten ist in beiden Fällen identisch — nur der Endpunkt ändert sich — sodass Sie lokal prototypisieren und Modelle später austauschen können.

Die minimale Architektur​

Reduziert man einen Agenten auf seinen Kern, gibt es vier Teile. Alles andere ist Komfort obendrauf.

        ┌─────────────────────────────────────────────┐
        │                                             │
        │   1. LOCAL MODEL  ──►  decides next action  │
        │      (Ollama / LM Studio, tool-capable)     │
        │                  │                          │
        │                  ▼                          │
        │   2. TOOL-CALLING LOOP                       │
        │      parse the model's tool request,         │
        │      run it, feed the result back            │
        │                  │                          │
        │                  ▼                          │
        │   3. TOOLS  ──►  search / read file /        │
        │      run code / call an API (your code)      │
        │                  │                          │
        │                  ▼                          │
        │   4. GUARDRAIL / STOP CONDITION              │
        │      max steps, budget, approval gate,       │
        │      "done" check ──► exit the loop          │
        │                                             │
        └─────────────────────────────────────────────┘
  1. Ein lokales Modell, das Tool-Calling unterstützt. Das Modell muss in der Lage sein, eine strukturierte Anfrage zum Aufruf eines Tools auszugeben (auch Function Calling genannt), nicht nur zu chatten. Ollama stellt dies über seine API und über einen OpenAI-kompatiblen Endpunkt unter http://localhost:11434/v1 bereit, sodass jedes Framework, das das OpenAI-Format spricht, ein lokales Modell steuern kann.
  2. Die Tool-Calling-Schleife. Das Herzstück des Agenten: Senden Sie die Konversation an das Modell, prüfen Sie, ob es den Aufruf eines Tools angefordert hat, führen Sie dieses Tool aus, hängen Sie das Ergebnis an und wiederholen Sie. Wenn das Modell antwortet, ohne ein Tool anzufordern, endet die Schleife.
  3. Tools. Einfache Funktionen, die Sie dem Modell zur Verfügung stellen — das Web durchsuchen, eine Datei lesen, einen Shell-Befehl ausführen, eine Datenbank abfragen, eine API aufrufen. Jedes Tool hat einen Namen, eine Beschreibung und ein typisiertes Eingabeschema, damit das Modell weiß, wann und wie es es verwenden soll.
  4. Ein Schutzmechanismus / eine Abbruchbedingung. Unverhandelbar für Autonomie. Mindestens ein Maximalschritt-Limit, damit die Schleife nicht ewig laufen kann, plus — für alles, was schreibt, löscht, ausgibt oder versendet — ein Genehmigungs-Gate oder eine Sandbox. Ohne dies haben Sie keinen Agenten, sondern eine Endlosschleife mit Dateizugriff.

Die Schleife in Schritt 2 ist wirklich klein. Hier ist sie in Python-Pseudocode gegen einen lokalen Ollama-Endpunkt:

Eine minimale lokale Agenten-Schleife (Python-Pseudocode, zeigt auf lokales Ollama)

from openai import OpenAI

# Point the OpenAI client at your LOCAL Ollama endpoint — nothing leaves the machine
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

tools = [{
  "type": "function",
  "function": {
      "name": "read_file",
      "description": "Read a UTF-8 text file and return its contents",
      "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"],
      },
  },
}]

def run_tool(name, args):
  if name == "read_file":
      # GUARDRAIL: only allow reads inside a sandboxed directory
      return safe_read(args["path"])
  raise ValueError(f"unknown tool: {name}")

messages = [{"role": "user", "content": "Summarize ./notes/today.md"}]

for step in range(8):                       # GUARDRAIL: hard step cap
  resp = client.chat.completions.create(
      model="llama3.1", messages=messages, tools=tools,
  )
  msg = resp.choices[0].message
  messages.append(msg)

  if not msg.tool_calls:                  # STOP: model answered, we're done
      print(msg.content)
      break

  for call in msg.tool_calls:
      result = run_tool(call.function.name, json.loads(call.function.arguments))
      messages.append({
          "role": "tool", "tool_call_id": call.id, "content": str(result),
      })
else:
  print("Stopped: hit the step cap without finishing.")

Das ist das gesamte Muster. Frameworks fügen Speicher, Wiederholungsversuche, Multi-Agenten-Orchestrierung, Tracing und strukturierten Zustand obendrauf — aber jedes von ihnen ist eine robustere Version dieser Schleife.

Welche lokalen Modelle für agentische / Tool-Use-Arbeit geeignet sind​

Nicht jedes Open-Weight-Modell kann einen Agenten steuern. Die Messlatte ist zuverlässiges Tool-Calling: Das Modell muss konsistent wohlgeformte Tool-Anfragen ausgeben, das richtige Tool auswählen und keine Argumente halluzinieren. Zwei Filter bei der Auswahl:

  • Es muss ein Tool-fähiges Modell sein. Ollama kennzeichnet diese — durchsuchen Sie die Tools-Kategorie für die aktuelle Liste, anstatt etwas anzunehmen. Zu den häufig für solides lokales Tool-Use genannten Modellen gehören die instruction-getunten Familien Qwen und Llama; die genaue beste Wahl verschiebt sich von Quartal zu Quartal.
  • Es muss mit Spielraum für Kontext auf Ihre Hardware passen. Agenten-Schleifen sammeln lange Nachrichtenverläufe an (jedes Tool-Ergebnis wird angehängt), sodass Sie sowohl die Gewichte als auch ein großzügiges Kontextfenster im Speicher benötigen. Ein kleineres Modell, das bequem passt und schnell läuft, schlägt oft ein größeres, das auf die Festplatte auslagert und mitten in der Schleife stehen bleibt.

Der entscheidende Schritt ist nicht das Lesen von Benchmarks — es ist das Durchführen einer kleinen Eval Ihrer Aufgabe gegen zwei oder drei Kandidatenmodelle. Ein Modell, das eine Bestenliste anführt, kann bei den spezifischen Tools, die Ihr Agent benötigt, dennoch unzuverlässig sein. Messen Sie auf Ihrer eigenen Schleife.

Frameworks, die lokal laufen​

Sie können die obige Schleife von Hand bauen, und für einen ersten Agenten ist das eine großartige Art zu lernen. Für alles Echte gibt Ihnen ein Framework Wiederholungsversuche, Speicher, Multi-Agenten-Koordination und Tracing. Die zentrale Tatsache: Die beliebten Agenten-Frameworks sind modellagnostisch — es ist ihnen egal, ob das Modell in der Cloud oder auf localhost ist, solange Sie sie auf den richtigen Endpunkt zeigen lassen.

  • LangGraph — ein Low-Level-Orchestrierungs-Framework für zustandsbehaftete Agenten (dauerhafte Ausführung, Persistenz, Human-in-the-Loop). Modellagnostisch; verdrahten Sie es ohne Umwege über die LangChain-Ollama-Integration mit einem lokalen Modell. Gut, wenn Sie explizite Kontrolle über den Zustandsgraphen des Agenten benötigen.
  • CrewAI — ein höher angesiedeltes Framework zur Orchestrierung eines oder mehrerer rollenbasierter Agenten („Crews“). Modellagnostisch über LiteLLM; zeigen Sie einen Agenten mit LLM(model="ollama/llama3.1", base_url="http://localhost:11434") auf ein lokales Modell. Gut, wenn Sie schnell mehrere kooperierende Agenten zusammenstellen wollen.
  • OpenAI Agents SDK — ein leichtgewichtiges Multi-Agenten-Framework. Trotz des Namens ist es anbieteragnostisch: über seine LiteLLM-Integration können Sie es auf ein lokales Ollama-Modell statt auf ein OpenAI-Modell zeigen lassen. Gut, wenn Sie OpenAIs Agenten-Ergonomie auf einem lokalen Backend wollen.

Wählen Sie ein Framework und lernen Sie es gut, anstatt alle drei anzutesten. Die Konzepte (Agenten, Tools, Schleifen, Zustand) übertragen sich; die APIs sind Details.

Bauen Sie Ihren ersten lokalen Agenten​

Ein realistischer Weg geht in bewussten Schritten von „gar keine Schleife“ zu „abgesicherte autonome Schleife“. Überspringen Sie nicht zu Schritt 4 — die meisten Fehler, auf die Leute bei lokalen Agenten stoßen, kommen daher, dass sie einem schwachen Modell zu früh zu viel Spielraum geben.

Guided walkthrough1 of 5
  1. Installieren Sie Ollama (siehe Modelle lokal ausführen), ziehen Sie dann ein für Tools gekennzeichnetes Modell, z. B. ollama pull llama3.1. Bestätigen Sie, dass es auf http://localhost:11434 bereitsteht und dass ollama list es anzeigt. Noch kein Agent — nur ein Modell, das Sie aufrufen können.
Watch out
  • Ein lokaler Agent mit Tools kann trotzdem echte Aktionen ausführen — stecken Sie ihn in eine Sandbox, verlangen Sie Genehmigung für destruktive Schritte und begrenzen Sie seine Schleifen/sein Budget.

Überprüfen Sie sich selbst​

Überprüfen Sie sich selbst

0/4
  1. Was ist der einzelne wichtigste Grund, warum Teams Agenten bauen, die lokal statt gegen eine Cloud-API laufen?
  2. Welche vier Teile bilden die minimale Architektur eines lokalen Agenten?
  3. Was bedeutet es, dass LangGraph, CrewAI und das OpenAI Agents SDK für den lokalen Einsatz 'modellagnostisch' sind?
  4. Sie bauen Ihren ersten lokalen Agenten. Was sollten Sie tun, BEVOR Sie ein Tool hinzufügen, das Dateien schreibt oder Befehle ausführt?
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 6
Key takeaways
  • Ein lokaler Agent ist die übliche Tool-Use-Schleife, bei der das Cloud-Modell gegen ein Open-Weight-Modell auf Ihrem Rechner getauscht wird — privat, offline und kostenlos zu iterieren.
  • Minimale Architektur = lokales Tool-fähiges Modell + Tool-Calling-Schleife + Tools + ein Schutzmechanismus/eine Abbruchbedingung. Die Schleife selbst ist winzig.
  • Ollamas OpenAI-kompatibler Endpunkt (/v1) unterstützt Tool-Calling, sodass jedes Framework im OpenAI-Format ein lokales Modell steuern kann.
  • LangGraph, CrewAI und das OpenAI Agents SDK sind modellagnostisch — zeigen Sie sie auf einen lokalen Endpunkt statt auf die Cloud.
  • Wählen Sie ein Tool-fähiges Modell, das auf Ihre Hardware passt, und entscheiden Sie dann mit einer kleinen Eval Ihrer eigenen Aufgabe — nicht mit einer Bestenliste.
  • Seien Sie ehrlich über die Leistungslücke und übernehmen Sie die Verantwortung für die Sicherheit: Begrenzen Sie Schleifen und Budget, stecken Sie Tools in eine Sandbox und verlangen Sie Genehmigung für alles Destruktive.
  • Simpel anfangen: ein sauberer Tool-Aufruf → begrenzte nur-lesende Schleife → abgesicherte destruktive Tools → (optional) ein Framework.

Quellen & weiterführende Literatur​