Einen lokalen KI-Agenten mit Python, LangChain und Ollama erstellen

#Warum ein lokaler KI-Agent in Python?

Ein Agent im Sinne von LangChain ist eine einfache Schleife: Das LLM erhält eine Frage und die Liste seiner Werkzeuge, entscheidet sich, eines davon aufzurufen (oder keines), liest das Ergebnis und wiederholt den Vorgang, bis es antworten kann. Die gesamte „Entscheidungsmechanik“ beruht auf der Fähigkeit des Modells, einen strukturierten Werkzeugaufruf zu erzeugen.

Wenn Sie das lokal mit Ollama durchführen, ändern sich zwei konkrete Dinge: Ihre Daten verlassen den Rechner nie, und jeder Aufruf kostet null Euro. Das ist der Unterschied zwischen dem Entwickeln von Prototypen mit OpenAI und einer Rechnung über 50 € am Ende der Woche einerseits und dem Iterieren ohne Rücksicht auf die Kosten andererseits.

Datenschutz

Die Dateien, die der Agent liest (Verträge, proprietärer Code, medizinische Notizen), verlassen den Rechner nicht. Kein DPA zu unterschreiben, keine Datenübertragung außerhalb der EU.

Keine Grenzkosten

Nach dem Download des Modells können Sie täglich Hunderte von Iterationen durchführen, ohne dass die Gebühren ansteigen.

Reproduzierbarkeit

Sie fixieren die exakte Version des Modells (qwen3.5:9b, granite4.2:8b usw.). Keine unbemerkte Drift wie bei gpt-4o-2024-11-20, das einen Monat später etwas anderes ist.

Vorhersehbare Latenz

Kein Hin und Her über das Netzwerk. Mit einer ordentlichen GPU erscheint das erste Token in weniger als einer Sekunde.

#Voraussetzungen

Python 3.10+

LangChain wird nicht mehr unter 3.9 getestet. Überprüfen Sie die Version mit python --version.

Ollama installiert und gestartet

Ollama muss unter http://localhost:11434 lauschen. Falls Installation und Start noch nicht erfolgt sind, die Installationsanleitungen für Ollama (Windows, macOS, Linux) konsultieren.

Ein Modell, das Werkzeuge aufrufen kann

Nicht alle LLM können Tools aufrufen. Qwen 3.5, Granite 4.2, Gemma 4, Devstral und GLM 4.7 Flash unterstützen Tool-Calling nativ. Vermeiden Sie inzwischen veraltete Modelle (Llama 2/3, Qwen 2.5, Mistral 7B).

Hardware

Qwen 3.5 9B Q4 benötigt etwa 6,6 GB VRAM. Eine GPU mit 8 GB (RTX 3060, 4060) reicht aus, eine mit 12 GB (4070) bietet Spielraum. Auf einem Mac sollten Sie 16 GB vereinheitlichten Speicher einplanen, um genügend Reserve zu haben.

#1. Das Python-Projekt initialisieren

Eine virtuelle Umgebung, drei Pakete, und das ist alles. Man vermeidet es, LangChain in der systemweiten Python-Umgebung zu installieren — LangChain verändert sich schnell und bringt Unordnung in diese Umgebung.

mkdir agent-local && cd agent-local
python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
# .venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install langchain langchain-ollama langgraph

langchain

Der Kern: Promptabstraktionen, Werkzeuge, Nachrichten.

langchain-ollama

Die offizielle Ollama-Integration. Seit 2024 vom LangChain-Team gepflegt.

langgraph

Für die Agentenschleife. Das ist die derzeit empfohlene Engine, stabiler als die früheren AgentExecutor.

#2. Von Python aus eine Verbindung zu Ollama herstellen

Bevor man einen Agenten aufbaut, prüft man, ob man tatsächlich mit dem Modell kommuniziert. Laden Sie das Modell herunter, falls Sie das noch nicht getan haben, und testen Sie anschließend den einfachsten möglichen Aufruf.

ollama pull qwen3.5:9b

Der Download ist in Q4_K_M etwa 6,6 GB groß (der Standardquantisierung bei Ollama). Sobald das Modell eingerichtet ist, erstellen Sie das erste Skript:

