RAG-Agenten zuverlässig betreiben

29. Juli 2026 KI-Stack

Eine funktionierende Vektorsuche ist noch kein verlässlicher RAG-Agent. Sie kann ähnliche Textabschnitte finden, beantwortet aber nicht die entscheidenden Betriebsfragen: Ist die Quelle aktuell? Gehört sie überhaupt zum Auftrag? Darf das Modell ein Werkzeug aufrufen? Wurde dessen Ergebnis geprüft? Und lässt sich später nachvollziehen, wie die Antwort entstanden ist?

Genau an diesen Übergängen entscheidet sich, ob eine RAG- und Agentenlösung lediglich in einer Demonstration beeindruckt oder im Alltag belastbar arbeitet.

Dieser Folgeartikel betrachtet deshalb nicht erneut die grundlegenden Komponenten des lokalen KI-Stacks. Im Mittelpunkt steht der vollständige Verarbeitungspfad – von der Dokumentaufnahme bis zur freigegebenen Antwort oder Aktion.

Ein RAG-Agent besteht aus zwei Kreisläufen

Der Betrieb lässt sich in einen Wissenskreislauf und einen Aufgabenkreislauf unterteilen.

Der Wissenskreislauf bereitet Quellen so auf, dass sie später gezielt gefunden werden können:

Quelle → Extraktion → Aufteilung → Embedding → Vektorspeicher → Qualitätsprüfung

Der Aufgabenkreislauf verarbeitet eine konkrete Benutzeranfrage:

Auftrag → Planung → Retrieval → Bewertung → Werkzeug → Antwort → Nachweis

Beide Kreisläufe sind voneinander abhängig. Ein gut steuernder Agent kann schlechte oder veraltete Wissensbestände nicht reparieren. Umgekehrt nutzt ein sauber aufgebauter Index wenig, wenn das Modell Quellen ignoriert oder Werkzeuge mit falschen Parametern aufruft.

Schritt 1: Quellen kontrolliert aufnehmen

Der RAG-Prozess beginnt nicht beim Embedding, sondern bei der Entscheidung, welche Inhalte überhaupt als Wissensquelle gelten.

Vor dem Import sollten deshalb mindestens folgende Punkte geklärt sein:

fachlicher Eigentümer der Quelle,
Dokumenttyp und Geltungsbereich,
Versions- oder Änderungsstand,
Vertraulichkeitsklasse,
zulässige Benutzer- oder Agentengruppe,
Aktualisierungs- und Löschregel.

Ohne diese Angaben entsteht schnell ein technisch sauberer, aber fachlich unkontrollierter Datenbestand. Mehr Dokumente bedeuten nicht automatisch bessere Antworten. Widersprüchliche Entwürfe, alte Installationsstände oder ungeprüfte Notizen erhöhen vielmehr das Risiko, dass die Suche den falschen Kontext liefert.

Für den lokalen KI-Stack sind Quellpfad, Abschnittsnummer, Inhalts-Hash und Importzeitpunkt als Metadaten vorgesehen. Der Hash hilft dabei, einen unveränderten Inhalt wiederzuerkennen. Er beweist jedoch nicht, dass das Dokument fachlich gültig ist. Dafür wird zusätzlich ein nachvollziehbarer Status benötigt.

Schritt 2: Dokumente sinnvoll zerlegen

OpenWebUI zerlegt umfangreiche Dokumente für fokussiertes Retrieval in Abschnitte. Die Qualität dieser Abschnitte beeinflusst unmittelbar die spätere Suche.

Ein brauchbarer Abschnitt sollte:

einen in sich verständlichen Gedanken enthalten,
Überschrift und fachlichen Kontext bewahren,
nicht mitten in Tabellen oder Anweisungen abbrechen,
ausreichend klein für eine präzise Auswahl bleiben,
ausreichend groß für eine verständliche Antwort sein.

Eine starre Zeichenzahl kann dafür nur ein Ausgangspunkt sein. Technische Dokumente profitieren häufig von einer strukturorientierten Trennung an Überschriften. Die aktuelle RAG-Dokumentation von OpenWebUI beschreibt dafür eine Markdown-Header-Aufteilung und das Zusammenführen zu kleiner Fragmente.

