Análisis de IA y Análisis de Datos Históricos

Beak Observability puede incluir dos análisis en cada alerta e incidente, escritos por su agente de recomendación externo — ya sea enviados junto con la alerta/incidente o añadidos posteriormente a través de un endpoint de callback dedicado. Beak nunca los genera por sí mismo. Cada uno es opcional, independiente del otro, y acepta un objeto JSON estructurado o una cadena de texto simple.

---

Los dos campos

• Análisis de IA (ai_analysis) — La lectura del agente sobre la alerta o el incidente en su estado actual: causa probable y acciones recomendadas.
• Análisis de datos históricos (historic_data_analysis) — La comparación del agente de esta señal con datos pasados y ya resueltos: si ha ocurrido antes y qué lo solucionó.

Cualquiera de los campos acepta dos formatos, en todos los endpoints:

• Un objeto o array JSON — Una respuesta estructurada con sus propias claves, anidadas con la profundidad que se desee.
• Una cadena de texto simple — Texto libre.

Se pueden combinar en una sola llamada: un campo estructurado y el otro como cadena de texto.

Nota: Estos son distintos de Probable cause, la narrativa de RCA automática que el generador propio de Beak escribe sobre los incidentes ingestados.

---

Dónde aparecen

Ambos análisis aparecen en el diálogo de detalle de fila en dos páginas que, en conjunto, cubren las cuatro superficies de alertas e incidentes. Abra cualquier fila para verlos.

Página	Superficies cubiertas
Alertas	Alertas por regla e ingestadas
Incidentes	Incidentes promovidos e ingestados / ITSM

Las páginas independientes Ingested Alerts e Ingested Incidents tienen sus propios diálogos de detalle más ligeros y no muestran los análisis — abra la fila desde Alertas o Incidentes en su lugar.

Cada análisis tiene su propia sección, y una sección permanece oculta hasta que su campo tenga contenido.

• Un análisis estructurado — Se presenta de la misma forma que los datos personalizados: una fila por clave, la clave convertida en una etiqueta legible, los valores formateados según su tipo (fechas, enlaces, sí/no), y los objetos y arrays anidados contraídos detrás de un chevron que se puede expandir.
• Una cadena de texto simple — Se muestra como texto, con un botón Show more / Show less cuando es suficientemente larga como para ocultar el resto del diálogo.

Copy as JSON coloca el campo en el portapapeles como JSON sin procesar, en el mismo formato en que se enviaría en el cuerpo de una solicitud — el campo identificado por su propio nombre:

{
  "ai_analysis": {
    "suggested_fixes": [ { "recency": "Resolved 2026-07-09.", "recommendation": "…" } ],
    "comparison_summary": "Same symptom, different host."
  }
}

Nota: Una sección aparece siempre que su campo contenga un valor, independientemente de si la fuente de recomendación de la empresa es el agente de IA o el motor integrado de Beak. El botón Get AI recommendation se muestra únicamente para las empresas configuradas para usar el agente, ya que es el único caso en que una solicitud puede tener éxito.

---

Solicitar un análisis desde la interfaz

En una alerta o incidente cuya empresa usa el agente de IA, Get AI recommendation activa el webhook saliente y retorna de inmediato. El diálogo muestra entonces un estado de el agente está analizando y realiza sondeos hasta que el agente responde con el callback. Ese estado se almacena en el servidor, por lo que sobrevive a una recarga de página; se detiene después de cinco minutos y ofrece Request again si no llega ningún callback.

Una sola solicitud produce ambos análisis — no existe un disparador separado para la comparación histórica.

---

Suministrarlos en el momento de ingestión

Ambos son claves opcionales de nivel superior en el payload de ingestión, para cualquier proveedor:

POST /api/v1/ingest/alerts/{provider}
POST /api/v1/ingest/incidents/{provider}

{
  "alert_id": "cpu-web-01",
  "summary": "CPU above 95% for 12 minutes",
  "severity": "critical",
  "ai_analysis": {
    "suggested_fixes": [
      { "recency": "Resolved 2026-07-09.", "recommendation": "Raise the pool ceiling and redeploy." }
    ],
    "confidence_basis": "Moderate — same symptom, different host.",
    "source_alert_ids": ["AL-260709-0003"]
  },
  "historic_data_analysis": "3 similar alerts in 90 days, all resolved by scaling the pool."
}

Alcance requerido: ingest:alerts o ingest:incidents. La respuesta devuelve ambos campos tal como fueron almacenados, para que pueda confirmar lo que Beak guardó.

Una re-ingestión que omita un análisis conserva el almacenado, de modo que una señal recurrente nunca pierde la escritura anterior del agente.

---

Escribirlos de vuelta (el callback del agente)

Tres endpoints, uno por superficie, cada uno aceptando el UUID o el id de visualización (AL-… / INC-…):

Superficie	Endpoint
Alertas (por regla o ingestadas)	PUT /api/v1/alerts/{origin}/{id}/ai-analysis — origin es rule o external
Incidentes promovidos	PUT /api/v1/promoted-incidents/{id}/ai-analysis
Incidentes ingestados / ITSM	PUT /api/v1/incident-ingest/incidents/{id}/ai-analysis

Los tres aceptan el mismo cuerpo. Envíe uno o ambos campos, cada uno como objeto o cadena de texto:

