> ## 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.

# Cómo funciona

> Qué pasa entre la pregunta de un visitante y la respuesta renderizada

Cada respuesta que da una página de wondeya se produce con el mismo pipeline. Entra la pregunta de un visitante; sale un conjunto pequeño de componentes tipados y validados que se transmiten en streaming a la página. El modelo elige **qué** mostrar y **cuál** material usar; nunca escribe la página por sí mismo.

```mermaid theme={null}
flowchart LR
    Q["Pregunta<br/>+ id de conversación"] --> O["entender<br/>idioma + consultas resueltas"]
    O --> T["seleccionar temas"]
    O --> A["seleccionar imágenes"]
    O -->|fuera de tema| B
    T --> SY["sintetizar por tema<br/>cada uno recupera sus propios pasajes"]
    SY --> B["construir<br/>1-3 componentes + respuesta"]
    A --> B
    B --> V["validar → sanitizar → resolver ids"]
    V --> S["transmitir a la página"]
```

## Los pasos

<Steps>
  <Step title="Entender">
    El agente lee la pregunta junto con la conversación hasta ese punto, detecta el idioma en el que escribe el visitante y reescribe la pregunta en dos consultas de búsqueda enfocadas: una para conocimiento, otra para imágenes. La respuesta volverá en el idioma del visitante. Una pregunta fuera de tema para el negocio se salta la recuperación por completo; el agente reencauza con cortesía en lugar de responderla.
  </Step>

  <Step title="Seleccionar temas e imágenes, al mismo tiempo">
    Dos llamadas rápidas al modelo corren en paralelo. Una elige cuáles de los temas de conocimiento del agente toca la pregunta, escogiendo a partir de la descripción que cada tema tiene de lo que cubre. La otra elige imágenes candidatas del registro del agente, a partir de una lista corta con el id, el tipo, la orientación y qué muestra cada imagen. Nunca una URL. Las imágenes ya mostradas en la conversación se excluyen en código, no solo en el prompt.
  </Step>

  <Step title="Sintetizar cada tema">
    Cada tema seleccionado recibe su propia síntesis, todas en paralelo, y cada una ejecuta su propia recuperación.

    **La recuperación es híbrida.** Un mapa de temas determinista y una búsqueda vectorial sobre los pasajes indexados del agente corren lado a lado y sus rankings se fusionan, devolviendo los ocho mejores pasajes para ese tema. Las dos mitades fallan de forma distinta a propósito: el mapa de temas no necesita modelo, ni índice, ni red, así que una página sigue respondiendo cuando la mitad vectorial no está disponible o todavía está calentando.

    La síntesis destila esos pasajes en un resumen corto y fundamentado de lo que el conocimiento dice sobre la pregunta. Un tema fallido nunca hunde el turno; el constructor trabaja con los resúmenes que llegaron.
  </Step>

  <Step title="Construir la respuesta">
    Una sola llamada compone la respuesta completa a partir de los resúmenes fundamentados y la lista corta de imágenes: de uno a tres componentes del [catálogo cerrado](/docs/es/components-catalog), en orden, más la respuesta hablada de una línea. Construir escribe el texto; no sale a buscar hechos nuevos. Una construcción que no produce ningún componente válido recibe exactamente un intento de reparación antes de que el turno termine en error.
  </Step>

  <Step title="Validar, sanitizar, resolver">
    Cada componente construido pasa por el mismo pipeline, en ese orden exacto, del lado del servidor:

    1. **Validar** las props del componente contra su esquema. Los campos desconocidos son un rechazo, no una clave descartada en silencio.
    2. **Sanitizar** cada campo de texto, dejando intactos los ids de referencia.
    3. **Resolver** los ids en datos reales: un id de imagen se convierte en una URL firmada del propio almacenamiento de wondeya, un id de enlace se convierte en la URL que registraste.

    Las salvaguardas fallan cerradas, por componente: un slot duplicado se descarta (gana el primero), y también un componente con props inválidas, uno que referencia un id de acción o de enlace que no existe, o un componente de imagen que no resolvió ninguna imagen aprobada. El resto de la respuesta llega igual; nunca se pierde un turno completo porque una sección estuviera malformada.
  </Step>

  <Step title="Transmitir">
    La página recibe eventos por Server-Sent Events a medida que ocurren: primero el id de conversación, luego un estado grueso y una línea de progreso mientras se elabora el turno, la respuesta escrita, cada sección exactamente una vez con props validadas listas para renderizar, y al final la lista autoritativa de las secciones que llegaron. No hay placeholders de carga: una sección aparece cuando está lista.
  </Step>
</Steps>

## Qué contiene el stream

El transporte es un stream de mensajes de AI SDK UI sobre SSE. Por él viajan seis tipos de eventos:

| Evento | Significado |
| - | - |
| `data-conversation` | El id de la conversación, propiedad del servidor, a la que pertenece este turno. Siempre el primer evento; la página lo guarda y lo devuelve en la siguiente pregunta. |
| `data-status` | Fase gruesa del turno: `understanding`, `searching`, `building`. Una etiqueta de respaldo para antes de que llegue la primera línea de progreso. |
| `data-thinking` | Una línea corta de progreso en el idioma del visitante, una por etapa del pipeline. Se reconcilia sobre un id fijo: la línea más reciente reemplaza a la anterior. |
| `data-section` | Una sección, emitida una sola vez con props validadas y `status: "ready"`, más su posición y el número de secciones del turno. |
| `text-delta` | La respuesta escrita corta que acompaña a los componentes. |
| `data-turn-done` | La lista autoritativa de las secciones que se completaron. Lo que falte en ella se descarta. |

## Por qué tiene esta forma

**El modelo selecciona; el servidor resuelve.** Un tipo de componente sale de un catálogo fijo. Una imagen sale de tu registro, por id. Un enlace sale de la lista que aprobaste, por id. Los esquemas hacen que una URL sea estructuralmente imposible de expresar en la salida del modelo, así que una inyección de prompt escondida dentro de un PDF subido no puede poner un enlace arbitrario ni un script frente a un visitante: no hay campo en el que pueda viajar.

**Todo está fundamentado.** Las cifras, los precios y las promesas se toman de los pasajes recuperados. Cuando el conocimiento no respalda una respuesta, el agente lo dice y ofrece un siguiente paso en lugar de inventar una.

**El servidor es dueño de la conversación.** El primer evento de cada turno le entrega a la página un id de conversación; la página lo devuelve en la siguiente pregunta y el servidor reproduce el historial, los turnos del visitante y los componentes ya mostrados, desde su propia transcripción almacenada. Un cliente no puede falsificar el historial, y saber qué se mostró es lo que permite que una pregunta de seguimiento refine la página en lugar de reiniciarla. Las transcripciones pertenecen a la sesión anónima de la pestaña, expiran con un reloj deslizante de 24 horas y nunca guardan la IP del visitante.

**El endpoint público está defendido.** El endpoint que atiende a los visitantes es anónimo por naturaleza, así que está protegido en capas: una lista de orígenes permitidos, límites de tasa por IP, una verificación de bots invisible, un periodo de enfriamiento por sesión, una caché para preguntas iniciales idénticas y un fusible diario global. [Seguridad y privacidad](/docs/es/security) explica toda la pila.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.