🤖 Sistema Agno para Observabilidad

Sistema de análisis automático de alertas usando Agno Framework + Grafana Stack. Recibe alertas de Grafana, correlaciona métricas/logs/traces y genera reportes de análisis automáticos con causa raíz e insights accionables.

---

🌟 Características

• ✅ ObservabilityTeam: Equipo multi-agente para análisis de alertas
  • WatchdogAgent: Clasificación de severidad, deduplicación y enriquecimiento de contexto
  • TriageAgent: Correlación de métricas (Prometheus), logs (Loki) y traces (Tempo)
  • ReportAgent: Generación de reportes markdown con timeline, evidencia y próximos pasos
• ✅ Quick Commands: 5 comandos rápidos de observabilidad con verificación inteligente
  • recent-incidents: Incidencias recientes con filtros + verificación de salud y tendencias
  • health: Health check de servicios en tiempo real + contexto de incidencias
  • post-deployment: Monitoreo post-deployment automático + análisis de anomalías
  • trends: Análisis de tendencias comparativas + correlación con estado actual
  • daily-digest: Resumen diario automático + detección de incidentes críticos
  • Slash Commands: Ejecutá comandos desde el chat con /novedades, /salud, /deploy, etc.
  • Sistema de Recomendaciones: Cada comando indica si es NOTIFY (accionable) o FYI (informativo)
  • Verificación con Evidencia: Checks automáticos adicionales para validar situaciones
  • Deduplicación: TTL de 30 min para evitar notificaciones repetitivas
• ✅ QueryAgent: Interpreta lenguaje natural para ejecutar quick commands
• ✅ Context Engineering: Configuración avanzada para reportes de alta calidad
• ✅ API REST Completa: Endpoints para webhooks, quick commands y reportes
• ✅ AgentOS + AgnoUI: Runtime oficial de Agno con interfaz web moderna
• ✅ Grafana Stack: Integración con Prometheus, Loki, Tempo y Grafana MCP

---

📚 Quick Start

1. Clonar el repositorio

git clone https://github.com/polsebas/agente-admin-observabilidad.git
cd agente-admin-observabilidad

2. Configurar variables de entorno

cp .env.example .env
# Editar .env con tus claves
# Opcional: Editar config.yaml para ajustes avanzados

Obtener OPENAI_API_KEY: https://platform.openai.com/api-keys
Obtener GRAFANA_API_KEY: Ver sección de Grafana Service Account

3. Levantar el stack

Opción A: Con Docker Compose (Recomendado)

export OPENAI_API_KEY=sk-xxx
export GRAFANA_API_KEY=glsa_xxx
export GRAFANA_URL=http://host.docker.internal:3001

docker compose up -d

• AgentOS: http://localhost:7777
• AgnoUI: http://localhost:3002

Opción B: Local (Development)

# Instalar dependencias
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Ejecutar servidor
uvicorn main:app --host 0.0.0.0 --port 7777

---

🔧 Configuración de Grafana

Grafana Service Account Token

1. Ir a Grafana → Administration → Service Accounts
2. Add service account:
   • Name: mcp-grafana
   • Role: Admin (o Editor mínimo)
3. Add service account token:
   • Name: agno-token
   • Copiar el token generado (glsa_...)
4. Exportar: export GRAFANA_API_KEY=glsa_xxx

Webhook de Alertmanager

1. En Grafana → Alerting → Contact points
2. Add contact point:
   • Name: agno-webhook
   • Integration: Webhook
   • URL: http://localhost:7777/api/alerts
   • HTTP Method: POST
3. Probar conexión

---

📖 Uso

Slash Commands en el Chat (⚡ Nuevo)

Ejemplo de ejecución de /novedades hoy con verificación automática, evidencia y recomendaciones inteligentes

Ejecutá Quick Commands directamente desde el chat con abreviaturas intuitivas:

# Incidencias recientes
/novedades hoy
/inc hours=8 severity=critical

# Salud de servicios
/salud
/health services=auth-service

# Post-deployment
/deploy service=auth-service deployment_time=2025-12-10T14:00:00Z

# Tendencias
/tendencias period_hours=48

# Digest diario
/digest ayer

# Ayuda
/qc

Aliases disponibles:

• /novedades, /nov, /inc → recent-incidents
• /salud, /sal, /health → health check
• /deploy, /dep, /pd → post-deployment
• /tendencias, /tend, /tr → trends
• /digest, /dig, /dd → daily digest
• /qc, /quick, /help → ayuda

Ver guía completa de slash commands.

Quick Commands (API REST)

# Health check de servicios
curl http://localhost:7777/api/quick/health

# Incidencias recientes (últimas 24h)
curl http://localhost:7777/api/quick/recent-incidents?hours=24

# Filtrar por severidad y servicio
curl "http://localhost:7777/api/quick/recent-incidents?hours=8&severity=critical&service=auth-service"

# Monitoreo post-deployment
curl "http://localhost:7777/api/quick/post-deployment?service=auth-service&deployment_time=2025-12-10T14:00:00Z"

# Análisis de tendencias
curl "http://localhost:7777/api/quick/trends?metric=alert_count&period_hours=48"

# Resumen diario
curl http://localhost:7777/api/quick/daily-digest

# Ver ayuda completa
curl http://localhost:7777/api/quick/help

Webhook de Grafana