Für Tabellen, Prüfnachweise und Konfigurationen gelten zusätzliche Anforderungen. Wird eine Tabellenzeile ohne Kopfzeile gespeichert, verliert sie ihre Bedeutung. Wird ein Konfigurationsblock vom erklärenden Abschnitt getrennt, kann das Retrieval zwar den Wert finden, aber seinen Zweck nicht mehr erklären.

Schritt 3: Embeddings konsistent erzeugen

Im KI-Stack übernimmt nomic-embed-text-v1.5 die semantische Abbildung. Das Modell verwendet aufgabenspezifische Präfixe:

search_document: für zu indexierende Dokumentabschnitte,
search_query: für spätere Suchanfragen.

Diese Präfixe gehören zum vorgesehenen Einsatz des Modells und sind in der Nomic-Modellbeschreibung dokumentiert.

Entscheidend ist die Konsistenz:

Dokumente und Anfragen verwenden dasselbe Embedding-Modell.
Beide Seiten verwenden die richtigen Präfixe.
Die Vektordimension bleibt unverändert.
Ein Modellwechsel führt zu einem kontrollierten Neuaufbau des Index.

Ein Vektorspeicher kann technisch verfügbar sein und dennoch unbrauchbare Treffer liefern, wenn Index und Suchanfrage mit unterschiedlichen Embedding-Konfigurationen erzeugt wurden.

Schritt 4: Metadaten für Scope und Aktualität nutzen

ChromaDB speichert neben Text und Embedding auch Metadaten. Diese können bei einer Abfrage als Filter verwendet werden. Die Chroma-Dokumentation beschreibt dafür den where-Filter.

Für einen Agenten ist diese Funktion besonders wichtig. Er sollte nicht zuerst den gesamten Wissensbestand durchsuchen und erst anschließend versuchen, unzulässige Treffer auszusortieren. Der zulässige Scope sollte bereits die Suche begrenzen.

Beispiele:

nur Dokumente eines konkreten Projekts,
nur freigegebene Betriebsdokumentation,
nur der aktuelle Paketstand,
nur Inhalte einer zulässigen Vertraulichkeitsklasse,
nur Quellen, die für den angemeldeten Benutzer freigegeben sind.

Damit werden Metadaten Teil des Berechtigungs- und Qualitätsmodells. Sie ersetzen keine Zugriffskontrolle, ermöglichen aber eine präzisere und nachvollziehbarere Auswahl.

Schritt 5: Die Benutzerfrage in einen Auftrag übersetzen

Nicht jede Frage benötigt denselben Ablauf. Ein Agent muss zunächst erkennen, welche Art von Aufgabe vorliegt.

Eine einfache Klassifikation kann unterscheiden:

Aufgabentyp	Geeigneter Pfad
Frage zu internem Wissen	RAG-Suche
Frage zu aktuellen Ereignissen	Webrecherche
Vergleich intern und extern	RAG plus Webrecherche
Bild- oder Videoerzeugung	ComfyUI-Werkzeug
Systemänderung	Werkzeug plus ausdrückliche Freigabe

Diese Einordnung darf nicht allein über einen frei formulierten Prompt verborgen bleiben. Für kritische Aufgaben sollten zulässige Werkzeuge, Parameter und Freigabeschritte technisch begrenzt sein.

OpenWebUI trennt den vorab eingebrachten Dateikontext von eingebauten Werkzeugen für den autonomen Wissenszugriff. Dadurch lässt sich ein vorhersagbarer RAG-Modus ohne autonome Werkzeugauswahl ebenso betreiben wie ein agentischer Modus mit nativen Funktionsaufrufen. Die möglichen Kombinationen sind in der OpenWebUI-Dokumentation beschrieben.

Schritt 6: Retrieval-Ergebnisse vor der Verwendung bewerten

Eine Vektorsuche liefert Ähnlichkeit, keine Wahrheit. Bevor Treffer an das Sprachmodell übergeben werden, sollten deshalb mehrere Prüfungen erfolgen:

