Einen lokalen KI-Agenten erstellen: Architektur und empfohlene Werkzeuge

#Warum einen lokalen KI-Agenten bauen?

Ein lokaler KI-Agent deckt drei Bedürfnisse ab, denen die Cloud nur schlecht gerecht wird. Erstens die Vertraulichkeit: Wenn ein Agent Ihre E-Mails liest, Ihre Datenbank abfragt oder Ihre Dateien durchsucht, birgt jeder Aufruf einer externen API das Risiko eines Datenlecks. Bei lokaler Ausführung verlässt der Kontext die Maschine nie. Zweitens die Kosten: Ein Agent führt für eine einzige Aufgabe Dutzende Modellaufrufe nacheinander aus, und die Rechnung für eine nutzungsabhängig abgerechnete API steigt schnell drastisch an. Drittens die Unabhängigkeit: keine Begrenzung der Aufrufrate, keine Netzwerkunterbrechungen, keine Änderungen der Preispolitik von heute auf morgen.

Der Preis dafür ist spürbar: Ein lokales Modell mit 14B oder 32B Parametern kann nicht so differenziert schlussfolgern wie die besten proprietären Modelle. Die Gestaltung des Agenten — klar abgegrenzte Tools, strikte Prompts, Schutzmechanismen — ist daher wichtiger als in der Cloud. Genau darum geht es in diesem Leitfaden zum lokalen KI-Agenten.

#Anatomie eines Agenten

Unabhängig davon, welches Framework verwendet wird, basiert ein lokaler KI-Agent stets auf denselben Bausteinen. Wer sie versteht, kann seine Werkzeuge fundiert auswählen, statt blind einem Tutorial zu folgen.

Das Modell (Reasoning)

Das LLM, das über die nächste Aktion entscheidet. Es muss Tool-Calling zuverlässig beherrschen: Qwen 3.x, Granite 4.x oder Mistral Small sind gute Kandidaten für den lokalen Einsatz.

Die Werkzeuge (Aktionen)

Python-Funktionen, die der Agent aufrufen kann: eine Datei lesen, eine API abfragen, eine Suche durchführen, in eine Datenbank schreiben. Jedes Tool wird durch ein JSON-Schema beschrieben, das das Modell liest.

Das Gedächtnis (Zustand)

Kurzfristig (der Verlauf des laufenden Gesprächs) und langfristig (ein Vektorspeicher, der über Sitzungen hinweg erhalten bleibt). Dafür ist RAG zuständig, das weiter unten ausführlich beschrieben wird.

Der Orchestrator (Schleife)

Der Code, der Schlussfolgern, Tool-Aufruf und Beobachtung so lange nacheinander ausführt, bis die Abbruchbedingung erfüllt ist. Genau das stellt ein Framework wie CrewAI oder AutoGen bereit.

Der Planer (Strategie)

Die Logik, die ein komplexes Ziel in geordnete Teilaufgaben zerlegt. Die Planung kann explizit erfolgen (durch einen eigens dafür vorgesehenen Planungsagenten) oder implizit (das Modell denkt Schritt für Schritt).

Ein minimaler Agent kommt mit einem Modell, zwei oder drei Werkzeugen und einer Schleife aus. Ein fortgeschrittenes System ergänzt dies um ein persistentes Gedächtnis, mehrstufige Planung und mehrere spezialisierte Agenten, die zusammenarbeiten. Beginnen Sie einfach: Die meisten Aufgaben rechtfertigen kein Team aus zehn Agenten.

#Voraussetzungen und empfohlener Stack

Der Referenz-Stack für einen lokalen KI-Agenten besteht aus drei Schichten: Ollama zur Bereitstellung des Modells, einem Orchestrierungsframework in Python und einem Modell, das Tool-Aufrufe unterstützt. Ollama lauscht standardmäßig auf http://localhost:11434 und stellt einen OpenAI-kompatiblen Endpunkt bereit, was die Integration mit den meisten Frameworks vereinfacht.

GPU / VRAM

Ein Agent kann mit einem Modell mit 14B oder mehr besser schlussfolgern als mit einem 7B-Modell. Rechnen Sie mit etwa 9 GB VRAM für ein 14B-Modell in Q4_K_M und etwa 19 GB für ein 32B-Modell. Eine RTX 4070 mit 12 GB betreibt ein 14B-Modell problemlos; eine RTX 4090 mit 24 GB oder ein Mac M4 Pro sind auf ein 32B-Modell ausgelegt.

