Comment créer un agent conversationnel RAG avec une seule API de recherche de documents

Cette intégration de référence ajoute un chat privé consacré aux connaissances à un SaaS documentaire existant appelé KnowledgeBox. KnowledgeBox indexe déjà les fichiers et applique les autorisations des espaces de travail. Elle provisionne la documentation de son API de recherche dans AgentChat, crée une session limitée au locataire et laisse AgentChat décider quand et comment récupérer les éléments probants.

KnowledgeBox ne téléverse pas sa base de données documentaire dans AgentChat et ne reconstruit pas la récupération sous la forme d’un outil de modèle personnalisé. Sa propre API de recherche reste le seul service capable de lire le contenu client indexé.

Étape 1 : définir le contrat de recherche de KnowledgeBox

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"
}

L’API valide l’identifiant utilisateur injecté et filtre les résultats selon l’espace de travail autorisé avant la récupération. Elle renvoie des passages concis et des champs de citation, et non des documents privés complets. Un deuxième point de terminaison de lecture peut renvoyer une section précise lorsque l’agent a besoin de davantage de contexte.

Étape 2 : enregistrer les instructions de recherche complètes dans AgentChat

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."
  }'

L’UUID du document renvoyé est enregistré dans la configuration de KnowledgeBox. Le contenu complet du document est inclus dans les conversations qui le joignent, afin que l’agent connaisse les règles relatives à la requête et aux citations avant d’appeler l’API de recherche.

Étape 3 : créer une session RAG limitée à un espace de travail

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 crée une session AgentChat distincte pour chaque conversation utilisateur. Le même document de recherche est réutilisé, mais chaque session reçoit des en-têtes différents accessibles uniquement en écriture. Le modèle voit le contrat de l’API et le nom de l’espace de travail dans le prompt ; il ne voit jamais le jeton Bearer.

Étape 4 : envoyer la question de l’utilisateur

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 renvoie immédiatement l’état du traitement. Pendant l’exécution, l’agent appelle POST https://knowledge.example.com/v1/search via http_request. AgentChat fait correspondre le nom d’hôte et injecte les en-têtes de l’espace de travail avant d’envoyer la requête.

La séquence de récupération réelle

1. Rechercher des informations sur la suppression des données clients et la politique de suppression des sauvegardes.
2. Examiner les titres, les sections, les scores et les passages renvoyés par KnowledgeBox.
3. Si le comportement des sauvegardes est décrit de manière incomplète, effectuer une seconde recherche ciblée sur la conservation et la restauration des sauvegardes.
4. Lire éventuellement une section spécifique à l’aide de son identifiant plutôt que de récupérer un document complet.
5. Composer une réponse qui distingue la suppression immédiate des données primaires de l’expiration planifiée des sauvegardes.
6. Incluez le titre de la source et l’URL de la source renvoyés par l’API.

Les appels de recherche issus d’une même réponse du modèle peuvent s’exécuter en parallèle. Si la deuxième requête dépend de l’interprétation du premier résultat, elle doit être effectuée lors d’un tour ultérieur du modèle. AgentChat conserve chaque résultat d’outil, de sorte que la réponse finale repose sur les passages exacts reçus par l’agent.

Étape 5 : afficher la progression du chat dans KnowledgeBox

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

KnowledgeBox interroge son backend une fois par seconde. Il fusionne les lignes par ID de message et n’accepte une mise à jour que lorsque la révision augmente. Les messages des outils peuvent être affichés sous forme d’activité compacte « Recherche dans les connaissances de l’espace de travail », tandis que le contenu de l’assistant apparaît progressivement à partir de la ligne de message persistante adossée à la base de données.

La réponse finale reste intégrée à l’historique d’AgentChat. Les URL des sources citées renvoient vers KnowledgeBox, où la visionneuse de documents habituelle vérifie les autorisations de l’utilisateur actuel avant d’ouvrir la source.

Pourquoi il s’agit d’une intégration AgentChat plutôt que d’une démonstration RAG générique

• Le contrat de recherche est provisionné via /api/api-documents et associé à l’aide de l’UUID du document.
• Le modèle sélectionné, le prompt, les limites et les autorisations de l’API appartiennent à la session AgentChat.
• La récupération est exécutée par l’outil HTTP intégré, plutôt que par un outil de recherche personnalisé compilé dans l’agent.
• L’identité de l’utilisateur est injectée au moyen d’en-têtes de session spécifiques à l’hôte et n’est jamais divulguée au modèle.
• Le client KnowledgeBox consomme des messages persistants avec les curseurs after_id et after_revision.
• Les arrêts, les erreurs récupérables et les pauses dues à l’atteinte du nombre maximal de tours peuvent reprendre via le point de terminaison de continuation d’AgentChat.

Tests en production pour cette intégration