> ## Documentation Index
> Fetch the complete documentation index at: https://wondeya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Conocimiento
> El material a partir del cual un agente puede responder, y cómo se indexa
El conocimiento es todo lo que el agente puede decir. Las respuestas se construyen a partir de él y de nada más: cuando el material no respalda una respuesta, el agente lo dice y ofrece un siguiente paso en lugar de inventar uno. No hay un paso de entrenamiento ni espera: agrega un documento, edita una afirmación, y la siguiente conversación ya lo refleja.
## Los tres tipos de fuente
PDF, Markdown, texto plano, Word (`.docx`) y HTML, hasta 10 MB por archivo.
Una página que wondeya obtiene y lee por ti.
Datos breves que escribes a mano, en español e inglés.
Se combinan libremente dentro de un mismo agente. Usa documentos para el volumen, URLs para el material que ya vive en tu sitio, y afirmaciones para el puñado de datos que siempre deben ser exactos: un precio, una garantía, un horario de apertura.
### Documentos
El cargador de la consola acepta PDF, Markdown, texto plano y Word (`.docx`). La API acepta además HTML (`text/html`). Un archivo que el pipeline no puede leer se rechaza con un error de formato no soportado en lugar de quedar indexado a medias, y el límite es de 10 MB por archivo en cualquier caso.
Subir el mismo archivo dos veces actualiza la fuente existente en lugar de crear una segunda: los bytes son la identidad de una subida, así que volver a arrastrar el mismo PDF no duplica tu base de conocimiento.
### URLs
Das la dirección de una página; wondeya la obtiene y la lee. Solo se permiten `http` y `https`, y las direcciones que resuelven a rangos privados, de loopback o link-local se rechazan. La comprobación se hace cuando agregas la URL y de nuevo al momento de obtenerla, porque el DNS puede cambiar en el intervalo.
Una fuente de tipo URL puede mantenerse al día. Dale una ventana de re-sincronización (`syncTtlMinutes`; la consola ofrece **Una sola vez**, **Cada día** y **Cada semana**) y wondeya vuelve a obtener la página según ese calendario. Elegir Una sola vez significa que no se vuelve a obtener nunca. El re-rastreo es determinista: compara los bytes obtenidos contra lo que ya indexó y solo vuelve a leer una página que realmente cambió, así una página que nunca cambia no cuesta nada y nunca vuelve a ejecutar el paso de enriquecimiento. Aún puedes **Reintentar** una URL a mano en cualquier momento; con el mismo contenido es igual de barato.
### Afirmaciones
Una afirmación es un título más el texto aprobado en español e inglés. Las afirmaciones se guardan **tal cual**: nunca se cortan en fragmentos, nunca se traducen automáticamente al momento de responder. Una afirmación es un texto que alguien aprobó, y volver a cortarlo sería editarlo. Al momento de responder gana el idioma del visitante, y el otro idioma de la misma afirmación se deja de lado para que un mismo dato no llegue dos veces.
La consola no tiene una pantalla de afirmaciones. Escríbelas y actualízalas por [API v1](/docs/es/api-reference/introduction) (`POST /v1/knowledge/claims`) o por [MCP](/docs/es/mcp/introduction) (`upsert_knowledge_claim`), hoy.
## Enriquecimiento automático
Cuando agregas un documento o una URL, wondeya lo lee una vez con un modelo antes de indexarlo. Esa única pasada hace tres cosas que de otro modo harías a mano:
* **Lo nombra.** La fuente recibe un título y un resumen de una línea de lo que cubre, para que el agente sepa que el documento existe incluso antes de leer dentro de él.
* **Lo traduce al inglés.** Los fragmentos se indexan y se recuperan en inglés, lo que cuesta menos tokens en cada respuesta futura. Esto es invisible para tus visitantes: siguen leyendo y recibiendo respuestas en su propio idioma. Una fuente muestra el idioma en el que llegó y una marca de "traducido" para que nada quede oculto.
* **Lo divide en temas.** El documento se divide en temas enfocados (varios cuando el material lo amerita, uno cuando es corto), y a cada tema se le da una descripción corta en inglés. Una nota de un párrafo se vuelve un tema; una política larga se vuelve varios.
El enriquecimiento nunca toca una **afirmación**: una afirmación es un texto que aprobaste palabra por palabra, así que se indexa exactamente como está escrito, en ambos idiomas, y nunca se traduce ni se renombra.
## Temas
Los temas son la forma en que la recuperación dirige una pregunta al material correcto. Son la mitad determinista de la recuperación (sin modelo, sin índice, sin red), y son la mejora de calidad más barata disponible. Una fuente sin temas es universal: el mapa de temas la coteja con cada pregunta, así que siempre se puede recuperar. Etiquetarla es lo que la enfoca.
Cada fuente lleva hasta 12 etiquetas de tema: palabras en minúscula como `pricing`, `warranty`, `shipping`. Puedes ponerlas a mano, y el enriquecimiento te las propone.
### La taxonomía de temas
Cada agente mantiene una **taxonomía** gestionada: el conjunto de temas bajo los que se organiza su conocimiento, cada uno con un `slug` (la clave estable que etiqueta el material), un título y una descripción. La descripción no es decoración: es lo que orienta al agente hacia el tema correcto cuando responde, así que una descripción clara es una palanca de calidad directa.
La consola no tiene una pantalla de Temas. Cura la taxonomía por [API v1](/docs/es/api-reference/introduction) (`GET /v1/knowledge/topics`, `PATCH /v1/knowledge/topics/:slug`, `POST /v1/knowledge/topics/merge`, `DELETE /v1/knowledge/topics/:slug`) o por [MCP](/docs/es/mcp/introduction) (`list_knowledge_topics`, `update_knowledge_topic`, `merge_knowledge_topics`, `delete_knowledge_topic`).
El enriquecimiento escribe la taxonomía por ti y marca cada tema como `auto`; en el momento en que lo renombras o reescribes su descripción pasa a ser `manual`, y el enriquecimiento nunca vuelve a sobrescribir tu redacción. Desde ahí curas lo que el modelo propuso:
* **Renombra** un tema o reescribe su descripción.
* **Fusiona** dos temas que el modelo dividió demasiado (por ejemplo `prices` en `pricing`); el material se re-etiqueta, nunca se pierde.
* **Elimina** un tema; la fila desaparece y la etiqueta se quita de cada fuente, pero el material se queda: un pasaje que queda sin temas simplemente se vuelve universal, y lo alcanza cada pregunta. Eliminar un tema nunca hace que el agente olvide un documento.
No hay una operación de "crear tema" a propósito: un tema sin material no dirige a nada. Los temas nacen del conocimiento que agregas.
**Un tema que se vuelve demasiado amplio es una señal de calidad.** La recuperación sintetiza cada tema seleccionado por separado, así que un tema que carga una cantidad muy grande de fragmentos produce un resumen más largo y menos enfocado. La consola lo marca; la solución es dividir el material subyacente, no el tema.
## Qué pasa después de agregar una fuente
La indexación nunca se ejecuta dentro de tu petición de subida. La petición guarda los bytes y encola el trabajo; la cola hace la lectura.
Cada fuente cuenta contra el cupo de documentos de tu plan, sea un documento, una URL o una afirmación. En el tope, la API responde 402 con el límite y el conteo actual. Editar una afirmación o reintentar una ingesta fallida nunca gasta un documento.
```mermaid theme={null}
flowchart LR
A["agregas una fuente"] --> B["estado: pending"]
B --> C["analizar
PDF página por página, encabezados para HTML/Markdown"]
C --> D["fragmentar
~512 tokens, según la estructura"]
D --> E["generar embeddings"]
E --> F["estado: ready
fragmentos + tokens contados"]
C -.-> X["estado: failed
con un motivo"]
```
Una fuente pasa por cuatro estados:
| Estado | Qué significa |
| - | - |
| `pending` | Guardada y en cola. Nada se puede recuperar todavía. |
| `processing` | Se está analizando, fragmentando y generando sus embeddings. |
| `ready` | Indexada. Los conteos de fragmentos y tokens están en la fuente. |
| `failed` | Algo específico salió mal, y la fuente dice qué. |
Una falla es un estado con un motivo legible por máquina, nunca una caída: `unsupported_document`, `ingest_failed`, o un motivo `fetch_…` para una URL (tiempo de espera agotado, fallo de DNS, respuesta demasiado grande, dirección bloqueada). **Reintentar** vuelve a ejecutar la ingesta con el archivo, la URL o la afirmación que wondeya ya tiene, así que recuperarse cuesta un clic y ninguna nueva subida.
### Cómo se cortan los documentos
Los documentos se dividen primero según su propia estructura (encabezados para Markdown y HTML, páginas para PDF) y solo después por tamaño, apuntando a unos 512 tokens con un pequeño solapamiento. Los fragmentos muy cortos se combinan en lugar de indexarse por su cuenta, porque un fragmento huérfano es ruido en cada búsqueda futura. Cada fragmento lleva el título del documento y la traza de encabezados de la que provino, que es lo que permite que un pasaje tenga sentido fuera de contexto.
## Cómo funciona la recuperación al momento de responder
Dos búsquedas corren en paralelo sobre los fragmentos del agente (más el pool del espacio de trabajo que lee) y sus rankings se fusionan:
* **el mapa de temas**, determinista e instantáneo;
* **la búsqueda vectorial**, filtrada a tu espacio de trabajo y agente antes de mirar un solo vector.
Los ocho mejores pasajes van al agente. No hay un paso de re-ranking, a propósito: con un corpus del tamaño de un agente el cuello de botella es encontrar el pasaje correcto siquiera, no ordenar los que encontraste, y un re-ranker le costaría tiempo al visitante en medio de una respuesta en vivo.
Si la mitad vectorial no está disponible (todavía construyéndose, o el proveedor de embeddings está caído), el mapa de temas responde solo y la página sigue funcionando.
### Probar recuperación
Hoy esto corre solo por [MCP](/docs/es/mcp/introduction), con `probe_retrieval`: corre exactamente la misma búsqueda que hace el agente y te muestra lo que volvió: cada pasaje, a qué fuente pertenece, su traza de encabezados, y cuántos candidatos aportó cada mitad de la búsqueda. La consola todavía no tiene una pantalla para probar la recuperación.
Responde la pregunta que importa cuando una respuesta decepciona: *¿el agente está eligiendo mal, o el material simplemente no está?*
## Alcance de agente y de espacio de trabajo
Una fuente pertenece a un agente, nombrado por `agentId`. Una fuente creada sin `agentId` va a un **pool del espacio de trabajo** que cada agente del espacio de trabajo lee por defecto, y varias páginas que comparten un agente comparten su conocimiento. Un agente puede quedar aislado del pool con su ajuste `useWorkspaceKnowledge`, así un espacio de trabajo que opera dos productos sin relación puede evitar que respondan en nombre del otro. Ese ajuste es editable a través de la API y MCP hoy; la consola todavía no lo expone.
En la consola, una fuente aterriza en el agente en cuya pestaña **Conocimiento** estás. Archivar una fuente en el pool del espacio de trabajo se hace a través de la API omitiendo `agentId`.
## Aislamiento y borrado
El conocimiento nunca sale de tu espacio de trabajo. Hay un único índice para todos y el id de tu espacio de trabajo es parte del filtro en todas y cada una de las búsquedas, así que no se puede escribir una búsqueda que alcance el material de otro cliente: es un prefiltro, no un posfiltro.
Borrar una fuente es real e inmediato: la fila de la fuente, sus fragmentos, sus vectores y el archivo guardado se van juntos en una sola cascada. Como cada fragmento guarda su propio vector, no hay una ventana en la que la base de datos haya olvidado algo que un motor de búsqueda todavía recuerda. Borrar una página no borra conocimiento: el material pertenece al agente, que aún puede responder en otras páginas. Borrar un agente es lo que elimina un corpus entero en esa misma cascada, y ese borrado se rechaza mientras una página todavía apunta al agente.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.