Gehört der Treffer zum erlaubten Datenbereich?
Ist die Quelle freigegeben und aktuell?
Enthält der Abschnitt genug Kontext?
Widersprechen sich mehrere Treffer?
Reicht die Qualität für eine Antwort aus?

Ein niedriger Relevanzwert sollte nicht automatisch mit weiteren, noch schwächeren Treffern kompensiert werden. In manchen Fällen ist „keine belastbare Quelle gefunden“ die richtige Antwort.

Ebenso problematisch ist eine zu große Treffermenge. Sie füllt das Kontextfenster, erhöht die Latenz und kann dazu führen, dass das Modell die entscheidende Passage übersieht.

Schritt 7: Werkzeuge nach dem Prinzip minimaler Rechte bereitstellen

Agentische Systeme werden erst durch Werkzeuge handlungsfähig. Genau deshalb sind Werkzeuge die kritischste Schnittstelle.

Im lokalen Stack lassen sich die Fähigkeiten in Risikoklassen einteilen:

Lesende Werkzeuge

Wissensbasis durchsuchen,
Dokumentabschnitt lesen,
Statusinformationen abrufen,
Websuche durchführen.

Erzeugende Werkzeuge

Textdatei erstellen,
Bild- oder Video-Workflow starten,
Bericht oder Zusammenfassung erzeugen.

Verändernde Werkzeuge

Konfiguration ändern,
Daten ersetzen oder löschen,
Installationen ausführen,
externe Inhalte veröffentlichen.

Ein Agent sollte standardmäßig nur lesende Werkzeuge erhalten. Erzeugende Funktionen benötigen definierte Zielpfade und Formate. Verändernde Funktionen benötigen zusätzliche Freigaben, eng begrenzte Parameter und einen nachweisbaren Rückweg.

OpenWebUI weist darauf hin, dass Workspace Tools als Python direkt im Serverprozess laufen und entsprechend weitreichende Möglichkeiten besitzen. Solche Werkzeuge müssen vor dem Import geprüft und auf berechtigte Nutzer beschränkt werden. Sie sind keine harmlose Prompt-Erweiterung. Sie sind ausführbarer Code. Siehe dazu die offizielle Werkzeugdokumentation.

Schritt 8: Strukturierte Werkzeugverträge verwenden

Ein Werkzeug sollte kein beliebiges Textfragment zurückgeben. Für jeden Aufruf wird ein definierter Ergebnisvertrag benötigt.

Ein Wissenswerkzeug sollte beispielsweise liefern:

Status des Aufrufs,
gefundene Abschnitte,
Quelle und Dokumentstand,
Abschnittsnummer,
Relevanzwert,
verwendete Filter,
Fehler- oder Warnhinweise.

Ein Medienwerkzeug benötigt andere Angaben:

Jobstatus,
Workflow-Version,
Datei-ID,
Dateiname und URL,
MIME-Typ,
Dateigröße,
verwendete Parameter.

Strukturierte Ergebnisse erleichtern die Validierung. Das Sprachmodell muss nicht aus einem Fließtext erraten, ob ein Auftrag erfolgreich war oder lediglich gestartet wurde.

Schritt 9: Antwort und Aktion getrennt behandeln

Eine Antwort zu formulieren und eine Aktion auszuführen sind zwei unterschiedliche Zustände.

Ein sinnvoller Ablauf für verändernde Aufgaben ist:

Analyse → geplanter Schritt → Benutzerfreigabe → Ausführung → technische Prüfung → Ergebnis

Das Modell kann eine Änderung vorschlagen und erläutern. Erst nach der Freigabe darf das zuständige Werkzeug tätig werden. Anschließend muss das reale Ergebnis geprüft werden. Eine Erfolgsmeldung des Modells reicht dafür nicht aus.

Diese Trennung schützt auch vor indirekter Prompt Injection. Fremde Dokumente oder Webseiten können Text enthalten, der das Modell zu einer Aktion auffordert. Ein solcher Inhalt darf keine Berechtigung ersetzen.

Schritt 10: Die RAG-Qualität messbar testen

Ein „sieht gut aus“-Test genügt für RAG nicht. Sinnvoll ist ein kleiner, reproduzierbarer Prüfsatz aus realistischen Fragen.

Für jede Frage werden festgelegt:

