Come creare un agente di chat RAG con una sola API di ricerca documentale

Questa integrazione di riferimento aggiunge una chat privata basata sulla conoscenza a un SaaS per documenti esistente chiamato KnowledgeBox. KnowledgeBox indicizza già i file e applica le autorizzazioni degli spazi di lavoro. Esegue il provisioning della documentazione della sua API di ricerca in AgentChat, crea una sessione con ambito limitato al tenant e lascia che sia AgentChat a decidere quando e come recuperare le informazioni probatorie.

KnowledgeBox non carica il proprio database di documenti in AgentChat e non ricostruisce il recupero come strumento personalizzato del modello. La sua API di ricerca rimane l'unico servizio in grado di leggere i contenuti dei clienti indicizzati.

Passaggio 1: definire il contratto di ricerca di 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 convalida la credenziale utente iniettata e filtra in base all'area di lavoro autorizzata prima del recupero. Restituisce passaggi concisi e campi di citazione, non documenti privati completi. Un secondo endpoint di lettura può restituire una sezione specifica quando l'agente ha bisogno di maggiore contesto.

Passaggio 2: registrare le istruzioni di ricerca complete in 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 del documento restituito viene salvato nella configurazione di KnowledgeBox. Il contenuto completo del documento viene incluso nelle chat che lo allegano, così l'agente conosce le regole relative alla richiesta e alle citazioni prima di chiamare l'API di ricerca.

Passaggio 3: creare una sessione RAG con ambito limitato all'area di lavoro

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 crea una sessione AgentChat separata per ogni conversazione dell’utente. Viene riutilizzato lo stesso documento di ricerca, ma ogni sessione riceve intestazioni diverse di sola scrittura. Il modello vede il contratto dell’API e il nome dell’area di lavoro nel prompt; non vede mai il bearer token.

Passaggio 4: inviare la domanda dell’utente

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 restituisce immediatamente lo stato di elaborazione. Durante l’esecuzione, l’agente chiama POST https://knowledge.example.com/v1/search tramite http_request. AgentChat identifica il nome host e inserisce le intestazioni dell’area di lavoro prima di inviare la richiesta.

La sequenza effettiva di recupero

1. Cercare informazioni sulla rimozione dei dati dei clienti e sulla policy di eliminazione dei backup.
2. Esaminare i titoli, le sezioni, i punteggi e i passaggi restituiti da KnowledgeBox.
3. Se il comportamento dei backup è descritto in modo incompleto, eseguire una seconda ricerca mirata sulla conservazione e sul ripristino dei backup.
4. Facoltativamente, leggere una sezione specifica tramite il relativo ID invece di recuperare un documento completo.
5. Comporre una risposta che distingua tra l’eliminazione immediata dei dati primari e la scadenza programmata dei backup.
6. Includi il titolo della fonte e l’URL della fonte restituiti dall’API.

Le chiamate di ricerca provenienti da una singola risposta del modello possono essere eseguite contemporaneamente. Se la seconda query dipende dall’interpretazione del primo risultato, deve essere eseguita in un turno successivo del modello. AgentChat conserva ogni risultato dello strumento, quindi la risposta finale si basa sui passaggi esatti ricevuti dall’agente.

Passaggio 5: visualizzare l’avanzamento della chat in KnowledgeBox

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

KnowledgeBox interroga il proprio backend una volta al secondo. Unisce le righe in base all’ID del messaggio e accetta un aggiornamento solo quando la revisione aumenta. I messaggi degli strumenti possono essere mostrati come attività compatta «Ricerca nella knowledge base dell’area di lavoro», mentre il contenuto dell’assistente appare progressivamente dalla riga del messaggio persistente supportata dal database.

La risposta finale rimane parte della cronologia di AgentChat. Gli URL delle fonti citate rimandano a KnowledgeBox, dove il normale visualizzatore di documenti verifica le autorizzazioni dell’utente corrente prima di aprire la fonte.

Perché questa è un’integrazione di AgentChat anziché una demo RAG generica

• Il contratto di ricerca viene fornito tramite /api/api-documents e associato tramite l'UUID del documento.
• Il modello selezionato, il prompt, i limiti e le autorizzazioni API appartengono alla sessione AgentChat.
• Il recupero viene eseguito dallo strumento HTTP integrato, anziché da uno strumento di ricerca personalizzato compilato nell'agente.
• L'identità dell'utente viene inserita tramite intestazioni di sessione specifiche dell'host e non viene mai divulgata al modello.
• Il client KnowledgeBox consuma messaggi persistenti con i cursori after_id e after_revision.
• Le interruzioni, gli errori recuperabili e le pause al raggiungimento del numero massimo di turni possono essere ripresi tramite l'endpoint di continuazione di AgentChat.

Test di produzione per questa integrazione