Cómo crear un agente de chat RAG con una sola API de búsqueda de documentos

Esta integración de referencia añade un chat privado de conocimiento a un SaaS de documentos existente llamado KnowledgeBox. KnowledgeBox ya indexa archivos y aplica los permisos del espacio de trabajo. Aprovisiona la documentación de su API de búsqueda en AgentChat, crea una sesión limitada al inquilino y permite que AgentChat decida cuándo y cómo recuperar evidencias.

KnowledgeBox no carga su base de datos de documentos en AgentChat ni reconstruye la recuperación como una herramienta de modelo personalizada. Su propia API de búsqueda sigue siendo el único servicio que puede leer el contenido de clientes indexado.

Paso 1: definir el contrato de búsqueda 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"
}

La API valida la credencial de usuario inyectada y filtra por el espacio de trabajo autorizado antes de la recuperación. Devuelve pasajes concisos y campos de citación, no documentos privados completos. Un segundo endpoint de lectura puede devolver una sección específica cuando el agente necesita más contexto.

Paso 2: registrar las instrucciones de búsqueda completas en 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."
  }'

El UUID del documento devuelto se guarda en la configuración de KnowledgeBox. El contenido completo del documento se incluye en los chats que lo adjuntan, de modo que el agente conoce las reglas de solicitud y citación antes de llamar a la API de búsqueda.

Paso 3: crear una sesión de RAG con alcance limitado al espacio de trabajo

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 sesión de AgentChat independiente para cada conversación de usuario. Se reutiliza el mismo documento de búsqueda, pero cada sesión recibe encabezados de solo escritura diferentes. El modelo ve el contrato de la API y el nombre del espacio de trabajo en el prompt; nunca ve el token de portador.

Paso 4: enviar la pregunta del usuario

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 devuelve inmediatamente el estado de procesamiento. Durante la ejecución, el agente realiza una llamada POST a https://knowledge.example.com/v1/search mediante http_request. AgentChat identifica el nombre de host e inyecta los encabezados del espacio de trabajo antes de enviar la solicitud.

La secuencia de recuperación real

1. Buscar información sobre la eliminación de datos de clientes y la política de eliminación de copias de seguridad.
2. Inspeccionar los títulos, las secciones, las puntuaciones y los pasajes devueltos por KnowledgeBox.
3. Si el comportamiento de las copias de seguridad está descrito de forma incompleta, realizar una segunda búsqueda específica sobre la retención y la restauración de copias de seguridad.
4. Opcionalmente, leer una sección específica por su ID en lugar de recuperar un documento completo.
5. Redactar una respuesta que distinga entre la eliminación inmediata de los datos primarios y la expiración programada de las copias de seguridad.
6. Incluye el título de la fuente y la URL de la fuente devueltos por la API.

Las llamadas de búsqueda de una misma respuesta del modelo pueden ejecutarse de forma simultánea. Si la segunda consulta depende de la interpretación del primer resultado, debe realizarse en un turno posterior del modelo. AgentChat conserva cada resultado de herramienta, por lo que la respuesta final se basa en los pasajes exactos que recibió el agente.

Paso 5: mostrar el progreso del chat en KnowledgeBox

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

KnowledgeBox consulta su backend una vez por segundo. Fusiona las filas por ID de mensaje y acepta una actualización solo cuando aumenta la revisión. Los mensajes de las herramientas pueden mostrarse como una actividad compacta de «Buscando en el conocimiento del espacio de trabajo», mientras que el contenido del asistente aparece progresivamente a partir de la fila de mensaje persistente respaldada por la base de datos.

La respuesta final sigue formando parte del historial de AgentChat. Las URL de las fuentes citadas apuntan de nuevo a KnowledgeBox, donde el visor de documentos habitual comprueba los permisos del usuario actual antes de abrir la fuente.

Por qué esto es una integración de AgentChat y no una demostración genérica de RAG

• El contrato de búsqueda se aprovisiona a través de /api/api-documents y se adjunta mediante el UUID del documento.
• El modelo seleccionado, el prompt, los límites y los permisos de la API pertenecen a la sesión de AgentChat.
• La recuperación se ejecuta mediante la herramienta HTTP integrada, en lugar de una herramienta de búsqueda personalizada compilada en el agente.
• La identidad del usuario se inyecta mediante encabezados de sesión específicos del host y nunca se revela al modelo.
• El cliente de KnowledgeBox consume mensajes duraderos con cursores after_id y after_revision.
• Las detenciones, los errores recuperables y las pausas al alcanzar el máximo de turnos pueden reanudarse mediante el endpoint de continuación de AgentChat.

Pruebas en producción para esta integración