> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Estudio de datos (agente de IA)

> Describe lo que necesitas en lenguaje natural y un agente de IA construye un informe de insights con números verificados, versionado y publicable

<Info>
  **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing).
</Info>

El **Estudio de datos** (Data Studio) es el módulo de analítica
conversacional de woku. En lugar de configurar un reporte campo por
campo, describes lo que necesitas en lenguaje natural y un agente de IA
construye un **informe de insights** sobre los datos reales de tu
empresa: KPIs, hallazgos con evidencia, visualizaciones y acciones
recomendadas, listo para revisar y publicar.

Complementa al [constructor de reportes](/docs/reports/visual-builder): el
constructor es **determinista y agendable** (ideal para entregas
repetibles en CSV/Excel/PDF); el Estudio de datos es **exploratorio y
conversacional** (ideal para obtener insights a medida en minutos).

## Cómo se usa

1. Abres una conversación y describes el informe que quieres.
2. El agente propone un **plan** (qué datos usará y qué mostrará) y
   espera tu aprobación.
3. Al aprobarlo, consulta los datos en el servidor, los analiza,
   **verifica cada número** contra los datasets y construye el informe.
4. Puedes pedir **cambios en lenguaje natural** (incluido cambiar el
   periodo analizado), volver a una **versión anterior** o calcular
   **métricas avanzadas** como predicciones.
5. El informe queda versionado; puedes **publicarlo** con un enlace
   público o protegido por clave.

Durante todo el proceso la conversación recibe eventos en vivo (el
agente "pensando", el plan, los datos extraídos, la revisión visual y el
informe listo).

## Cómo trabaja el agente

El agente es un **orquestador** conversacional que propone un plan,
espera tu aprobación y luego ejecuta un pipeline determinista: consulta
los datos en el servidor, los analiza, verifica la evidencia, renderiza
el informe y lo revisa visualmente antes de entregarlo.

```mermaid theme={null}
flowchart TD
    U([Usuario]) <-->|conversación en vivo| AG{{"Agente orquestador"}}

    AG --> P["1 · Proponer el plan"]
    P --> OK{"¿Apruebas el plan?"}
    OK -->|sí| D["2 · Consultar los datos<br/>siempre del lado del servidor"]
    D -. catálogo de consultas .-> DATOS[("Datos de woku")]

    D --> A["3 · Analizar<br/>KPIs, hallazgos, acciones"]
    A --> V["4 · Verificar la evidencia<br/>cada número contra los datasets"]
    V --> R["5 · Renderizar el HTML<br/>autocontenido, SVG del servidor"]
    R --> REV{"Revisión visual<br/>¿aprueba?"}
    REV -->|no · reparar| A
    REV -->|sí| LISTO([Informe versionado y publicable])
```

### Las cinco herramientas

| Herramienta                   | Qué hace                                                                                                                                                                         |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **generate\_plan**            | Arma el plan del informe a partir del catálogo completo de consultas disponibles y lo propone al usuario. No ejecuta nada hasta que lo apruebes.                                 |
| **create\_insight\_report**   | Ejecuta el pipeline determinista que construye el informe aprobado (ver la sección siguiente).                                                                                   |
| **revise\_dashboard**         | Aplica cambios pedidos en lenguaje natural sobre el informe existente, incluido cambiar el periodo analizado (por ejemplo "excluye enero" o "solo el último trimestre").         |
| **set\_dashboard\_version**   | Vuelve a una versión anterior del informe.                                                                                                                                       |
| **compute\_advanced\_metric** | Calcula métricas avanzadas, por ejemplo predicciones, usando el intérprete de código de OpenAI. Solo se ejecuta con tu **consentimiento explícito** para enviar datos agregados. |

### El pipeline del informe

`create_insight_report` no es un agente libre, sino un **pipeline
determinista**:

1. **Datos del servidor**: los datasets se consultan siempre del lado
   del servidor a través del catálogo de consultas; el modelo nunca toca
   la base de datos.