Modell

Wählen Sie ein Modell, das für zuverlässiges Tool-Calling bekannt ist. Die Qualität des Function-Callings zählt mehr als die reine Modellgröße: Ein sorgfältiges 14B-Modell schlägt ein 32B-Modell, das Argumente erfindet.

Python 3.10+

CrewAI und AutoGen sind Python-Bibliotheken. Arbeiten Sie in einer dedizierten virtuellen Umgebung, um Abhängigkeitskonflikte zu vermeiden.

Quantization

Q4_K_M ist als Standardeinstellung ein guter Kompromiss. Wechseln Sie zu Q5_K_M oder Q8_0, wenn das Modell Denkfehler macht und der verfügbare VRAM dies zulässt.

# 1. Vérifier qu'Ollama tourne
curl http://localhost:11434/api/tags

# 2. Récupérer un modèle capable de tool calling
ollama pull qwen3:14b

# 3. Environnement Python isolé
python -m venv .venv && source .venv/bin/activate
pip install crewai crewai-tools

#CrewAI oder AutoGen: Welches wählen?

Beide Frameworks koordinieren Agenten, jedoch mit unterschiedlichen Ansätzen. Die beste Wahl hängt von Ihrer Aufgabe ab, nicht von einem absoluten Ranking.

CrewAI

Teamorientiert: Man definiert Agenten mit einer Rolle, einem Ziel und Werkzeugen und weist ihnen dann Aufgaben in einer festgelegten Reihenfolge zu. Deklarativer, gut lesbarer Ansatz, ideal für geschäftliche Pipelines (recherchieren → schreiben → gegenlesen). Integrierter RAG-Speicher.

AutoGen

Auf „Konversation“ ausgerichtet: Die Agenten sprechen miteinander, bis sie zu einem gemeinsamen Ergebnis kommen. Flexibler für offene Probleme und gemeinsames Schlussfolgern, erfordert aber mehr Abstimmung, um den lokalen Ablauf in Grenzen zu halten. Version 0.4 bindet Ollama über ihren OpenAI-kompatiblen Client an.

Wann eine einfache Lösung genügt

Für einen einzelnen Agenten mit einigen Werkzeugen reicht ein schlankes Framework (oder LangChain) aus. CrewAI und AutoGen entfalten ihren vollen Nutzen, sobald mehrere Rollen oder eine nicht triviale Orchestrierung ins Spiel kommen.

from crewai import Agent, Task, Crew, LLM

# CrewAI passe par LiteLLM : préfixe 'ollama/' + base_url local
llm = LLM(
    model="ollama/qwen3:14b",
    base_url="http://localhost:11434",
)

chercheur = Agent(
    role="Analyste documentaire",
    goal="Extraire les faits clés des documents fournis",
    backstory="Expert méthodique, ne répond que sur la base des sources.",
    llm=llm,
    verbose=True,
)

tache = Task(
    description="Résume les 3 points essentiels du rapport fourni.",
    expected_output="Une liste à puces de 3 points, sourcés.",
    agent=chercheur,
)

equipe = Crew(agents=[chercheur], tasks=[tache])
print(equipe.kickoff())

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

# Endpoint OpenAI-compatible d'Ollama : /v1
client = OpenAIChatCompletionClient(
    model="qwen3:14b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignore par Ollama, mais requis par le client
    model_info={
        "function_calling": True,
        "json_output": True,
        "vision": False,
        "family": "unknown",
    },
)

agent = AssistantAgent(name="assistant", model_client=client)

#Den Agenten Schritt für Schritt aufbauen

Hier ist der Ablauf, um von einem rohen Modell zu einem lokalen KI-Agenten zu gelangen, der eine echte Aufgabe erfüllt. Die Reihenfolge ist wichtig: Jeder Schritt validiert den vorherigen.

1. 01
   Das Ziel und die Abbruchbedingung definieren

   Schreiben Sie in einem Satz auf, was der Agent erzeugen soll und woran man erkennt, dass er fertig ist. Ein vages Ziel („hilf mir“) führt zu einem Agenten, der sich im Kreis dreht; ein klar abgegrenztes Ziel („sortiere diese 20 Rechnungen nach Lieferant in einer CSV-Datei“) führt zu einem kontrollierbaren Agenten.
