Ein Mitarbeiter sucht im Intranet nach Urlaubsregeln, eine Supportkraft beantwortet eine Anfrage, ein Nutzer fragt auf der Produktseite nach der Installation. Alle möchten dokumentengestützte Antworten direkt in ihrem Arbeitsablauf erhalten.
Die RAGO-X API bindet dokumentenbasierte Fragen und Antworten in solche Oberflächen ein. Ihr Dienst übernimmt Anmeldung und Benutzeroberfläche. RAGO-X verarbeitet RAG Chat für die Dokumentenschränke, die dem API-Schlüssel zugewiesen sind.
Dieser Artikel basiert auf dem Entwicklermenü und der externen Integrations-API. Die Szenarien und Fragen sind Beispiele, keine Ergebnisse eines Kundeneinsatzes. API-Zugriff ist derzeit ab Pro verfügbar. Prüfen Sie die Bedingungen unter Preise und im Entwicklermenü.
Anfrage und Antwortempfang sind getrennt
Die HTTP-Antwort auf eine Frage enthält nicht unmittelbar die fertige Antwort. Zunächst erhalten Sie eine task_id. Anschließend verbinden Sie sich mit dem Stream dieses Tasks, um das Ergebnis zu empfangen.
Oberfläche des bestehenden Dienstes
↓ Frage
Eigenes Backend — Anmeldung und Zugriffsprüfung
↓ Frage mit API-Schlüssel senden
RAGO-X API — Task annehmen und task_id zurückgeben
↓ SSE-Stream des Tasks öffnen
Eigenes Backend — Ergebnis empfangen und weiterleiten
↓
Benutzeroberfläche — Antwort und vorhandene Belege prüfen
Der Schlüssel bleibt auf dem Integrationsserver. Nutzer melden sich bei Ihrem Dienst an; der Browser benötigt den RAGO-X-Schlüssel nicht. Dieses Muster gilt für Intranet, Supportwerkzeuge und Produktoberflächen gleichermaßen.
Beispiel 1: ein Assistent für interne Richtlinien
Die Frage des Mitarbeiters
„Wie beantrage ich einen halben Tag Urlaub?“
Ergänzen Sie ein Fragefeld im Intranet und verbinden Sie einen Dokumentenschrank mit Personalrichtlinien. Beschäftigte können passende Erläuterungen direkt lesen, statt mehrere Dokumente zu öffnen.
So erfolgt die Anbindung
- Urlaubsregeln, Arbeitszeithinweise und Antragsverfahren in einem RAGO-X-Dokumentenschrank bereitstellen.
- Einen API-Schlüssel erstellen, der nur diesen Schrank erlaubt.
- Das Backend nimmt die Frage des angemeldeten Mitarbeiters entgegen und fordert RAG Chat an.
- Den Task-Stream empfangen und die Antwort im Intranet anzeigen.
- Zurückgegebene Belege anzeigen, damit die Originalrichtlinie überprüft werden kann.
Unterscheiden sich die Leserechte nach Person oder Abteilung, muss das Backend sie vor dem Senden prüfen. Der Geltungsbereich des API-Schlüssels entspricht nicht den Rechten einzelner Mitarbeiter. Eine vom Browser übergebene Schrank-UUID darf nicht ungeprüft übernommen werden.
Trennen Sie auch die Gespräche. Verwalten Sie die Beziehung zwischen Nutzer, Schrank und Gespräch im Backend und vergeben Sie für neue Gespräche eine eindeutige session_id. Verwenden Sie keinen festen gemeinsamen Wert für mehrere Personen.
API-Schlüssel vorbereiten und die erste Frage senden
Die drei Szenarien verwenden dieselben Endpunkte.
| Schritt | Methode und Pfad | Zweck |
|---|---|---|
| 1 | GET /api/v2/integrations/cabinets |
Für den Schlüssel erlaubte Schränke auflisten |
| 2 | POST /api/v2/integrations/cabinets/{cabinet_uuid}/rag-chat |
Frage an den ausgewählten Schrank senden |
| 3 | GET /api/v2/integrations/rag-chat/{task_id}/stream |
SSE-Antwort des Tasks empfangen |
1. Schlüssel im Entwicklermenü erstellen
Wählen Sie unter Entwickler → API-Schlüsselverwaltung einen verständlichen Namen, etwa „Intranet-Richtlinienassistent“, und nur die benötigten Dokumentenschränke.
Sie können ein Ablaufdatum sowie erlaubte Quell-IPs/CIDRs festlegen. Bei einem Server mit fester ausgehender IP lässt sich so der Ursprung einschränken. Eine leere Adressliste bedeutet, dass keine Quelladressbeschränkung besteht.
Der vollständige Schlüssel wird nur unmittelbar nach der Erstellung einmal angezeigt. Speichern Sie ihn in einem serverseitigen Secretspeicher, nicht in URLs, Frontendcode oder Browserspeichern. Der Login-JWT für die Schlüsselverwaltung ist vom API-Schlüssel für Integrationsanfragen zu unterscheiden.
Führen Sie die folgenden cURL-Beispiele auf dem Integrationsserver oder in einem Entwicklerterminal aus.
| Umgebungsvariable | Wert |
|---|---|
RAGO_X_API_BASE_URL |
Die für Ihre Umgebung angegebene API-Basisadresse ohne /api/v2 |
RAGO_X_API_KEY |
Der ausgestellte API-Schlüssel |
CABINET_UUID |
UUID aus der Liste erlaubter Schränke |
TASK_ID |
Bei der Frage zurückgegebene Task-ID |
Die Adresse der Landingpage ist keine API-Basisadresse. Maßgeblich sind die Verbindungsdaten und aktuellen Formate unter Entwickler → API-Nutzungsanleitung Ihrer Umgebung.
2. Erlaubte Dokumentenschränke abrufen
curl --fail-with-body --request GET \
--url "${RAGO_X_API_BASE_URL}/api/v2/integrations/cabinets" \
--header "Authorization: Bearer ${RAGO_X_API_KEY}"
Die Liste steht unter data.items. Jeder Eintrag enthält cabinet_uuid und name. Setzen Sie CABINET_UUID auf den vorgesehenen Schrank.
Ist die Liste leer, prüfen Sie zunächst die Schlüsselberechtigungen. Wählen Sie den Schrank serverseitig ausdrücklich aus, statt einfach den ersten Eintrag zu verwenden.
3. Frage senden und Task-ID erhalten
curl --fail-with-body --request POST \
--url "${RAGO_X_API_BASE_URL}/api/v2/integrations/cabinets/${CABINET_UUID}/rag-chat" \
--header "Authorization: Bearer ${RAGO_X_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"session_id": "hr-demo-conversation-001",
"question": "Wie beantrage ich einen halben Tag Urlaub?"
}'
session_id kennzeichnet das Gespräch, question enthält die Frage. Der feste Beispielwert dient nur einem einzelnen Tester. Ersetzen Sie ihn produktiv durch eine vom Backend vergebene Gesprächs-ID.
Übernehmen Sie die zurückgegebene task_id als TASK_ID. Task-Annahme und abgeschlossene Generierung sind verschiedene Zustände. Zeigen Sie zunächst die laufende Verarbeitung an und öffnen Sie den Stream.
4. Ergebnisse über SSE empfangen
curl --fail-with-body --no-buffer --request GET \
--url "${RAGO_X_API_BASE_URL}/api/v2/integrations/rag-chat/${TASK_ID}/stream" \
--header "Authorization: Bearer ${RAGO_X_API_KEY}" \
--header "Accept: text/event-stream"
Verwenden Sie denselben API-Schlüssel, mit dem die Frage übermittelt wurde. Ein anderer Schlüssel darf den Task nicht beliebig abrufen, selbst wenn beide zur gleichen Organisation gehören.
Der Stream verwendet derzeit subscribed zur Verbindungsbestätigung und message für Ergebnisse. Warten Sie nicht ausschließlich auf ein SSE-Ereignis namens final. Werten Sie type sowie Abschluss- und Fehlerinformationen innerhalb der JSON-Daten von message aus.
SSE trennt Ereignisse durch Leerzeilen. Ein gelesener Netzwerkblock entspricht nicht zwingend einem Ereignis. Puffern Sie die Daten und verarbeiten Sie vollständige Ereignisse. Auch Kommentarzeilen zur Verbindungserhaltung sind möglich.
Das native EventSource des Browsers kann keinen beliebigen Authorization-Header setzen. Das Backend empfängt den authentifizierten RAGO-X-Stream und leitet Ergebnisse passend an das Frontend weiter.
Beispiel 2: Antwortentwürfe im Support
Die Frage der Supportkraft
„Ein Kunde möchte die Lieferadresse ändern. Welche Vorgehensweise gilt je nach Versandstatus?“
Ein Button Entwurf aus Dokumenten neben der Kundenanfrage sendet die Frage an einen Schrank mit Supportrichtlinien und Betriebshandbüchern.
Entwurf und Geschäftsdaten gemeinsam prüfen
RAGO-X-Dokumente belegen Regeln und Abläufe. Aktuelle Zustände, etwa ob eine Bestellung versendet wurde, kommen aus dem Bestellsystem. Die API-Anbindung führt nicht automatisch Bestellabfragen oder Adressänderungen aus.
- Bestellstatus im vorhandenen System prüfen.
- Erforderlichen Kontext und Frage an RAGO-X senden.
- Antwort und Belege anzeigen.
- Die Supportkraft gleicht Richtlinie und tatsächlichen Zustand ab und bestätigt die Antwort.
Die Frage kann beispielsweise „bereits versendet“ enthalten. Unnötige Kontakt- oder Zahlungsdaten müssen nicht mitgesendet werden. Beschränken Sie den Kontext auf die Informationen, die für die Regelanwendung nötig sind.
Mit bearbeitbaren, von Menschen bestätigten Entwürfen lassen sich Ergebnisse und Betriebsregeln zunächst besser prüfen als mit sofortigen automatischen Kundenantworten.
Beispiel 3: Handbuchsuche direkt im Produkt
Die Frage des Nutzers
„Bei der ersten Verbindung tritt ein Authentifizierungsfehler auf. Welche Einstellungen soll ich prüfen?“
Ergänzen Sie im Einstellungsbereich ein Hilfefeld und verbinden Sie Installationsanleitungen, Fehlerhilfen und Betriebshandbücher in einem Dokumentenschrank.
Dokumente nach Produkt und Version auswählen
Müssen Produkte oder Versionen getrennt bleiben, verwenden Sie getrennte Schränke und lassen Sie das Backend den passenden auswählen. Die gezeigte Frage-API nimmt session_id und question entgegen. Beliebige zusätzliche Felder wie product_version sind nicht automatisch wirksame Filter.
Eine Versionsangabe in der Frage liefert Kontext, ersetzt aber weder die Schrankauswahl noch die Zugriffskontrolle.
Zeigen Sie Belege an, wenn sie zurückgegeben werden. Richten Sie Felder und Originalzugriff nach der Spezifikation Ihrer Umgebung aus. Öffentliche Download-URLs oder numerische Konfidenzwerte sind nicht in jeder Antwort garantiert. Bei unzureichenden Belegen sollte die Oberfläche Dokumentergänzungen oder den Kontakt zum Support ermöglichen.
Unterschiede der drei Szenarien
| Punkt | Richtlinienassistent | Supportentwurf | Handbuchsuche |
|---|---|---|---|
| Fragende Person | Angemeldeter Mitarbeiter | Supportkraft | Produktnutzer |
| Dokumente | Regeln und Anträge | Richtlinien und Handbücher | Installation und Fehlerbehebung |
| Prüfung durch eigenen Dienst | Individuelle Leserechte | Aktueller Geschäftszustand | Produkt, Version, Berechtigung |
| Anzeige | Intranet-Fragefeld | Entwurfsbereich im Support | Hilfe im Produkt |
| Anfangsprüfung | Gesprächstrennung | Bestätigung durch Supportkraft | Richtiger Dokumentenschrank |
Der API-Ablauf bleibt gleich. Entscheidend ist, welcher Schrank angeschlossen wird, was vorher geprüft wird und wo das Ergebnis erscheint.
Bei Fehlern nicht sofort dieselbe Anfrage wiederholen
Trennen Sie Fehler beim Einreichen von Fehlern während des Streamempfangs.
| Antwort oder Situation | Prüfung | Verhalten des eigenen Dienstes |
|---|---|---|
401 |
Fehlender oder ungültiger Schlüssel | Authentifizierung prüfen; vorübergehende Nichtverfügbarkeit anzeigen |
403 |
Schrank-/Task-Zugriff, Schlüssel- oder Quellrichtlinien | Fehlercode und Berechtigungen prüfen |
409 wegen fehlender Credits |
Verfügbare Organisationscredits | Weitere Anfragen stoppen; Administration informieren |
429 |
Aufruflimit | Gemäß Retry-After warten und Anfragemenge reduzieren |
400 oder 422 |
Schrankkonfiguration oder Anfragewerte | Pflichtfelder und Fehlermeldung prüfen |
503 |
Vorübergehend keine Verarbeitung | Begrenzte Wiederholungen und Störungshinweis |
| Abbruch nach Annahme | task_id und Abschlusszustand |
Bestehenden Task von einer neuen Anfrage unterscheiden |
Unbedachte Wiederholungen können mehrere Tasks erzeugen. Dieselbe session_id ist kein zugesicherter Idempotenzschlüssel.
Sollen Gespräche in Supporthistorien oder Auditansichten erhalten bleiben, planen Sie die Speicherung gesondert. Eine sichtbare Antwort bedeutet nicht, dass Ihr Geschäftssystem sie gespeichert hat.
Mit einem Schrank und einer Oberfläche beginnen
Wählen Sie zunächst einen Schrank und ein Fragefeld. Prüfen Sie echte Fragen, Antworten, Belege und Fehlerbehandlung vor der Erweiterung. Für Richtlinien eignen sich häufige Fragen zu Urlaub, Genehmigung und Nachweisen; für Produkthilfe Installationsschritte und typische Fehlermeldungen. Testen Sie auch Fragen ohne Antwort in den Dokumenten.
RAGO-X übernimmt dokumentenbasierte Fragen und Antworten. Ihr Dienst kennt Nutzer, Berechtigungen und Geschäftszustand. So bleiben die Zuständigkeiten klar.
Weitere Informationen bieten die Integrationsübersicht, der API-Anwendungsfall, die RAGO-X-Architektur und RAG-Chunking. Verbindungsdaten Ihrer Umgebung erhalten Sie im Entwicklermenü oder beim Support.