from langchain_ollama import ChatOllama

llm = ChatOllama(
    model="qwen3.5:9b",
    temperature=0,
    # base_url="http://localhost:11434",  # par défaut, à changer si Ollama est ailleurs
)

reponse = llm.invoke("En une phrase : qu'est-ce qu'un agent IA ?")
print(reponse.content)

python test_ollama.py

Wenn Sie einen kohärenten Satz sehen, funktioniert die Verbindung Python ↔ Ollama. Falls ein ConnectionError auftritt, überprüfen Sie, ob Ollama ordnungsgemäß läuft (ollama ps sollte einen aktiven Dienst auflisten).

#3. Die Werkzeuge des Agenten definieren

Ein LangChain-Tool ist einfach eine Python-Funktion, die mit @tool dekoriert ist. Der Docstring wird zur Beschreibung, die das LLM sieht – das Modell nutzt sie, um zu entscheiden, wann es die Funktion aufruft. Seien Sie präzise: Ein vager Docstring führt zu zufälligen Aufrufen.

Wir erstellen zwei repräsentative Werkzeuge: eines zur Auswertung arithmetischer Ausdrücke und eines zum Lesen von Dateien.

from pathlib import Path
from langchain_core.tools import tool


@tool
def calculer(expression: str) -> str:
    """Évalue une expression arithmétique simple.

    Args:
        expression: une expression contenant uniquement des chiffres,
                    des espaces et les opérateurs + - * / ( ).

    Returns:
        Le résultat numérique sous forme de chaîne, ou un message d'erreur.
    """
    autorise = set("0123456789+-*/(). ")
    if not all(c in autorise for c in expression):
        return "Erreur : caractère non autorisé. Seuls 0-9 et + - * / ( ) sont permis."
    try:
        resultat = eval(expression, {"__builtins__": {}}, {})
        return str(resultat)
    except Exception as e:
        return f"Erreur de calcul : {e}"


@tool
def lire_fichier(chemin: str) -> str:
    """Lit le contenu d'un fichier texte du répertoire courant.

    Args:
        chemin: chemin relatif ou absolu vers un fichier texte (.txt, .md, .py, etc.).

    Returns:
        Le contenu du fichier, ou un message d'erreur si introuvable.
    """
    p = Path(chemin)
    if not p.exists():
        return f"Fichier introuvable : {chemin}"
    if not p.is_file():
        return f"Ce n'est pas un fichier : {chemin}"
    try:
        return p.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        return "Fichier binaire ou encodage non UTF-8."
    except Exception as e:
        return f"Erreur de lecture : {e}"

Drei Regeln, um sicherzustellen, dass das Modell Tools korrekt verwendet:

Aussagekräftiger Name

calculer statt process, lire_fichier statt get. Das LLM orientiert sich bei der Auswahl zuerst am Namen.

Ausführlicher Docstring

Beschreiben Sie, was das Tool tut, was es erwartet und was es zurückgibt. Die Python-Typannotationen werden von LangChain gelesen und dem Modell zugänglich gemacht.

Einen String zurückgeben

Immer. Wenn die Funktion ein dict oder ein Objekt zurückgibt, serialisiert LangChain es, aber das Ergebnis ist für das Modell weniger gut lesbar.

#4. Den Agenten zusammenbauen

Wir haben ein LLM und Werkzeuge. Die Funktion create_react_agent von langgraph verbindet beide und steuert die Schleife: Solange das Modell Werkzeuge aufrufen möchte, geht es weiter; sobald es mit Text antwortet, wird die Schleife beendet.

from langchain_ollama import ChatOllama
from langgraph.prebuilt import create_react_agent
from tools import calculer, lire_fichier

llm = ChatOllama(model="qwen3.5:9b", temperature=0)

SYSTEM_PROMPT = (
    "Tu es un assistant en français. Tu disposes d'outils pour calculer "
    "et lire des fichiers. Utilise-les dès que c'est pertinent, sans jamais "
    "inventer un résultat. Réponds toujours en français."
)

agent = create_react_agent(
    model=llm,
    tools=[calculer, lire_fichier],
    prompt=SYSTEM_PROMPT,
)