2. 02
   In atomare Werkzeuge aufteilen

   Jede externe Aktion wird zu einer Python-Funktion mit einem eindeutigen Namen, typisierten Argumenten und einem klaren Docstring – genau diese Beschreibung liest das Modell. Bevorzugen Sie mehrere kleine, präzise Werkzeuge gegenüber einem großen Allzweckwerkzeug.
3. 03
   System-Prompt verfassen

   Definieren Sie die Rolle, die verfügbaren Werkzeuge und die Regeln (niemals etwas erfinden, immer die Quelle nennen, bei Zweifeln anhalten). Beim lokalen Betrieb gleicht ein strenger Prompt die geringere Differenziertheit des Modells beim Schlussfolgern aus.
4. 04
   Die Orchestrierungsschleife einrichten

   Lassen Sie das Framework die Schleife „schlussfolgern → handeln → beobachten“ steuern, setzen Sie aber eine Obergrenze für die Iterationen (zum Beispiel 10), damit ein festgefahrener Agent nicht unbegrenzt Ressourcen verbraucht. Das ist eine wesentliche Schutzmaßnahme im autonomen Betrieb.
5. 05
   Gedächtnis hinzufügen

   Binden Sie einen Vector Store als Langzeitgedächtnis an, wenn sich der Agent über Sitzungen hinweg an Informationen erinnern muss (siehe nächster Abschnitt). Wenn das nicht nötig ist, reicht der Gesprächsverlauf aus.
6. 06
   An realen Fällen testen und iterieren

   Starten Sie den Agenten mit verschiedenen Eingaben, lesen Sie die Ausführungsprotokolle (verbose) und korrigieren Sie die Prompts und die Werkzeugbeschreibungen. 80 % der Arbeit an einem lokalen Agenten findet hier statt, nicht im ursprünglichen Code.

#Langzeitgedächtnis mit RAG

Ein Agent ohne Gedächtnis beginnt jede Sitzung von vorne. Das Langzeitgedächtnis basiert auf demselben Prinzip wie RAG (Retrieval-Augmented Generation): Informationen werden als Vektoren in einer Datenbank gespeichert. Bei Bedarf werden die relevantesten Informationen abgerufen und wieder in den Kontext eingefügt.

Lokale Embeddings

Generieren Sie die Vektoren mit einem Embedding-Modell, das von Ollama bereitgestellt wird (z. B. nomic-embed-text oder mxbai-embed-large): Die zu speichernden Daten verlassen die Maschine nicht, was dem Datenschutzziel entspricht.

Vector Store

ChromaDB ist die Standardwahl für den lokalen Betrieb: schlank, mit persistenter Speicherung auf der Festplatte und nativ in CrewAI integriert. Für größere Datenmengen übernimmt eine selbst gehostete Qdrant-Instanz.

Integriertes Gedächtnis von CrewAI

CrewAI bietet ein sofort nutzbares Gedächtnis (Kurzzeit-, Langzeit- und Entitätsgedächtnis), das sich für die Verwendung eines Ollama-Embedders konfigurieren lässt, ohne die RAG-Pipeline von Hand aufbauen zu müssen.

from crewai import Crew

