# Cómo funciona el análisis

> Qué dispara el análisis que Sypnia hace de un problema, qué lee, qué pasos sigue, qué escribe, qué nunca hace y cómo muestra que no sabe.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/agent/how-the-analysis-works/

Para agentes: El proceso del análisis de Sypnia: disparadores (nuevo, crece, vuelve, a pedido), entradas (falla, pila con líneas de código, pasos previos, traza, cambios de la versión, impacto), los cinco pasos, los campos de salida y las reglas de confianza, los modos de falla (not_enough_evidence, failed, limit_reached, off) y las sugerencias semanales.

**\[Motor]** **\[Nube]** Esta página es para quien quiere saber qué hay detrás de la frase «3 personas intentaron pagar hoy y no pudieron». Es igual en Sypnia Cloud y en un motor alojado por ti con un modelo configurado. Sin modelo el agente está apagado y todo lo demás de Sypnia sigue funcionando.

> **En palabras simples**
>
> Cuando algo se rompe, Sypnia junta los hechos por su cuenta: dónde falló el código, qué hizo la persona, qué petición falló, qué cambió en la última versión, a cuántas personas afectó. Después le hace una pregunta a un modelo de lenguaje: con estos hechos, ¿qué pasó y por qué? Se queda con la respuesta solo si la respuesta señala esos hechos. Si los hechos no alcanzan, lo dice en vez de adivinar.

## Cuándo corre