if __name__ == "__main__":
    question = (
        "Combien fait 1234 * 5678 ? "
        "Ensuite, lis le fichier notes.txt et résume-le en deux phrases."
    )
    reponse = agent.invoke({"messages": [("user", question)]})

    # Le dernier message est la réponse finale du modèle
    print(reponse["messages"][-1].content)

Legen Sie zum Testen eine kleine Datei notes.txt daneben an:

echo "Réunion projet Hermes : on garde Ollama comme runtime principal, on évalue vLLM pour la prod, RAG sur ChromaDB. Décision : POC en 2 semaines." > notes.txt

#5. Die Schleife ausführen und beobachten

python agent.py

Sie sollten eine Antwort sehen, die sowohl das Berechnungsergebnis (7.006.652) als auch eine Zusammenfassung des Dateiinhalts enthält. Aufschlussreicher ist es jedoch, zu sehen, was während der Ausführung passiert. Fügen Sie diesen Modus mit ausführlicher Ausgabe hinzu, um die Schleife Schritt für Schritt zu verfolgen:

for evenement in agent.stream(
    {"messages": [("user", question)]},
    stream_mode="values",
):
    dernier = evenement["messages"][-1]
    dernier.pretty_print()
    print("---")

Sie werden den typischen Ablauf eines Agenten beobachten: Das Modell erzeugt einen Aufruf von calculer, erhält das Ergebnis, erzeugt einen Aufruf von lire_fichier, erhält den Inhalt und generiert dann die endgültige Antwort. Drei Iterationen für eine einzige Benutzerfrage.

#Tipps und Fehlerbehebung

Zu kurzer Kontext

Standardmäßig kürzt Ollama den Kontext auf 2048 Tokens. Wenn Ihr Agent mehrere Tools nacheinander aufruft, wird diese Grenze schnell überschritten. Setzen Sie num_ctx=8192 in ChatOllama(model="...", num_ctx=8192).

Modell, das Werkzeuge halluziniert

Wenn der Agent Funktionsnamen erfindet, senken Sie die Temperatur auf 0 und formulieren Sie den System-Prompt neu, indem Sie die verfügbaren Werkzeuge ausdrücklich auflisten.

Unendliche Schleife

Setzen Sie eine Grenze: create_react_agent(..., recursion_limit=10). Wird sie überschritten, beendet sich der Agent kontrolliert.

Zu hohe Latenz

Auf einer CPU erreicht ein 9B-Modell 5–10 Tokens/s. Wechseln Sie zu qwen3.5:4b (3,4 GB VRAM, 30+ Tokens/s auf einer einfachen GPU), wenn die Qualität für Ihren Anwendungsfall weiterhin akzeptabel ist.

Fehler „context length exceeded“

Die Zusammenfassung einer langen Datei überschreitet num_ctx. Fügen Sie ein zwischengeschaltetes Werkzeug hinzu, das die Datei in Chunks aufteilt, oder erhöhen Sie num_ctx auf bis zu 32768, sofern Ihr VRAM ausreicht.

#Weiterführende Informationen

Sie haben einen Agenten, der lokal rechnet, liest und Schlussfolgerungen zieht. Drei naheliegende Richtungen zur Vertiefung:

Ihm Zugriff auf Ihre Dokumente geben

Den Agenten mit einer Vektordatenbank verbinden, damit er Fragen zu einem internen Korpus beantworten kann — genau darum geht es im Einführungsleitfaden zu lokalem RAG.

Für die Arbeit am Code die CLI nutzen

Aider ist ein Entwicklungsagent, der Ihre Dateien direkt vom Terminal aus bearbeitet. Sie können ihn mit derselben Ollama-Instanz verbinden und Qwen3-Coder 30B oder Devstral für die assistierte Bearbeitung nutzen.

Quantisierung des Modells einstellen

Wenn Ihnen Qwen 3.5 9B Q4 zu langsam ist oder seine Qualität gerade noch ausreicht, erklärt der Leitfaden zur Quantisierung, wann Sie zu Q5_K_M wechseln oder ein kleineres Modell wählen sollten.