Espacios de conocimiento dinámicos: contexto de IA actual, estructurado y trazable
Los Knowledge Spaces de Claix ahora son dinámicos. Añade documentos procesados, quita fuentes obsoletas y sustituye contenido conservando document_id estables y trazabilidad.
Los Knowledge Spaces de Claix ahora son dinámicos. Puedes añadir un documento ya procesado a un Knowledge Space, quitar un documento sin eliminar su contexto persistente, o sustituir el contenido de un documento conservando el mismo document_id estable.
Eso significa que un Knowledge Space de Claix ya no es una colección estática de archivos añadidos en la ingesta. Puede evolucionar a medida que cambia la información de tu negocio.
Llega una nueva fuente
↓
Procesarla con Claix
↓
Añadirla al Knowledge Space correspondiente
La fuente deja de ser relevante
↓
Quitarla del Knowledge Space
↓
Mantener el documento disponible de forma independiente
La fuente se corrige o actualiza
↓
Procesar la fuente de reemplazo
↓
Sustituir el contenido del documento existente
↓
Conservar el mismo document_id y la pertenencia al Knowledge SpaceImporta porque los agentes de IA, las aplicaciones, las automatizaciones y los flujos de recuperación solo son tan fiables como el contexto al que pueden acceder. Si un Knowledge Space contiene facturas desactualizadas, contratos obsoletos, políticas superadas, hojas de cálculo antiguas o documentos duplicados, un agente puede recuperar información técnicamente relevante pero operativamente incorrecta.
Las nuevas APIs de gestión de Knowledge Spaces de Claix permiten mantener una capa de contexto viva, actual y consultable sin reconstruir un espacio entero cada vez que cambia un archivo.
El problema de la frescura del conocimiento
La mayoría de los sistemas de knowledge base para IA tienen una debilidad oculta.
Funcionan bien en la primera demo:
Subir documentos
↓
Hacer una pregunta
↓
Obtener una respuestaPero la información real de negocio cambia constantemente.
- Un proveedor envía una factura corregida.
- Se modifica un contrato.
- Se actualiza una lista de precios.
- Se publica una nueva versión de una política operativa.
- Un cliente sube un documento de reemplazo.
- Se corrige una exportación de hoja de cálculo.
- Una nota de voz se sustituye por una grabación más clara.
- Un documento se asigna al proyecto o cliente equivocado.
- Un archivo que antes era relevante ya no debería influir en respuestas cruzadas.
Si el contenido antiguo sigue activo en una knowledge base, el agente puede recuperar información desactualizada.
Valor antiguo del contrato
+ valor de la factura nueva
+ lista de precios obsoleta
↓
El agente recibe contexto conflictivo
↓
El agente da una respuesta plausible pero incorrectaEsto no es solo un problema de recuperación.
Es un problema de gobernanza de datos.
Un Knowledge Space debe poder responder:
¿Qué fuentes están activas ahora?
¿Cuál es el documento autoritativo?
¿Qué versión de este documento debe usar un agente?
¿Cuándo se actualizó por última vez esta fuente?
¿Se eliminó un documento obsoleto del razonamiento cruzado?
¿Un reemplazo preservó la identidad del documento usada por los flujos existentes?Los sistemas de producción de RAG y agentes de IA necesitan controles de frescura, versionado, linaje y deprecación. Cuando siguen disponibles varias versiones activas de la misma fuente, la recuperación puede elegir una versión obsoleta aunque el modelo de recuperación se comporte correctamente.
Claix ahora ofrece a los desarrolladores controles de API directos para gestionar este ciclo de vida.
¿Qué cambia con los Knowledge Spaces dinámicos?
Antes, la relación de un documento con un Knowledge Space se decidía principalmente durante la extracción.
Procesar un documento con space_id
↓
El documento pasa a formar parte del Knowledge Space
↓
Consultar el Knowledge Space más adelanteSigue siendo el enfoque más rápido cuando ya sabes dónde pertenece una fuente.
Pero los flujos de negocio no siempre son predecibles.
A veces un documento se procesa primero y se categoriza después. A veces hay que moverlo entre contextos. A veces se corrige el archivo original. A veces el mismo registro de negocio debe conservar un identificador estable mientras cambia su contenido subyacente.
Claix ahora admite tres operaciones para esa realidad:
| Operación | Qué hace | Por qué importa |
|---|---|---|
| Añadir un documento a un Knowledge Space | Asigna un documento ya procesado a un space_id | Organizar fuentes después de la extracción |
| Quitar un documento de un Knowledge Space | Pone el space_id del documento a null sin eliminarlo | Eliminar contexto obsoleto o irrelevante con seguridad |
| Sustituir el contenido del documento | Reemplaza el contenido de un documento estable con una fuente recién procesada | Mantener el contexto actual sin cambiar el document_id original |
Estas llamadas son gratuitas. No consumen créditos de extracción ni de Context Window.
El resultado es un Knowledge Space que se comporta menos como una carpeta estática de subidas y más como una capa de fuente de verdad mantenida para aplicaciones, flujos y agentes de IA.
Añadir un documento existente a un Knowledge Space
Procesar primero, organizar después
Un flujo habitual se ve así:
El cliente sube un PDF
↓
Tu aplicación lo procesa con Claix
↓
Claix devuelve datos estructurados y un document_id
↓
Tu flujo determina a qué proveedor, proyecto, caso o cuenta pertenece
↓
Añadir el documento existente al Knowledge Space correctoEs útil cuando la clasificación ocurre después de la extracción.
Por ejemplo:
- Un backend recibe documentos antes de saber la cuenta de cliente relevante.
- Una automatización recibe archivos por email y los clasifica más tarde.
- Un flujo extrae primero la información del proveedor y luego asigna la fuente a un Knowledge Space de proveedor.
- Un revisor humano decide a qué proyecto pertenece un documento.
- Un agente identifica el caso, proveedor o contexto de cliente adecuado después de leer el resultado extraído.
Usa:
POST https://claix.dev/add-spaceCon:
{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}Una respuesta correcta confirma que el documento ya forma parte del Knowledge Space:
{
"success": true,
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
"space_name": "Suppliers 2026",
"file_name": "invoice.pdf",
"version": 1,
"message": "Document added to Knowledge Space."
}A partir de ese momento, el documento participa en las consultas cruzadas de ese espacio.
Por qué importa la asignación posterior al procesamiento
Muchas plataformas documentales asumen que la categorización ocurre antes o durante la ingesta.
Eso no siempre es cómo funcionan los sistemas reales.
Considera una aplicación SaaS multi-tenant:
Llega un documento nuevo
↓
Ningún usuario lo ha asignado aún a un proyecto
↓
Claix extrae proveedor, cliente, número de contrato y datos de referencia
↓
Tu lógica de negocio identifica la cuenta correcta
↓
El documento se añade al Knowledge Space correspondienteEl mismo patrón sirve para:
Documento recibido
↓
Extraer datos
↓
Clasificar según el resultado
↓
Asignar al espacioEs más flexible que obligar a que cada fuente tenga un destino fijo antes de que el sistema entienda qué contiene.
Un documento puede extraerse una vez, persistir su contexto y organizarse después en el Knowledge Space donde resulta útil.
Quitar un documento de un Knowledge Space
Quitar contexto sin eliminar el documento
Un documento no necesita borrarse de forma permanente solo porque ya no deba influir en el razonamiento cruzado.
Por ejemplo:
- Un documento se adjuntó al proveedor equivocado.
- Un contrato ya no pertenece al espacio activo del proyecto.
- Una factura duplicada no debe afectar a los totales del proveedor.
- Un archivo de cliente debe salir de un contexto específico de caso.
- Un documento necesita revisión antes de reclasificarse.
- Un flujo debe dejar de usar una fuente en respuestas cruzadas pero conservarla para auditoría o consultas directas.
Claix ahora permite quitar un documento de su Knowledge Space actual manteniendo el documento persistente disponible.
Usa:
DELETE https://claix.dev/remove-document-from-space/{document_id}El endpoint también acepta POST para clientes que no pueden enviar peticiones DELETE.
Ejemplo:
DELETE https://claix.dev/remove-document-from-space/d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4bTras una respuesta correcta:
{
"success": true,
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"previous_space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c",
"space_id": null,
"file_name": "invoice.pdf",
"version": 1,
"message": "Document removed from Knowledge Space. It no longer has a space_id."
}- El documento sigue existiendo.
- Su document_id sigue funcionando.
- Su contexto persistente permanece disponible.
- Puedes seguir consultándolo directamente mediante el contexto del documento.
Lo único que cambia es esto:
El documento ya no participa en las consultas del Knowledge Space.Por qué quitar es más seguro que borrar
Una operación destructiva de borrado no es la respuesta correcta para cada cambio de gestión del conocimiento.
Hay una diferencia importante entre:
Eliminar la fuente de forma permanentey:
Quitar la fuente de este grupo de documentos relacionadosCon Claix:
| Acción | Documento persistente | Contexto directo del documento | Consultas del Knowledge Space |
|---|---|---|---|
| Quitar del Knowledge Space | Se conserva | Disponible | Excluido |
| Sustituir contenido del documento | Se conserva con el mismo document_id | Actualizado | Usa el contenido actualizado |
| Eliminar documento | Eliminado | No disponible | Excluido |
Quitar un documento de un Knowledge Space es, por tanto, útil para una reclasificación segura.
Quitar del espacio actual
↓
Revisar o clasificar el documento
↓
Opcionalmente añadirlo a otro espacioAsí se evita el contexto obsoleto y el razonamiento duplicado accidental, conservando la fuente original para investigación, cumplimiento o reutilización posterior.
Sustituir un documento sin cambiar su document_id
Conservar la identidad estable al actualizar el contenido
La operación nueva más importante es el reemplazo de documentos.
Un documento puede estar referenciado por:
- Una base de datos de aplicación.
- Un registro de CRM.
- Un caso de cliente.
- Un flujo de aprobación.
- Una tarea de un agente de IA.
- Un cliente MCP.
- Una tarea A2A.
- Un ticket de soporte.
- Un Knowledge Space.
- Una entrada de log.
- Una regla de negocio.
- Una cola de revisión humana.
Si el documento se actualiza, obligar a todos los sistemas posteriores a adoptar un document_id nuevo crea una complejidad innecesaria.
Claix ahora permite sustituir el contenido de un documento persistente conservando el document_id estable.
Usa:
POST https://claix.dev/replace-documentCuerpo de la petición:
{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}El flujo está pensado para un patrón de reemplazo sencillo:
1. Procesa la nueva fuente con normalidad.
2. Recibe un new_content_document_id temporal.
3. Sustituye el contenido del documento estable.
4. Sigue usando el document_id original en todas partes.El documento fuente aporta su contenido procesado y su nombre de archivo al documento estable. Tras un reemplazo correcto, el documento fuente se elimina.
Documento estable existente
document_id: doc_A
↓
Fuente de reemplazo recién procesada
document_id: doc_B
↓
Claix sustituye el contenido de doc_A con el de doc_B
↓
doc_A sigue siendo el document_id estable
doc_B se eliminaLa pertenencia de doc_A al Knowledge Space permanece intacta.
Por qué importan los document_id estables
Los identificadores estables importan siempre que otro sistema almacene referencias.
Imagina un Knowledge Space de proveedor que contiene:
Contrato del proveedor
Pedido de compra
Factura
Lista de preciosTu flujo puede estar usando ya:
document_id = supplier-invoice-recordpara:
- Consultas directas al documento.
- Conciliación cruzada entre documentos.
- Flujos de aprobación financiera.
- Logs de auditoría.
- Citas de fuente.
- Páginas de estado orientadas al cliente.
- Referencias internas.
- Estado de tareas del agente.
Ahora el proveedor envía una factura corregida.
Sin soporte de reemplazo, tendrías que:
Procesar la factura corregida
↓
Recibir un document_id nuevo
↓
Quitar el documento antiguo del Knowledge Space
↓
Añadir el documento nuevo al Knowledge Space
↓
Actualizar cada referencia almacenada
↓
Actualizar cada flujo
↓
Asegurar que la fuente antigua ya no influya en las consultasCon el reemplazo de documentos de Claix:
Procesar la factura corregida
↓
Recibir un ID de documento temporal
↓
Sustituir el contenido del documento estable existente
↓
Seguir usando el document_id original- El flujo puede conservar sus referencias intactas.
- El Knowledge Space puede conservar su pertenencia intacta.
- El contexto del documento sigue siendo direccionable con el mismo identificador.
Es un modelo mucho mejor para sistemas en los que los documentos forman parte de un proceso de negocio continuo y no de subidas puntuales.
Qué conserva el reemplazo de documentos
Cuando sustituyes un documento de Claix, el documento de destino conserva su identidad estable.
Se conserva:
- document_id
- pertenencia al Knowledge Space
- referencias posteriores
- relaciones a nivel de aplicación
- identidad de negocio existenteEl reemplazo actualiza el contenido fuente que Claix usa para contexto y razonamiento.
Se actualiza:
- nombre de archivo
- contenido procesado
- datos estructurados extraídos
- contexto documental usado para el razonamiento
- evidencia de fuente
- metadatos del documento derivados de la fuente de reemplazo
- versión activa del documentoLa respuesta incluye un número de versión nuevo:
{
"success": true,
"swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"source_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c",
"file_name": "corrected-invoice.pdf",
"version": 2,
"swaps_count": 1,
"message": "Content replaced. The source document was deleted."
}- El swap_id da a la operación de reemplazo un identificador trazable.
- La version indica a los sistemas posteriores que el contenido detrás del document_id estable ha cambiado.
- El swaps_count permite entender cuántas veces se ha actualizado el documento estable.
Los Knowledge Spaces dinámicos evitan el contexto obsoleto del agente
El conocimiento estático es un riesgo operativo
Un Knowledge Space estático acumula problemas con el tiempo:
Factura original
+ factura corregida
+ contrato obsoleto
+ hoja de cálculo duplicada
+ lista de precios antigua
↓
Contexto conflictivo
↓
Recuperación poco fiable
↓
Respuesta incorrecta del agenteSi un agente de IA ve la factura antigua y la corregida, puede:
- Usar el importe equivocado.
- Sumar ambos valores.
- Citar la fuente superada.
- Tratar condiciones antiguas como actuales.
- Identificar una discrepancia falsa.
- Dar una respuesta correcta para la versión equivocada de la realidad.
Por eso importa la gestión dinámica del Knowledge Space.
El objetivo no es solo dejar que los usuarios muevan archivos.
El objetivo es mantener un conjunto actual y autoritativo de fuentes para el razonamiento del agente.
La fuente relevante entra en el espacio
↓
La fuente obsoleta sale del espacio
↓
La fuente corregida sustituye el contenido antiguo
↓
Las consultas usan la fuente de verdad actualLa fiabilidad de una knowledge base depende en gran medida de la frescura, el linaje de las fuentes, el contenido activo frente al deprecado y la eliminación de versiones obsoletas de la recuperación. Varias versiones activas del mismo registro de negocio pueden hacer que los agentes recuperen información desactualizada o contradictoria.
Ejemplo: conciliación de facturas de proveedor
Un flujo de compras procesa:
supplier-contract.pdf
purchase-order.pdf
invoice-march.pdf
price-list.xlsxTodas las fuentes pertenecen a:
Knowledge Space: Proveedor A — 2026Un agente pregunta:
¿La factura de marzo coincide con el precio acordado en el contrato?Al principio, la respuesta usa:
supplier-contract.pdf
+ purchase-order.pdf
+ invoice-march.pdf
+ price-list.xlsxMás tarde, el proveedor emite una factura corregida.
Un flujo estático de knowledge base crearía un segundo registro de factura:
invoice-march.pdf
invoice-march-corrected.pdfAhora el Knowledge Space contiene dos versiones del mismo registro de negocio.
Un flujo dinámico con Claix hace esto en su lugar:
1. Procesar invoice-march-corrected.pdf.
2. Recibir el ID temporal del documento fuente.
3. Llamar a POST /replace-document.
4. Conservar el document_id original de la factura.
5. Incrementar la versión del documento.
6. Eliminar el documento fuente temporal.
7. Mantener la misma pertenencia al Knowledge Space.El agente ahora ve un único registro activo de la factura de marzo con contenido actualizado.
Eso reduce el contexto duplicado y conserva la relación de negocio estable entre la factura y el resto del espacio del proveedor.
Ejemplo: gestión de casos de cliente
Una aplicación de soporte al cliente mantiene un Knowledge Space por caso:
Caso 4382
↓
Emails del cliente
Capturas de soporte
Notas de voz
Contratos
Facturas
Informes internosUn agente de soporte puede preguntar:
¿Qué se le ha dicho ya al cliente sobre el reembolso?
¿Qué factura está en disputa?
¿Se prometió una fecha de entrega?
¿Qué documentos respaldan la reclamación del cliente?Con el tiempo:
- Se sube una captura al caso equivocado.
- Hay que reclasificar una nota de voz.
- Un cliente envía un formulario corregido.
- Un resumen interno de soporte se sustituye por una versión final.
Los Knowledge Spaces dinámicos permiten a la aplicación gestionar ese contexto sin borrar todo y reconstruir el caso desde cero.
Captura incorrecta
↓
Quitar del Knowledge Space
Formulario corregido
↓
Procesar el reemplazo
↓
Sustituir el contenido del documento original
Nuevo adjunto de soporte
↓
Procesar
↓
Añadir al Knowledge SpaceEl Knowledge Space permanece actual y útil para los agentes durante todo el ciclo de vida del caso.
Contexto dinámico para aplicaciones, flujos y agentes
Los Knowledge Spaces son útiles para agentes de IA, pero no solo para agentes.
Pueden apoyar cualquier sistema que necesite contexto actual y cruzado entre fuentes.
Aplicaciones backend
Un backend puede mantener una referencia estable al documento:
document_idmientras permite actualizar el contenido fuente.
Por ejemplo:
Registro de cliente
↓
document_id almacenado en la base de datos
↓
El cliente sube una fuente corregida
↓
Llamada de reemplazo a Claix
↓
La referencia existente en la base de datos sigue siendo válidaEl backend no necesita actualizar claves foráneas ni rehacer relaciones en toda la aplicación.
Flujos de automatización
n8n, Make, Zapier y automatizaciones a medida a menudo necesitan reaccionar a entradas de negocio que cambian.
Un flujo puede:
Procesar la nueva fuente
↓
Comprobar si sustituye un registro existente
↓
Llamar a replace-document
↓
Consultar el Knowledge Space actualizado
↓
Continuar con los datos actualesO:
Clasificar la fuente procesada
↓
Añadirla a un Knowledge Space
↓
Hacer preguntas cruzadas entre documentos
↓
Enviar discrepancias a revisiónAgentes de IA
Un agente puede trabajar con un Knowledge Space que refleja el estado operativo actual, no un montón histórico de archivos.
El agente pregunta:
"¿Cuál es el precio actual del contrato?"
Knowledge Space:
Contiene solo el contenido activo y actual de las fuentes
El agente recibe:
Una respuesta fundamentada en los documentos actualesEso es crítico para flujos de agentes que involucran:
- Pagos.
- Compras.
- Contratos.
- Soporte al cliente.
- Cumplimiento.
- Operaciones.
- Gestión de proveedores.
- Onboarding.
- Due diligence.
- Gestión de casos.
- Conciliación financiera.
Reemplazo de documentos y trazabilidad
Dinámico no significa sin trazabilidad.
Una preocupación habitual al sustituir contenido es:
Si el documento cambia, ¿cómo sabemos qué ocurrió?Claix devuelve un swap_id por cada operación de reemplazo:
{
"swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c"
}Identifica el evento de sustitución de contenido.
La respuesta también incluye:
document_id
source_document_id
version
swaps_count
file_nameEso da a las aplicaciones trazabilidad operativa:
Identidad estable del documento:
document_id
Fuente de reemplazo:
source_document_id
Operación de reemplazo:
swap_id
Versión actual del contenido:
version
Número total de reemplazos:
swaps_countLa version del documento aumenta tras cada reemplazo.
Versión 1
↓
Fuente corregida procesada
↓
Versión 2
↓
Fuente actualizada procesada de nuevo
↓
Versión 3Así un flujo sabe que el contenido detrás de un document_id estable ha cambiado.
Un sistema fiable debería registrar ese cambio junto a sus propios eventos de negocio:
{
"workflow_run_id": "supplier-reconciliation-2026-09-25-0081",
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"document_version": 2,
"claix_swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
"action": "reconcile_corrected_invoice"
}Es especialmente útil cuando un agente o una automatización toma decisiones basadas en fuentes que cambian.
Source tracing después de un reemplazo
El source tracing de Claix aporta evidencia para campos extraídos y respuestas a consultas.
Para un PDF, la evidencia de fuente puede referirse a:
- Página
- Párrafo
- Cláusula
- Tabla
- Fragmento de texto
Para una hoja de cálculo:
- Columna
- Fila
- Celda de origen
Para audio:
- Segundo
- Rango temporal
- Fragmento hablado
Tras el reemplazo, el document_id estable permanece igual, pero el contenido activo y su evidencia de fuente se actualizan a la fuente de reemplazo.
Importa porque una cita de fuente debe referirse al contenido disponible actualmente para el flujo.
Antes del reemplazo:
document_id → página 2 del PDF antiguo
Después del reemplazo:
mismo document_id → página 2 del PDF corregidoLas aplicaciones que necesitan historial de auditoría deberían almacenar:
document_id
versión del documento
swap_id
log_id
evidencia de fuente
decisión del flujo
marca temporalPara flujos operativos estándar, usar la evidencia de fuente activa más reciente suele ser suficiente.
Para flujos de alto impacto —pagos, aprobaciones legales, decisiones de acceso, procesos regulatorios o conciliación financiera—, registrar la versión del documento y el swap_id junto a la decisión crea una pista de auditoría más sólida.
Un modelo mejor que volver a subirlo todo
Sin Knowledge Spaces dinámicos, muchos equipos recurren a soluciones ineficientes.
Solución 1: recrear todo el Knowledge Space
Eliminar el Knowledge Space antiguo
↓
Reprocesar cada fuente
↓
Crear un Knowledge Space nuevo
↓
Actualizar todas las referencias
↓
Esperar que nada siga apuntando al espacio antiguoEsto genera trabajo innecesario, procesamiento duplicado y problemas de gestión de referencias.
Solución 2: mantener todas las versiones activas
Documento original
+ documento corregido
+ documento actualizado
+ documento final
↓
El Knowledge Space crece
↓
El agente ve varias versiones conflictivasEsto aumenta el riesgo de respuestas obsoletas o contradictorias.
Solución 3: borrar el documento antiguo y crear uno nuevo
document_id antiguo eliminado
↓
document_id nuevo creado
↓
Las referencias de la aplicación se rompen
↓
Los flujos necesitan actualizaciones
↓
Hay que reconstruir las relaciones de contextoEl reemplazo de documentos de Claix evita estos problemas:
Procesar la nueva fuente
↓
Sustituir el contenido del documento estable existente
↓
Conservar el mismo document_id
↓
Conservar la misma pertenencia al Knowledge Space
↓
Usar la versión actual en consultas futurasEs un modelo más sencillo para APIs, desarrolladores, herramientas de automatización y sistemas de IA.
Cuándo añadir, quitar o reemplazar
Usa la siguiente guía de decisión.
| Situación | Operación recomendada de Claix |
|---|---|
| Sabes el Knowledge Space de destino durante la extracción | Incluye space_id en la petición de extracción |
| Procesaste una fuente antes de saber dónde pertenece | POST /add-space |
| Un documento debe dejar de afectar a consultas cruzadas pero seguir disponible | DELETE /remove-document-from-space/{document_id} |
| Un documento se asignó al espacio equivocado y debe moverse | Quítalo y luego añádelo al espacio correcto |
| Un archivo corregido debe sustituir un registro de negocio existente | POST /replace-document |
| Un documento debe desaparecer de forma permanente | DELETE /delete-document/{document_id} |
| Una fuente independiente nueva pertenece al mismo contexto | Procésala y añádela o asígnala al espacio |
| Una fuente pertenece a otra cuenta | No intentes reasignarla; Claix aplica la propiedad de la cuenta |
Cómo añadir un documento a un Knowledge Space
Endpoint
POST https://claix.dev/add-spacePetición
{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}Ejemplo cURL
curl -X POST "https://claix.dev/add-space" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_CLAIX_API_KEY" \
-d '{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"space_id": "5b9e2c14-7d3a-4f8b-9e1c-6a0d4b8f2e7c"
}'El documento y el Knowledge Space deben pertenecer a la misma cuenta de Claix.
Un documento solo puede tener un space_id activo. Si ya pertenece a un espacio, quítalo primero.
Cómo quitar un documento de un Knowledge Space
Endpoint
DELETE https://claix.dev/remove-document-from-space/{document_id}Ejemplo cURL
curl -X DELETE \
"https://claix.dev/remove-document-from-space/d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b" \
-H "x-api-key: YOUR_CLAIX_API_KEY"Esta operación:
- Conserva el documento persistente
- Mantiene válido el document_id
- Mantiene disponible el contexto directo del documento
- Excluye el documento de las consultas del Knowledge Space
- Pone space_id a null
No elimina el archivo fuente ni su contexto.
Cómo sustituir el contenido de un documento
Endpoint
POST https://claix.dev/replace-documentPetición
{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}Ejemplo cURL
curl -X POST "https://claix.dev/replace-document" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_CLAIX_API_KEY" \
-d '{
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"new_content_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c"
}'Resultado esperado
{
"success": true,
"swap_id": "c1e7a4b2-9f0d-4e8a-b3c5-1d2e3f4a5b6c",
"document_id": "d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4b",
"source_document_id": "a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3c",
"file_name": "corrected-invoice.pdf",
"version": 2,
"swaps_count": 1,
"message": "Content replaced. The source document was deleted."
}Después del reemplazo:
Continúa consultando:
document_id = d4a1e9d2-8b1c-4f3e-9a02-8b1e9f3c7a4bNo sigas usando:
new_content_document_id = a8c3f1e0-2d4b-4a9e-8c71-5f0e2b9d6a3cLa fuente de reemplazo se elimina tras un swap correcto.
Controles de seguridad y propiedad
Todos los endpoints de gestión de Knowledge Spaces requieren una API key de Claix.
Usa una de estas opciones:
x-api-key: YOUR_CLAIX_API_KEYo:
Authorization: Bearer YOUR_CLAIX_API_KEYClaix verifica:
- Que la API key exista y esté activa.
- Que la cuenta esté activa.
- Que el documento pertenezca a la cuenta de la API key.
- Que el Knowledge Space pertenezca a la cuenta de la API key.
- Que una fuente de reemplazo pertenezca a la misma cuenta.
Las referencias inválidas o entre cuentas no pueden usarse para manipular el contexto de otra cuenta.
Nunca expongas una API key de Claix en código del navegador, repositorios públicos, aplicaciones cliente, capturas de pantalla o logs.
Usa Claix desde un backend, una función serverless segura, un almacén de credenciales de la plataforma de integración o un entorno de automatización de confianza.
Knowledge Spaces dinámicos y fiabilidad de la IA
El valor de un Knowledge Space no es solo la capacidad de consultar muchos documentos juntos.
El valor es la capacidad de consultar juntos los documentos actuales correctos.
Un agente solo puede producir respuestas cruzadas fiables si:
Se incluyen las fuentes relevantes
+
Se excluyen las fuentes irrelevantes
+
Las fuentes corregidas sustituyen a las superadas
+
La identidad del documento permanece estable donde los flujos dependen de ella
+
Los cambios son trazablesLos Knowledge Spaces dinámicos hacen esto posible.
Dan a aplicaciones y agentes un ciclo de vida práctico para el contexto:
Ingerir
↓
Extraer
↓
Asignar
↓
Consultar
↓
Quitar
↓
Reemplazar
↓
Consultar de nuevo el contexto actualEs más útil que tratar un Knowledge Space como un cubo RAG estático.
Lo convierte en una capa de contexto mantenida para operaciones de negocio en vivo.
Preguntas frecuentes
- ¿Qué es un Knowledge Space dinámico?
- Un Knowledge Space dinámico es una colección de documentos persistentes de Claix que puede cambiar con el tiempo. Puedes añadir documentos procesados, quitar documentos sin eliminarlos y sustituir el contenido del documento conservando identificadores estables y la relación existente con el Knowledge Space.
- ¿Puedo añadir un documento después de procesarlo?
- Sí. Usa POST /add-space con el document_id existente y el space_id de destino. El documento no debe pertenecer ya a un Knowledge Space.
- ¿Puedo quitar un documento sin eliminarlo?
- Sí. Usa DELETE /remove-document-from-space/{document_id}. El documento permanece persistente y se puede consultar directamente. Simplemente deja de participar en las consultas cruzadas del Knowledge Space.
- ¿Puedo mover un documento de un Knowledge Space a otro?
- Sí. Quita el documento de su Knowledge Space actual y luego añádelo al nuevo Knowledge Space. El document_id permanece igual.
- ¿Puedo sustituir un documento conservando su document_id?
- Sí. Procesa primero la fuente de reemplazo y luego llama a POST /replace-document con document_id y new_content_document_id. El documento de destino conserva su document_id estable y su pertenencia al Knowledge Space. La fuente de reemplazo se elimina tras el éxito de la operación.
- ¿Por qué es importante un document_id estable?
- Un document_id estable evita romper referencias en aplicaciones, flujos, logs, agentes, bases de datos, registros de cliente y Knowledge Spaces cuando cambia el contenido fuente subyacente.
- ¿Qué ocurre con el documento fuente de reemplazo?
- Tras un reemplazo correcto, el documento fuente new_content_document_id se elimina. No lo uses en peticiones posteriores.
- ¿El reemplazo de documentos consume créditos de extracción?
- No. Las llamadas de add-to-space, remove-from-space y replace-document son gratuitas y no consumen créditos de extracción ni de Context Window. La fuente de reemplazo debe haberse procesado previamente.
- ¿Sustituir el contenido conserva la pertenencia al Knowledge Space?
- Sí. El document_id estable de destino conserva su relación con el Knowledge Space. Las consultas futuras del Knowledge Space usan el contenido de reemplazo.
- ¿Puedo usar el reemplazo de documentos para facturas y contratos corregidos?
- Sí. Ejemplos habituales incluyen facturas corregidas, contratos revisados, listas de precios actualizadas, nuevas versiones de políticas, hojas de cálculo reprocesadas, imágenes de recibos más claras, grabaciones de audio de reemplazo y formularios de cliente actualizados.
- ¿Puedo consultar la versión anterior del documento?
- La respuesta del reemplazo devuelve un swap_id, un número de versión y el conteo de reemplazos para trazabilidad operativa. Guarda estos IDs con tus propios datos de flujo o auditoría si necesitas seguir los cambios en el tiempo.
- ¿Claix evita el contexto documental obsoleto?
- La gestión dinámica del Knowledge Space ayuda a evitar el contexto obsoleto al permitir que las aplicaciones quiten fuentes irrelevantes y sustituyan contenido superado conservando referencias estables. Tu flujo sigue siendo responsable de decidir cuándo una fuente debe quitarse, actualizarse o revisarse.
Conclusión
Los agentes de IA, los sistemas de recuperación, las aplicaciones backend y los flujos de automatización no deberían razonar para siempre sobre colecciones estáticas de archivos.
- El contexto de negocio cambia.
- Se corrigen facturas.
- Se modifican contratos.
- Se clasifican mal documentos.
- Se sustituyen grabaciones de audio.
- Llega información nueva.
- La información antigua deja de ser relevante.
Los Knowledge Spaces de Claix ahora respaldan esa realidad.
Añade las fuentes que importan. Quita las fuentes que ya no pertenecen. Sustituye contenido obsoleto sin romper la identidad del documento. Mantén el contexto que usan tus sistemas de IA actual, estructurado y trazable.
Claix ofrece a los desarrolladores una API de Knowledge Space dinámica para gestionar el contexto documental en PDFs, hojas de cálculo, imágenes, texto, HTML, XML y audio, de modo que aplicaciones, flujos y agentes de IA puedan razonar sobre información de negocio actual en lugar de subidas obsoletas.
También te podría interesar…
Producto · Agentes
Espacios de conocimiento para agentes de IA: consulta varios documentos y conecta sus datos
Producto · Agentes
Inteligencia documental con evidencia para agentes de IA
Producto · Agentes
Memoria documental persistente para agentes: por qué guardar el contexto cambia todo
Modo Agente · IA
El Futuro de los Agentes de IA: Procesamiento de Datos Estructurados e Inferencia en una Sola Llamada