# Enviar alerta de prueba
curl -X POST http://localhost:7777/api/alerts \
  -H "Content-Type: application/json" \
  -d @test-alert.json

QueryAgent (Lenguaje Natural)

Usa AgnoUI en http://localhost:3002 o la API directamente:

# Ejemplos de queries en lenguaje natural
"Dame las novedades de las últimas 8 horas"
"Cómo está el sistema ahora?"
"Monitoreá el deploy de auth-service de las 14:00"
"Analizá las tendencias de la última semana"

---

🏗️ Arquitectura del Sistema

┌─────────────────────────────────────────┐
│         Grafana Alertmanager            │
│         (Webhook POST)                  │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│         AgentOS (FastAPI)               │
│  Endpoint: /api/alerts                  │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│       ObservabilityTeam                 │
│  ┌────────────────────────────────────┐ │
│  │  WatchdogAgent                     │ │
│  │  → Classify, Dedupe (Redis)        │ │
│  │  → Enrich Context                  │ │
│  └─────────────┬──────────────────────┘ │
│                ▼                        │
│  ┌────────────────────────────────────┐ │
│  │  TriageAgent                       │ │
│  │  → Dynamic Service Discovery       │ │
│  │  → Correlate Metrics/Logs/Traces   │ │
│  └─────────────┬──────────────────────┘ │
│                ▼                        │
│  ┌────────────────────────────────────┐ │
│  │  ReportAgent                       │ │
│  │  → Generate Markdown Report        │ │
│  └────────────────────────────────────┘ │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│  Storage: PostgreSQL (Async)            │
│  Cache: Redis (Deduplication)           │
└─────────────────────────────────────────┘

Componentes Clave

• WatchdogAgent: Clasifica severidad (critical/major/minor/info), detecta duplicados, enriquece contexto
• TriageAgent: Correlaciona métricas de Prometheus, logs de Loki, traces de Tempo para identificar causa raíz
• ReportAgent: Genera reportes markdown con timeline, evidencia, análisis de causa raíz y próximos pasos
• ObservabilityTeam: Coordina el flujo secuencial entre los 3 agentes
• QueryAgent: Ejecuta quick commands desde lenguaje natural

---

📚 Documentación

Context Engineering

• Guía de Context Engineering: Documentación completa sobre cómo se usa el context engineering en este proyecto, incluyendo arquitectura, parámetros por agente, best practices y ejemplos.
• Referencia Rápida de Contexto: Una guía concisa para consultas rápidas sobre los parámetros de contexto y su uso.
• Resumen de Implementación: Un resumen ejecutivo de los cambios implementados, resultados y mejoras observables.

Quick Commands

• Guía de Quick Commands: Documentación completa de comandos rápidos de observabilidad, incluyendo 5 comandos principales, modo híbrido, ejemplos prácticos y casos de uso.
• Resumen de Implementación: Resumen técnico de la implementación, arquitectura, testing y próximos pasos.

Slash Commands en el Chat

Ejecutá comandos rápidos directamente desde el chat:

# Incidencias recientes
/novedades hoy              # Últimas 24h
/inc hours=8 severity=critical

# Salud del sistema
/salud                      # Todos los servicios
/health services=auth-service,payment-service

# Post-deployment
/deploy service=auth-service deployment_time=2025-12-14T14:00:00Z

# Tendencias
/tendencias period_hours=48
/tr metric=alert_count

# Digest diario
/digest ayer
/dd date=2025-12-09

# Ayuda
/qc

Características:

• 🔔 Recomendaciones Inteligentes: Cada comando indica si es NOTIFY (accionable) o FYI (informativo)
• 📋 Verificación con Evidencia: Checks automáticos adicionales para validar situaciones
• 🔄 Deduplicación: TTL de 30 min para evitar notificaciones repetitivas
• ⚡ Abreviaturas: Aliases cortos como /nov, /sal, /dep, /tend, /dig

Ver documentación completa para más detalles sobre aliases, evidencia y criterios de notify/fyi.

General

• Índice de Documentación: Punto de entrada a toda la documentación del proyecto.

---

🧪 Testing

# Probar quick commands
./test_quick_commands.sh

# Enviar alerta de prueba
curl -X POST http://localhost:7777/api/alerts \
  -H "Content-Type: application/json" \
  -d @test-alert.json

# Ver reporte generado
cat test-alert-report.md

---

🚀 Roadmap (Fase 2)

• Análisis IA completo: Integración real de analyze_with_ai=True con agentes
• Métricas reales: Comparación de métricas de Prometheus en tendencias
• Automatización: Daily digest automático con cron/scheduled tasks
• Acciones automáticas: Restart, scale, runbooks ejecutables
• Exportación: Reportes en PDF/HTML, integración con Jira/PagerDuty
• Performance: Cache de queries, paginación, índices optimizados
• Dashboard: Panel de Grafana con quick commands embebidos

---

🤝 Contribuir

Las contribuciones son bienvenidas! Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

Ver docs/CONTEXT_ENGINEERING.md para guías de desarrollo.

---

📝 Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

---

🙏 Agradecimientos

• Agno Framework - Multi-agent framework
• Grafana - Observability stack
• OpenAI - LLM provider

---

📞 Contacto

Pol Sebastian - @polsebas

Project Link: https://github.com/polsebas/agente-admin-observabilidad

---

⭐ Si te gusta este proyecto, dale una estrella en GitHub!