So erstellen Sie einen RAG-Chat-Agenten mit nur einer Dokumentsuch-API

Diese Referenzintegration fügt einem bestehenden Dokumenten-SaaS namens KnowledgeBox einen privaten Wissenschat hinzu. KnowledgeBox indiziert Dateien bereits und setzt Arbeitsbereichsberechtigungen durch. Die Integration stellt die Dokumentation der Such-API für KnowledgeBox in AgentChat bereit, erstellt eine mandantenbezogene Sitzung und lässt AgentChat entscheiden, wann und wie Belege abgerufen werden.

KnowledgeBox lädt seine Dokumentdatenbank nicht in AgentChat hoch und implementiert die Suche nicht als benutzerdefiniertes Modell-Tool neu. Die eigene Such-API bleibt der einzige Dienst, der auf indizierte Kundeninhalte zugreifen kann.

Schritt 1: Den KnowledgeBox-Suchvertrag definieren

POST /v1/search
{
  "query": "How long are audit logs retained?",
  "limit": 8,
  "filters": { "collection_ids": ["security"] }
}

→ {
  "results": [
    { "document_id": "doc_42", "title": "Security Policy", "section": "Audit retention", "text": "Audit logs are retained for...", "score": 0.91, "source_url": "/documents/doc_42#audit-retention" }
  ],
  "query_id": "qry_88"
}

Die API überprüft die übermittelten Benutzeranmeldedaten und filtert die Ergebnisse vor dem Abruf nach dem autorisierten Arbeitsbereich. Sie gibt kompakte Textpassagen und Zitationsfelder zurück, nicht vollständige private Dokumente. Ein zweiter Lese-Endpunkt kann einen bestimmten Abschnitt zurückgeben, wenn der Agent mehr Kontext benötigt.

Schritt 2: Die vollständigen Suchanweisungen in AgentChat registrieren

curl -X POST "$AGENT_CHAT_URL/api/api-documents" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "KnowledgeBox Search API",
    "description": "Search authorized workspace documents and return citable passages.",
    "content": "# KnowledgeBox Search API\nBase URL: https://knowledge.example.com/v1\n\nUse POST /search before answering questions about workspace knowledge. Send a focused natural-language query. Results are already permission-filtered. Cite title, section, and source_url. If results are weak, reformulate once. If results remain empty, say the documents do not contain the answer. Never claim a fact that is not supported by a returned passage.\n\nPOST /search body: query string required; limit integer 1-10; filters.collection_ids optional. Response results contain document_id, title, section, text, score, source_url.\n\nGET /documents/{document_id}/sections/{section_id} reads one authorized section when a search passage is incomplete."
  }'

Die zurückgegebene Dokument-UUID wird in der KnowledgeBox-Konfiguration gespeichert. Der vollständige Dokumentinhalt wird in Chats eingefügt, die das Dokument anhängen, sodass der Agent die Anfrage- und Zitationsregeln kennt, bevor er die Such-API aufruft.

Schritt 3: Eine auf den Arbeitsbereich beschränkte RAG-Sitzung erstellen

POST /api/agent/sessions
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{
  "title": "Workspace ws_17 knowledge assistant",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["knowledge_search_doc_uuid"],
  "system_prompt": "Answer from retrieved workspace evidence. Include source title and URL for factual claims.",
  "max_turns": 12,
  "host_headers": [
    { "host": "knowledge.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_workspace_user_token" },
    { "host": "knowledge.example.com", "header_key": "X-Workspace-ID", "header_value": "ws_17" }
  ]
}

KnowledgeBox erstellt für jede Unterhaltung eines Benutzers eine separate AgentChat-Sitzung. Dasselbe Suchdokument wird wiederverwendet, aber jede Sitzung erhält andere Nur-Schreib-Header. Das Modell sieht den API-Vertrag und den Namen des Arbeitsbereichs im Prompt; das Bearer-Token bekommt es nie zu sehen.

Schritt 4: Die Frage des Benutzers senden

POST /api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{ "message": "Can customer data be removed from backups immediately? Please cite the policy." }

AgentChat gibt sofort den Status „Verarbeitung“ zurück. Während der Ausführung ruft der Agent über http_request POST https://knowledge.example.com/v1/search auf. AgentChat erkennt den Hostnamen und fügt die Workspace-Header ein, bevor die Anfrage gesendet wird.

Die eigentliche Abrufsequenz

1. Nach Informationen zur Löschung von Kundendaten und zur Richtlinie für die Löschung von Sicherungskopien suchen.
2. Die von KnowledgeBox zurückgegebenen Titel, Abschnitte, Bewertungen und Textpassagen prüfen.
3. Wenn das Verhalten bei Sicherungskopien unvollständig beschrieben ist, eine zweite gezielte Suche nach der Aufbewahrung und Wiederherstellung von Sicherungskopien durchführen.
4. Optional einen bestimmten Abschnitt anhand seiner ID lesen, anstatt ein vollständiges Dokument abzurufen.
5. Eine Antwort formulieren, die zwischen der sofortigen Löschung der Primärdaten und dem planmäßigen Ablauf der Sicherungskopien unterscheidet.
6. Fügen Sie den vom API zurückgegebenen Quellentitel und die Quell-URL ein.

Suchaufrufe aus einer einzelnen Modellantwort können gleichzeitig ausgeführt werden. Wenn die zweite Abfrage von der Interpretation des ersten Ergebnisses abhängt, muss sie in einem späteren Modellturn erfolgen. AgentChat speichert jedes Tool-Ergebnis, sodass die endgültige Antwort auf den exakten Passagen basiert, die der Agent erhalten hat.

Schritt 5: Chat-Fortschritt in KnowledgeBox darstellen

GET /api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENT_CHAT_KEY

KnowledgeBox fragt einmal pro Sekunde über sein Backend ab. Es führt Zeilen anhand der Nachrichten-ID zusammen und akzeptiert eine Aktualisierung nur, wenn die Revision höher ist. Tool-Nachrichten können als kompakte Aktivität „Arbeitsbereichswissen wird durchsucht“ angezeigt werden, während der Inhalt des Assistenten schrittweise aus der dauerhaft in der Datenbank gespeicherten Nachrichtenzeile erscheint.

Die endgültige Antwort bleibt Teil des AgentChat-Verlaufs. Die zitierten Quell-URLs führen zurück zu KnowledgeBox, wo der normale Dokument-Viewer vor dem Öffnen der Quelle die Berechtigung des aktuellen Benutzers prüft.

Warum dies eine AgentChat-Integration und keine generische RAG-Demo ist

• Der Suchvertrag wird über /api/api-documents bereitgestellt und anhand der Dokument-UUID angehängt.
• Das ausgewählte Modell, der Prompt, die Limits und die API-Berechtigungen gehören zur AgentChat-Sitzung.
• Der Abruf wird vom integrierten HTTP-Tool ausgeführt und nicht von einem benutzerdefinierten Suchtool, das in den Agenten einkompiliert wurde.
• Die Benutzeridentität wird durch hostspezifische Sitzungs-Header eingefügt und dem Modell niemals offengelegt.
• Der KnowledgeBox-Client verarbeitet dauerhafte Nachrichten mit after_id- und after_revision-Cursors.
• Stopps, behebbare Fehler und Pausen nach Erreichen der maximalen Zuganzahl können über den AgentChat-Continue-Endpunkt fortgesetzt werden.

Produktionstests für diese Integration