2. **Análisis**: el analista produce un informe estructurado con KPIs,
   hallazgos respaldados por evidencia, visualizaciones y acciones
   recomendadas.
3. **Verificación de evidencia**: cada afirmación numérica se verifica
   contra los datasets, con un reintento correctivo. Los hallazgos que
   no pasan la verificación se descartan: un informe nunca publica
   números sin verificar.
4. **Render determinista**: el HTML se genera autocontenido, con SVG
   renderizado en el servidor y sin dependencias de CDNs.
5. **Ver y reparar**: un modelo multimodal revisa el resultado
   renderizado antes de entregarlo, con un máximo de 2 rondas de
   reparación.
6. **Persistencia**: el informe queda guardado como una nueva versión
   de la app.

### Acceso a los datos (multi-tenant)

El agente nunca consulta la base directo: trabaja sobre un **catálogo de
consultas** del servidor. El `companyId` **siempre** se inyecta desde el
contexto de autenticación y nunca desde lo que diga el modelo,
garantizando el aislamiento entre empresas.

El catálogo cubre KPIs globales, métricas por woku y por carpeta,
tendencias de calificación, clientes y segmentos, NPS y sus
herramientas, formularios y canales de respuesta.

## Eventos en streaming (SSE)

El endpoint del agente responde como `text/event-stream`. Estos son los
eventos que emite:

| Evento              | Significado                                          |
| ------------------- | ---------------------------------------------------- |
| `thinking`          | Razonamiento o progreso del agente.                  |
| `plan_proposed`     | Plan listo para revisión del usuario.                |
| `data_extracted`    | Dataset consultado (clave, filas).                   |
| `analysis_complete` | Análisis terminado (clave, tipo).                    |
| `visual_review`     | Resultado de la revisión visual (aprobado, puntaje). |
| `screenshot`        | Captura generada del informe.                        |
| `app_ready`         | Informe construido (id, versión, URL).               |
| `title`             | Título de la conversación, generado automáticamente. |
| `message`           | Respuesta final del asistente.                       |
| `error`             | Resumen de error.                                    |
| `done`              | Fin del stream.                                      |

## Persistencia y publicación

* **Conversación**: historial de mensajes, plan capturado y herramientas
  ejecutadas.
* **App**: metadatos y **versiones inmutables**, cada una conserva su
  propio HTML. Revisar o volver a una versión anterior nunca altera las
  demás.
* **Publicación**: cada app puede publicarse y despublicarse; el enlace
  usa un slug y el acceso puede ser **público** o **protegido por
  clave**, con verificación de la clave al abrirlo.

## Límites por conversación

Para controlar costo y abuso, cada conversación tiene topes:

| Límite                      | Valor |
| --------------------------- | ----- |
| Mensajes                    | 20    |
| Versiones construidas       | 5     |
| Enfriamiento entre mensajes | 1 s   |
| Presupuesto                 | 5 USD |

## Modelos

* **claude-sonnet-5**, la conversación del orquestador y el análisis del
  informe.
* **o4-mini**, solo la revisión visual multimodal.
* **gpt-5.5**, respaldo del plan y del análisis ante una sobrecarga
  transitoria.

## Estudio de datos vs. constructor de reportes

|                  | Estudio de datos                                              | Constructor de reportes                     |
| ---------------- | ------------------------------------------------------------- | ------------------------------------------- |
| Entrada          | Conversación en lenguaje natural                              | Selección de fuente, dimensiones y métricas |
| Salida           | Informe HTML interactivo con números verificados y versionado | Tabla o gráfico                             |
| Entrega agendada | No disponible                                                 | CSV/Excel/PDF programada por email o SFTP   |
| Naturaleza       | Exploratorio, conversacional                                  | Determinista, repetible                     |

Ambos leen los mismos datos y conviven: usa el agente para **explorar y
obtener insights**, y los reportes para **entregas gobernadas y
agendadas**.