Einen LangChain-SQL-Agenten für Abfragen in natürlicher Sprache auf MySQL bauen

Unternehmensdaten liegen meist hinter einer technischen Mauer. Wer etwas daraus wollte, musste SQL schreiben oder ein starres Klick-Tool lernen. Eine Schnittstelle in natürlicher Sprache entfernt diese Zwischenschicht: Die Person, die entscheidet, stellt die Frage direkt, und die Analyse wird von ihrer Absicht gesteuert, nicht von technischem Können. Ein SQL-Agent auf Basis von LangChain ist ein praktischer Weg dorthin. Im Folgenden: was der Agent tut, wie Sie die Umgebung und eine MySQL-Testdatenbank einrichten, wie Sie den Executor verdrahten und welche Schutzmaßnahmen nötig sind, bevor er etwas Echtes anfasst.

Wie der Datenzugriff einfacher wurde

Jede Generation von Werkzeugen hat mehr von der darunterliegenden Komplexität verborgen:

1. Kommandozeilen-Clients verlangten exakte Syntax und ein solides Verständnis relationaler Algebra.
2. Visuelle Query-Builder halfen, aber Joins und Tabellenbeziehungen musste man trotzdem verstehen.
3. Dashboards waren leicht zu lesen, blieben aber auf die Ansichten beschränkt, die jemand vorab gebaut hatte.
4. Schnittstellen in natürlicher Sprache erfassen die Bedeutung, sodass niemand das Schema oder eine Abfragesprache kennen muss.

Ein KI-SQL-Agent bringt mehrere konkrete Vorteile:

• Er liest das Schema selbstständig und findet die relevanten Tabellen, Primär- und Fremdschlüssel sowie Join-Pfade.
• Er ordnet umgangssprachliche Formulierungen Datenbankentitäten zu und schreibt und führt dann komplexe Abfragen aus, ohne dass jemand eingreifen muss.
• Er ruft das Schema nur für die relevanten Tabellen ab, was Token-Verbrauch und Kosten senkt und der Performance hilft.
• Er verwandelt vage Fragen wie „Wie liefen die Verkäufe letzten Monat?“ in deterministisches SQL, indem er den Kontext erschließt und Entitäten zuordnet.

Zuverlässig funktioniert das nur mit dem richtigen Unterbau, nämlich einem Orchestrierungs-Framework und einer isolierten Umgebung.

Woraus ein LangChain-SQL-Agent besteht

Ein Sprachmodell, das mit einer strukturierten Datenbank spricht, braucht eine Middleware, und LangChain liefert das Bindegewebe: Schlussfolgern, Werkzeugwahl und Ausführungszyklen, die einen Prompt in eine sichere Datenbankoperation verwandeln. Die Agenten unterscheiden sich im Stil des Schlussfolgerns und in den unterstützten Modellen.

Im Zentrum steht die ReAct-Schleife, kurz für Reasoning plus Acting:

1. Auswählen: Der Agent liest den Prompt und wählt ein Werkzeug, etwa einen SQL-Executor.
2. Handeln: Er führt dieses Werkzeug aus, zum Beispiel die generierte Abfrage.
3. Prüfen: Er bewertet die Ausgabe und entscheidet, ob das reicht oder ein weiterer Durchlauf nötig ist.
4. Wiederholen: Der Zyklus läuft weiter, bis eine endgültige, validierte Antwort vorliegt.

Außerdem wählen Sie zwischen zwei Designs. Ein One-Shot-System behandelt jede Frage für sich, mit geringerer Latenz und einfacherer Optimierung. Ein dialogorientiertes System verfolgt den Zustand und führt das Gespräch, sodass Nutzer ihre Suche mit Folgefragen verfeinern und Mehrdeutigkeiten über mehrere Runden klären können – eine Art Dialog mit den Daten.

Umgebung und Abhängigkeiten

Für alles, was Richtung Produktion geht, sollten Sie die Umgebung isolieren und Versionen fixieren, damit ein Bibliotheksupdate die Pipeline nicht unbemerkt kaputt macht. Legen Sie eine virtuelle Umgebung an und aktivieren Sie sie:

pip install virtualenv
virtualenv my_env
source my_env/bin/activate

Installieren Sie dann diesen Stack in genau diesen Versionen:

• ibm-watsonx-ai==1.0.4 übernimmt die Inferenz des Foundation Models.
• ibm-watson-machine-learning==1.0.357 bindet die Enterprise-LLMs ein.
• langchain==0.2.1 ist das zentrale Orchestrierungs-Framework für die Agentenlogik.
• langchain-ibm==0.1.7 liefert Wrapper speziell für das IBM-Ökosystem.
• langchain-experimental==0.0.59 enthält zusätzliche Agenten-Hilfsmittel.
• mysql-connector-python==8.4.0 ist der Datenbanktreiber.