equipe = Crew(
    agents=[chercheur],
    tasks=[tache],
    memory=True,  # active la memoire long terme (ChromaDB sous le capot)
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

#Aufgabenplanung

Planung ist die Fähigkeit des Agenten, ein komplexes Ziel vor dem Handeln in geordnete Schritte zu zerlegen. Ohne sie neigt ein lokales Modell dazu, sich auf die erstbeste Aktion zu stürzen und sich dabei zu verzetteln. Es gibt zwei Ansätze.

Implizite Planung (ReAct)

Das Modell denkt Schritt für Schritt laut nach, wählt eine Aktion, beobachtet und plant dann neu. Einfach einzurichten, aber anfällig bei kleinen Modellen, die nach wenigen Runden den Faden verlieren.

Explizite Planung

Ein Agent (oder eine erste Aufgabe) für die Planung erzeugt eine Liste von Schritten, die dann von Ausführungsagenten verarbeitet werden. Lokal robuster: Man trennt 'denken' von 'tun', was die Belastung jedes Aufrufs verringert.

Hierarchische Zerlegung

Für langwierige Aufgaben ermöglicht CrewAI einen hierarchischen Prozess, bei dem ein „Manager“-Agent Aufgaben delegiert und die Ausführung überwacht. Leistungsfähig, aber Fällen vorbehalten, die den Aufwand rechtfertigen – die Koordination kostet Tokens.

Faustregel für den lokalen Betrieb: Je kleiner das Modell, desto expliziter muss die Planung sein und desto enger muss der Umfang jedes Schritts begrenzt werden. Ein 14B-Modell, das eine klar umrissene Mikroaufgabe bearbeitet, ist zuverlässiger als ein 32B-Modell, das mit einem vagen Ziel sich selbst überlassen wird.

#Datensicherheit

Ein vollständig lokaler Betrieb verhindert, dass Daten an APIs von Drittanbietern abfließen. Ein autonomer Agent bringt jedoch eigene Risiken mit sich: Er führt auf Grundlage eines generierten Textes Aktionen aus, die manchmal destruktiv sind. Vertraulichkeit macht Schutzmaßnahmen nicht überflüssig.

Prinzip der geringsten Rechte

Geben Sie dem Agenten nur die unbedingt notwendigen Werkzeuge. Ein Agent, der nicht auf die Festplatte schreiben muss, darf kein Schreibwerkzeug haben — das ist die erste Schutzbarriere gegen Schäden.

Freigabe sensibler Aktionen durch einen Menschen

Für alle irreversiblen Aktionen (Löschen, Senden, Bezahlen, Ändern einer Datenbank) muss eine manuelle Bestätigung eingefügt werden. Die vollständige Autonomie ist nur für sichere und umkehrbare Aktionen gerechtfertigt.

Isolierung der Codeausführung

Wenn der Agent Code ausführt, lassen Sie ihn dies in einem Container oder einer Sandbox-Umgebung tun, niemals direkt auf dem Hostrechner. Ein bösartiger Prompt, der in ein Dokument eingeschleust wird, kann einen Agenten manipulieren (Prompt-Injektion).

Protokollierung der Aktionen

Protokollieren Sie jeden Werkzeugaufruf und jede Entscheidung. Bei unerwartetem Verhalten ist das Protokoll Ihre einzige Möglichkeit, zu verstehen, was der Agent tatsächlich getan hat.

#Tipps und Fehlerbehebung

Der Agent läuft in einer Schleife, ohne jemals anzuhalten

Prüfen Sie die Abbruchbedingung und die Iterationsgrenze. Oft ist das Ziel zu ungenau oder der Agent erkennt nicht, dass er fertig ist: Formulieren Sie das erwartete Ergebnis im Prompt ausdrücklich.

Falsch formatierte Tool-Aufrufe

Das Modell erfindet Argumente oder lässt Felder aus. Vereinfachen Sie die Tool-Schemas, wechseln Sie zur nächsthöheren Quantisierungsstufe (Q4 → Q5) oder zu einem Modell, das beim Tool Calling zuverlässiger ist.

Langsame Antworten beim Einsatz mehrerer Agenten

Jeder Agent entspricht einem vollständigen Modellaufruf. Reduzieren Sie beim lokalen Betrieb die Anzahl der Agenten, kürzen Sie die Systemprompts und prüfen Sie, ob das Modell vollständig in den VRAM passt (andernfalls lässt die Auslagerung auf die CPU den Durchsatz einbrechen).

Der Speicher findet nichts Relevantes

Falsches Embedding-Modell oder zu große bzw. zu kleine Chunks. Prüfen Sie, ob der Ollama-Embedder läuft, und passen Sie die Größe der gespeicherten Textabschnitte an.

Verbindung zu :11434 verweigert

Ollama läuft nicht oder lauscht auf einer anderen Netzwerkschnittstelle. Überprüfen Sie dies mit „curl http://localhost:11434/api/tags“ und prüfen Sie die base_url, die dem Framework übergeben wurde.

#Weiterführende Informationen

Dieser Leitfaden beschreibt die Architektur; diese Tutorials gehen auf die konkrete Implementierung jedes einzelnen Bausteins ein:

Mehrere Agenten mit CrewAI

„CrewAI + Ollama: Mehrere KI-Agenten lokal orchestrieren“ beschreibt ausführlich die Einrichtung eines Teams spezialisierter Agenten samt Rollen und Aufgaben.

Ein Python-Agent von A bis Z

„Einen lokalen KI-Agenten in Python mit LangChain und Ollama erstellen“ zeigt Schritt für Schritt, wie ein Agent aufgebaut wird, der Tools aufrufen und Dateien lesen kann.

Der Gedächtnisbaustein (RAG)

„Lokales RAG mit ChromaDB und Ollama: Python-Tutorial“ behandelt die vollständige Pipeline Embeddings → Suche → Antwort, das Herzstück des Langzeitgedächtnisses.