{
  "ai_analysis": {
    "suggested_fixes": [
      { "recency": "Resolved 2026-07-09.", "recommendation": "Verify disk space and run the standard cleanup." }
    ],
    "source_alert_ids": ["AL-260709-0003"],
    "comparison_summary": "Same symptom, different host."
  },
  "historic_data_analysis": "No prior occurrences of this signature on this service."
}

Reglas para el cuerpo:

• Se requiere al menos un campo — Un cuerpo vacío se rechaza con 422 en lugar de aceptarse como un no-op silencioso.
• Un campo omitido no se modifica — Escribir un análisis nunca borra el otro, y deliberadamente no existe forma de eliminar un análisis a través de este endpoint.
• Cada campo tiene un límite de 20.000 caracteres — Medido sobre el valor almacenado, por lo que para un análisis estructurado, sobre su JSON serializado.

Nota: Autentique estos endpoints por id con el encabezado X-API-Key. Pasar la clave como parámetro de consulta ?key= o como Authorization: Bearer beak_… es rechazado antes de que la solicitud llegue a la ruta.

---

Leerlos de vuelta

Ambos campos se devuelven en los endpoints de lectura de alertas e incidentes — GET /api/v1/alerts/{origin}/{id}, GET /api/v1/promoted-incidents, GET /api/v1/ingest/alerts, GET /api/v1/incident-ingest/incidents y sus formas por id.

Nota: Ambos campos se almacenan como texto, por lo que un análisis estructurado se devuelve como una cadena JSON, no como un objeto anidado — analícelo (JSON.parse o el equivalente en su lenguaje) para leerlo. Lo que se obtiene es la serialización canónica de lo enviado, por lo que la ida y vuelta es exacta.

{
  "id": "…", "status": "firing",
  "ai_analysis": "{\"suggested_fixes\": [{\"recency\": \"Resolved 2026-07-09.\"}]}",
  "historic_data_analysis": "3 similar alerts in 90 days, all resolved by scaling the pool."
}

---

Alcances de la clave de API

Cree claves en Settings → API keys, marcando únicamente los alcances que el agente necesita.

Alcance	Otorga
Write AI analysis (alerts:write_ai_analysis)	Escribir ambos análisis en cualquier alerta — por regla o ingestada — y nada más.
Write AI analysis (incidents:write_ai_analysis)	Escribir ambos análisis en cualquier incidente — promovido o ingestado — y nada más.
ingest:alerts / ingest:incidents	Suministrar los campos en el POST de ingestión.
alerts:read / alerts:read_internal, incidents:read / incidents:read_internal	Leerlos de vuelta.

Los dos alcances de escritura son deliberadamente limitados:

• Una clave que solo contiene alerts:write_ai_analysis — No puede cambiar el estado, la severidad, las notas de triage ni la resolución. Una clave de agente filtrada o con mal funcionamiento solo podrá escribir en los campos de análisis.
• Una clave amplia con alerts:write — No puede acceder al endpoint de análisis, y enviar los campos de análisis al endpoint de actualización general no tiene efecto; no son modificables allí.
• Un alcance por tipo de entidad — Un agente que analiza incidentes promovidos e ingestados necesita un solo alcance, no dos.

---

Referencia de campos

Campo	Tipo	Notas
ai_analysis	Objeto JSON, array o cadena de texto; nullable	Máximo 20.000 caracteres, medidos una vez serializado.
historic_data_analysis	Objeto JSON, array o cadena de texto; nullable	Máximo 20.000 caracteres, medidos una vez serializado.
ai_analysis_requested_at	Timestamp, nullable	Se registra cuando Get AI recommendation despacha el webhook. Impulsa el estado de analizando y cubre ambos análisis — una sola solicitud produce ambos, por lo que no existe un segundo timestamp.

---

Mejores Prácticas

• Envíe JSON estructurado cuando la respuesta tiene partes — Claves como suggested_fixes, comparison_summary y source_alert_ids se convierten en filas etiquetadas y expandibles que un operador puede revisar. Un bloque de texto único no puede navegarse.
• Mantenga los nombres de clave estables — Las etiquetas se derivan de sus claves, por lo que renombrar una clave cambia lo que ven los operadores.
• Referencie las alertas con las que comparó — Coloque sus ids de visualización en el payload (por ejemplo source_alert_ids) para que un operador pueda rastrear el razonamiento del agente hasta los registros reales.
• Limite el alcance de la clave del agente solo a los campos de análisis — Use alerts:write_ai_analysis / incidents:write_ai_analysis en lugar de una clave de escritura amplia, para que el agente nunca pueda alterar el estado ni la resolución.
• Envíe solo el campo que actualizó — Los campos omitidos se conservan, por lo que una actualización parcial es segura y menos costosa que reenviar ambos.
• Controle el límite de 20.000 caracteres en payloads estructurados — La serialización añade comillas y puntuación, por lo que un objeto es más grande que el texto que contiene.

---

Páginas Relacionadas

• Alertas — El feed unificado de alertas, donde ambos análisis aparecen en las filas por regla e ingestadas.
• Ingested Alerts — El feed de alertas ingestadas y la API de ingestión de alertas.
• Incidentes — Incidentes promovidos.
• Ingested Incidents — Incidentes ingestados / ITSM.
• Settings — Claves de API y alcances.