Die Datenbank, die der Agent abfragt

Ein Agent ist nur so genau wie seine Datenbank. Er stützt sich auf Tabellennamen, Spaltenbeschreibungen und Schlüsselbeziehungen, um eine Frage mit den Daten zu verbinden, also muss das Schema sauber sein.

Chinook eignet sich gut als Testumgebung, weil es ein komplettes Geschäft mit digitalen Medien abbildet:

• Es hat 11 Tabellen, darunter Artist, Album, Invoice und Track.
• Primär- und Fremdschlüssel erlauben dem Agenten Joins über mehrere Tabellen.
• Es enthält mehr als 15.000 Datensätze, genug, um Trendanalysen und komplexe Abfragen zu prüfen.

Der Agent verbindet sich über eine URI, die exakt diesem Muster folgen muss:

mysql+mysqlconnector://{mysql_username}:{mysql_password}@{mysql_host}:{mysql_port}/{database_name}

Fünf Werte sind nötig: Benutzername, Passwort, Host, Port (standardmäßig 3306) und Datenbankname, hier Chinook.

Bevor ein LLM ins Spiel kommt, prüfen Sie Verbindung und Schema über die MySQL-CLI:

-- Verify database existence
SHOW DATABASES;
USE Chinook;

-- Confirm data integrity: This should return exactly 347
SELECT COUNT(*) FROM Album;

Die Anzahl der Alben sollte genau 347 betragen. Eine geprüfte Datenbank gibt dem Modell eine solide Grundlage und senkt die Wahrscheinlichkeit von Fehlern bei der Datenzuordnung.

Den Agent-Executor bauen

Als Nächstes wird das Modell gekapselt und an einen Datenbank-Executor angebunden, der bestimmt, wie der Agent Ihre Daten sieht und mit ihnen arbeitet.

Stellen Sie die Modellparameter auf Determinismus ein. Bei der SQL-Generierung führt unvorhersehbare Ausgabe direkt zu erfundener Syntax, also halten Sie alles stabil.

Der Agent entsteht über die Factory create_sql_agent, mit ibm/granite-4-h-small als Reasoning-Engine. Sie braucht diese Argumente:

• llm nimmt das Granite-Modell, gekapselt in einer WatsonxLLM-Instanz.
• db nimmt Ihre SQLDatabase-Verbindung.
• verbose=True lässt Sie beobachten, was er tut.
• agent_type, gesetzt auf ZERO_SHOT_REACT_DESCRIPTION für gewöhnliche analytische Fragen.

Betrachten Sie verbose=True als mehr als einen Debug-Schalter. Im Unternehmenskontext macht er Audits überhaupt erst möglich. Sie können die Gedankenkette einsehen und prüfen, ob das generierte SQL und die Denkschritte zur internen Datenlogik und zu Compliance-Vorgaben passen, bevor eine Antwort jemanden erreicht.

Fehlerbehebung und Schutzmaßnahmen

Mehrdeutige Sprache und die Zuordnung zum Schema bringen selbst starke Modelle ins Straucheln, deshalb braucht ein Produktivsystem automatische Schutzmaßnahmen und menschliche Aufsicht.

Eine echte Stärke dieses Agenten ist die Selbstkorrektur. Schlägt eine generierte Abfrage fehl, dann:

1. erfasst er den Traceback der Datenbank-Engine,
2. ermittelt, was schiefgelaufen ist, etwa ein Syntaxfehler oder ein falsch geschriebener Spaltenname,
3. und versucht es mit einer korrigierten Anweisung erneut, was die Erfolgsquote bei komplizierten Abfragen erhöht.

Vier Praktiken schützen Unternehmensdaten:

1. Führen Sie jede vom Agenten ausgelöste Abfrage in einer isolierten Sandbox aus, damit nichts versehentlich verändert wird.
2. Behalten Sie einen Menschen in der Schleife: Eine Fachperson prüft Ergebnisse, die in wichtige Berichte einfließen.
3. Verfeinern Sie Prompts laufend, um unterschiedliche Formulierungen und domänenspezifische Eigenheiten abzudecken.
4. Geben Sie dem Datenbank-Connector ein eingeschränktes Benutzerprofil mit strikter Zeilensicherheit und klaren Datenschutzgrenzen.

Was bleibt

Der Wechsel von reinem SQL zu Abfragen in natürlicher Sprache öffnet Daten für weit mehr Menschen. Kombinieren Sie ein präzises Modell wie ibm/granite-4-h-small mit der strukturierten Orchestrierung von LangChain, und die Lücke zwischen Alltagssprache und verwertbaren Erkenntnissen wird kleiner. Ein System, dem man in der Produktion vertrauen kann, entsteht aber weiterhin durch kontinuierliches Testen und klare Governance.