| Disparador               | Cuándo exactamente                                                                                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Un problema es nuevo** | Apenas el motor crea el problema, a menos de 2 minutos de la primera falla                                                                                                     |
| **Un problema crece**    | Cuando llega al doble de las personas que tenía en su último análisis, y cuando se ve por primera vez en una versión más nueva                                                 |
| **Un problema vuelve**   | Cuando un problema resuelto ocurre otra vez                                                                                                                                    |
| **Tú lo pides**          | El botón «Analizar de nuevo», o [`POST /v1/problems/{problem}/analyze`](https://docs.sypnia.com/es/api/problems). Sirve después de subir source maps o de registrar la versión |

No corre para problemas ignorados, para proyectos que apagaron el agente, ni por encima de los [límites](https://docs.sypnia.com/es/agent/limits): máximo 3 veces al día para un mismo problema.

## Qué lee

Todo lo que el agente lee lo recoge el motor con reglas fijas, antes de que intervenga un modelo. Es exactamente lo que devuelve [`GET /v1/problems/{problem}/context`](https://docs.sypnia.com/es/api/problems).

| Entrada                       | Qué es                                                                                                                  | De dónde sale                                                        |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| La falla agrupada             | El nombre y el mensaje del error, o la llamada que falló y cómo                                                         | Los eventos del problema                                             |
| La pila, con líneas de código | Los marcos en tus propios archivos y unas líneas de código alrededor de cada uno                                        | La pila del error, traducida con los source maps de la versión       |
| Los pasos previos             | Lo que hizo la persona antes: páginas abiertas, cosas tocadas por su etiqueta, llamadas hechas. Hasta 30                | La sesión de una ocurrencia                                          |
| La traza                      | La petición que falló, seguida del navegador a la API y a las llamadas detrás                                           | La traza de esa ocurrencia                                           |
| La versión y lo que cambió    | La versión en la que la falla se vio primero, cuándo salió, sus commits, archivos cambiados y, si los envías, los diffs | [Versiones](https://docs.sypnia.com/es/api/releases-and-source-maps) |
| El impacto                    | Cuántas personas, sesiones y ocurrencias; cuántas reintentaron; cuándo funcionó por última vez la misma página          | Los conteos del motor                                                |

Cualquiera puede faltar. Sin source maps la pila está minificada; sin una versión registrada no hay «qué cambió». El agente trabaja con lo que hay y su confianza baja en la misma medida.

## Los pasos

### 1. Recoger

El motor elige una ocurrencia para estudiar: la más reciente que tenga traza y sesión. Arma el contexto de arriba. Todavía sin modelo.

### 2. Quitar lo que no debe salir

El motor quita, por regla, lo que no debe salir: las personas pasan a ser «persona 1», «persona 2»; se descartan ids, nombres y correos; las etiquetas de filas de listas y de texto libre se reemplazan por su tipo («una fila»); los valores que parecen tokens o llaves se cortan de mensajes y URLs. Con `SYPNIA_AI_SEND_SOURCE=false` también se quitan las líneas de código y los diffs. La lista exacta está en [Modelos y qué se envía](https://docs.sypnia.com/es/agent/models-and-what-is-sent).

### 3. Preguntar

Una llamada al modelo, con instrucciones fijas y el contexto ya limpio en JSON. El modelo debe responder con una forma JSON fija, y cada afirmación sobre la causa debe nombrar la parte del contexto en la que se apoya. El agente no tiene herramientas ni hace ninguna otra petición: no puede navegar, correr código ni leer nada que no se le dio.

### 4. Revisar

El motor revisa la respuesta contra el contexto, por regla:

- El lugar al que culpa debe ser un marco de la pila o un archivo que la versión cambió.
- Cada evidencia debe señalar algo que existe en el contexto.
- Los números no se toman del modelo. «3 personas», «hoy», «18:40» los pone el motor con sus propios conteos.

Una respuesta que falla se pide una vez más. Si vuelve a fallar, la causa se descarta y el análisis queda en `not_enough_evidence`.

### 5. Escribir

El motor guarda el análisis en el problema, arma [el prompt](https://docs.sypnia.com/es/agent/the-prompt) con una plantilla fija, le da al problema su slug legible y envía el webhook `problem.analyzed`.

## Qué escribe

El `analysis` de un problema, en la API, el servidor MCP, la app y la Consola. El texto se escribe en el idioma del proyecto (`settings.agent.language`); los ejemplos de esta documentación están en inglés.

| Campo            | Qué es                                                           | Ejemplo                                                                                                             |
| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `sentence`       | Qué pasó, en una o dos frases simples                            | «3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.»                  |
| `who`            | A quién afectó                                                   | «3 people. Two of them tried again and gave up.»                                                                    |
| `doing`          | Qué intentaban hacer                                             | «Paying for an order, at the last step of checkout.»                                                                |
| `since`          | Desde cuándo, y si antes funcionaba                              | «Yesterday's change, deployed at 18:40. It worked before.»                                                          |
| `cause.text`     | La causa probable                                                | «Release 4f2a91c renamed the cart's total from cart.total to cart.totalCents. The checkout still reads cart.total…» |
| `cause.evidence` | De uno a seis hechos, cada uno apuntando a algo que puedes abrir | `release_change` `4f2a91c:src/cart/cart.ts`; `stack_frame` `src/checkout/checkout.tsx:142`                          |
| `what_to_do`     | El cambio que hay que hacer                                      | «Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.»             |
| `confidence`     | Qué tan bien sostiene la evidencia a la causa                    | `high`                                                                                                              |
| El prompt        | Lo mismo, como encargo para un agente de código                  | Mira [El prompt](https://docs.sypnia.com/es/agent/the-prompt)                                                       |

### Confianza

La confianza se fija por regla a partir de la evidencia, no por lo seguro que suene el modelo.

| Nivel    | Regla                                                                                                       |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| `high`   | Al menos dos tipos de evidencia coinciden, y uno es un cambio de la versión que toca el código donde falla  |
| `medium` | La causa se apoya solo en la pila o en la traza, con líneas de código                                       |
| `low`    | La causa encaja con los hechos y nada la confirma: una pila minificada, o ninguna información de la versión |

En Sypnia Cloud solo se ofrece un pull request con `high` y `medium`.

## Qué nunca hace

- Nunca ve grabaciones, capturas de página ni pantallazos. Lee eventos como texto.
- Nunca lee lo que una persona escribió. Eso nunca se recoge.
- Nunca recibe nada que esté dentro de un elemento enmascarado, ni nombres, correos o ids de personas.
- Nunca lee tu repositorio en un motor alojado por ti. Solo ve las líneas de código de tus source maps y los diffs que decidiste enviar. En Sypnia Cloud el repositorio se lee solo para escribir un pull request que pediste.
- Nunca cambia tu código, nunca hace merge, nunca resuelve ni ignora un problema.
- Nunca llama a un modelo antes de que configures uno, en un motor alojado por ti.

## Cuando no sabe

Una causa equivocada, dicha con seguridad, cuesta más que no tener causa. Por eso cada forma en que el análisis se puede quedar corto tiene su propio estado, y se muestra tal cual.

| `analysis.status`     | Qué pasó                                                       | Qué ves                                                                                                                                                                                              |
| --------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`               | Se encontró una causa y pasó las revisiones                    | El análisis completo                                                                                                                                                                                 |
| `not_enough_evidence` | El agente pudo describir qué pasó y no pudo sostener una causa | La frase, a quién, qué hacían, desde cuándo. En lugar de la causa: «No hay evidencia suficiente para nombrar una causa», con lo que falta (por ejemplo «no hay source maps para la versión 4f2a91c») |
| `pending`             | Está corriendo                                                 | El título técnico, y «analizando». Casi siempre menos de un minuto                                                                                                                                   |
| `failed`              | La llamada al modelo falló o se venció tres veces              | El título técnico, y «el análisis falló; se intentará de nuevo cuando el problema crezca»                                                                                                            |
| `limit_reached`       | El proyecto usó sus análisis de hoy                            | El título técnico, y cuándo se reinicia la cuenta                                                                                                                                                    |
| `off`                 | No hay modelo configurado, o el proyecto apagó el agente       | El título técnico. No se envió nada a ningún lado                                                                                                                                                    |

En todos, el problema está completo: los conteos, las sesiones, las grabaciones, la traza y la pila están ahí, y el prompt lleva la evidencia.

## Sugerencias semanales

Una vez por semana, el lunes a las 07:00 UTC, el agente mira la semana que terminó y propone mejoras de rendimiento y de uso de la app. Mira [`GET /v1/suggestions`](https://docs.sypnia.com/es/api/performance).

Trabaja en dos partes. Primero, reglas fijas sobre los números, sin modelo: una página con INP en el percentil 75 por encima de 500 ms, más de 3 clics de rabia por cada 100 vistas, una ruta de la API con más de 2 % de fallas, un campo de formulario en el que la gente falla una y otra vez. Estas corren en cualquier motor. Segundo, una llamada al modelo por cada página con hallazgos, para decir en palabras simples qué cambiar. Esa parte necesita un modelo y solo envía conteos, rutas, selectores y etiquetas estables: nunca personas, sesiones ni ids.

## Apagarlo

| Dónde                                 | Cómo                                                                                                                 |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| Un proyecto                           | Pon `settings.agent.enabled` en `false`: `PATCH /v1/projects/{project_ref}`, o en los ajustes del proyecto en la app |
| Todo un motor alojado por ti          | Pon `SYPNIA_AI_PROVIDER=none`, que es el valor por defecto                                                           |
| Solo las llamadas semanales al modelo | `SYPNIA_AI_WEEKLY_SUGGESTIONS=false`                                                                                 |

Con el agente apagado, los problemas conservan su título técnico, las alertas llevan ese título y no se envía nada a ningún proveedor de modelos.