erwartete Quelle,
erwarteter Dokumentabschnitt,
zulässige Alternativquelle,
unzulässige oder veraltete Quellen,
Kernaussage der erwarteten Antwort,
erlaubte Werkzeuge,
erwartetes Verhalten bei fehlendem Treffer.

Damit lassen sich mindestens vier Ebenen getrennt testen:

Importtest: Wurden Dokument und Metadaten vollständig aufgenommen?
Retrieval-Test: Wird der richtige Abschnitt unter den besten Treffern gefunden?
Antworttest: Verwendet das Sprachmodell den gelieferten Kontext korrekt?
Agententest: Wählt das Modell das richtige Werkzeug und hält es die Freigabegrenzen ein?

Fehlschläge werden dadurch genauer zugeordnet. Eine falsche Antwort kann aus einem Importfehler, einem ungeeigneten Chunk, einem schlechten Treffer, einer Kontextüberschreitung oder einer falschen Modellinterpretation entstehen.

Schritt 11: Negativtests nicht vergessen

Ein belastbarer Agent muss auch bei ungeeigneten Eingaben kontrolliert reagieren.

Wichtige Negativtests sind:

Frage zu einem nicht vorhandenen Dokument,
Suche mit widersprüchlichen Quellen,
Zugriff auf eine nicht freigegebene Wissensbasis,
manipulierte Anweisung innerhalb eines Dokuments,
ungültige Werkzeugparameter,
Zeitüberschreitung eines Werkzeugs,
fehlende Ergebnisdatei trotz Erfolgsmeldung,
wiederholter Werkzeugfehler,
Aufforderung zu einer nicht erlaubten Systemänderung.

Das erwartete Verhalten ist nicht immer eine Antwort. Es kann auch ein kontrollierter Abbruch, eine Rückfrage oder die Anforderung einer Freigabe sein.

Schritt 12: Jeden Lauf nachvollziehbar machen

Für Diagnose und Nachweise sollten die wesentlichen Entscheidungen erhalten bleiben:

Benutzerauftrag,
ausgewählter Betriebsmodus,
verwendetes Modell,
abgerufene Quellen und Metadaten,
aufgerufene Werkzeuge,
strukturierte Ein- und Ausgaben,
Freigaben,
Fehler und Abbrüche,
finale Antwort oder erzeugte Datei.

Dabei muss zwischen technischer Protokollierung und sichtbarer Chatantwort unterschieden werden. Nutzer benötigen eine verständliche Quellenangabe. Betreiber benötigen zusätzlich genug Informationen, um einen Fehler reproduzieren zu können.

Ein praktikables Freigabemodell

Für einen lokalen Einzelplatz- oder kleinen Team-Stack reicht zunächst ein einfaches Modell:

Stufe	Fähigkeit	Freigabe
1	Lesen und suchen	automatisch innerhalb des zulässigen Scopes
2	Dateien und Medien erzeugen	automatisch in definierten Zielbereichen
3	Systeme oder Daten verändern	ausdrückliche Bestätigung vor Ausführung
4	Extern veröffentlichen oder versenden	separate Bestätigung mit Zielprüfung

Diese Stufen können später technisch verfeinert werden. Wichtig ist zunächst, dass eine erfolgreiche Werkzeugauswahl niemals automatisch eine unbeschränkte Ausführungsberechtigung bedeutet.

Fazit

Ein zuverlässiger RAG-Agent entsteht nicht durch ein einzelnes Modell und auch nicht durch möglichst viele Werkzeuge. Er entsteht durch einen kontrollierten End-to-End-Prozess.

Quellen müssen freigegeben, Dokumente sinnvoll zerlegt und Embeddings konsistent erzeugt werden. Retrieval-Ergebnisse brauchen Scope-, Aktualitäts- und Qualitätsprüfungen. Werkzeuge benötigen minimale Rechte und strukturierte Verträge. Verändernde Aktionen müssen von der Antwortgenerierung getrennt und ausdrücklich freigegeben werden.

Die wichtigste Architekturentscheidung lautet deshalb: Autonomie wird nicht pauschal aktiviert, sondern für jede Fähigkeit begründet, begrenzt und getestet.