Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Cuándo corre
  2. Qué lee
  3. Los pasos
  4. Recoger
  5. Quitar lo que no debe salir
  6. Preguntar
  7. Revisar
  8. Escribir
  9. Qué escribe
  10. Confianza
  11. Qué nunca hace
  12. Cuando no sabe
  13. Sugerencias semanales
  14. Apagarlo

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.

Cuándo corre

DisparadorCuándo exactamente
Un problema es nuevoApenas el motor crea el problema, a menos de 2 minutos de la primera falla
Un problema creceCuando 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 vuelveCuando un problema resuelto ocurre otra vez
Tú lo pidesEl botón «Analizar de nuevo», o POST /v1/problems/{problem}/analyze. 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: 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.

EntradaQué esDe dónde sale
La falla agrupadaEl nombre y el mensaje del error, o la llamada que falló y cómoLos eventos del problema
La pila, con líneas de códigoLos marcos en tus propios archivos y unas líneas de código alrededor de cada unoLa pila del error, traducida con los source maps de la versión
Los pasos previosLo que hizo la persona antes: páginas abiertas, cosas tocadas por su etiqueta, llamadas hechas. Hasta 30La sesión de una ocurrencia
La trazaLa petición que falló, seguida del navegador a la API y a las llamadas detrásLa 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 diffsVersiones
El impactoCuántas personas, sesiones y ocurrencias; cuántas reintentaron; cuándo funcionó por última vez la misma páginaLos 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.

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

CampoQué esEjemplo
sentenceQué 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.»
whoA quién afectó«3 people. Two of them tried again and gave up.»
doingQué intentaban hacer«Paying for an order, at the last step of checkout.»
sinceDesde cuándo, y si antes funcionaba«Yesterday’s change, deployed at 18:40. It worked before.»
cause.textLa causa probable«Release 4f2a91c renamed the cart’s total from cart.total to cart.totalCents. The checkout still reads cart.total…»
cause.evidenceDe uno a seis hechos, cada uno apuntando a algo que puedes abrirrelease_change 4f2a91c:src/cart/cart.ts; stack_frame src/checkout/checkout.tsx:142
what_to_doEl cambio que hay que hacer«Read cart.totalCents in confirmPayment(), and show the customer a message when a payment is rejected.»
confidenceQué tan bien sostiene la evidencia a la causahigh
El promptLo mismo, como encargo para un agente de códigoMira El prompt

Confianza

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

NivelRegla
highAl menos dos tipos de evidencia coinciden, y uno es un cambio de la versión que toca el código donde falla
mediumLa causa se apoya solo en la pila o en la traza, con líneas de código
lowLa 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.statusQué pasóQué ves
readySe encontró una causa y pasó las revisionesEl análisis completo
not_enough_evidenceEl agente pudo describir qué pasó y no pudo sostener una causaLa 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»)
pendingEstá corriendoEl título técnico, y «analizando». Casi siempre menos de un minuto
failedLa llamada al modelo falló o se venció tres vecesEl título técnico, y «el análisis falló; se intentará de nuevo cuando el problema crezca»
limit_reachedEl proyecto usó sus análisis de hoyEl título técnico, y cuándo se reinicia la cuenta
offNo hay modelo configurado, o el proyecto apagó el agenteEl 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.

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óndeCómo
Un proyectoPon settings.agent.enabled en false: PATCH /v1/projects/{project_ref}, o en los ajustes del proyecto en la app
Todo un motor alojado por tiPon SYPNIA_AI_PROVIDER=none, que es el valor por defecto
Solo las llamadas semanales al modeloSYPNIA_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.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar