{"id":49533040,"url":"https://github.com/polsebas/agente-admin-observabilidad","last_synced_at":"2026-05-02T08:36:02.384Z","repository":{"id":328077715,"uuid":"1114153484","full_name":"polsebas/agente-admin-observabilidad","owner":"polsebas","description":"Sistema de análisis automático de alertas con Agno Framework + Grafana Stack. Incluye ObservabilityTeam (WatchdogAgent, TriageAgent, ReportAgent) y Quick Commands para observabilidad en tiempo real.","archived":false,"fork":false,"pushed_at":"2026-01-14T17:23:50.000Z","size":505,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T21:31:31.377Z","etag":null,"topics":["agno","ai","alerting","devops","grafana","loki","multi-agent","observability","prometheus","sre","tempo"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polsebas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-11T01:21:05.000Z","updated_at":"2026-01-14T17:24:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/polsebas/agente-admin-observabilidad","commit_stats":null,"previous_names":["polsebas/agente-admin-observabilidad"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/polsebas/agente-admin-observabilidad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polsebas%2Fagente-admin-observabilidad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polsebas%2Fagente-admin-observabilidad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polsebas%2Fagente-admin-observabilidad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polsebas%2Fagente-admin-observabilidad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polsebas","download_url":"https://codeload.github.com/polsebas/agente-admin-observabilidad/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polsebas%2Fagente-admin-observabilidad/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agno","ai","alerting","devops","grafana","loki","multi-agent","observability","prometheus","sre","tempo"],"created_at":"2026-05-02T08:36:01.537Z","updated_at":"2026-05-02T08:36:02.373Z","avatar_url":"https://github.com/polsebas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🤖 Sistema Agno para Observabilidad\n\n[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)\n[![Agno Framework](https://img.shields.io/badge/Agno-2.2.12+-green.svg)](https://www.agno.com/)\n[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![GitHub](https://img.shields.io/github/stars/polsebas/agente-admin-observabilidad?style=social)](https://github.com/polsebas/agente-admin-observabilidad)\n\nSistema 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.\n\n---\n\n## 🌟 Características\n\n![Slash Commands en Acción](docs/slash-commands-demo.png)\n\n- ✅ **ObservabilityTeam**: Equipo multi-agente para análisis de alertas\n  - **WatchdogAgent**: Clasificación de severidad, deduplicación y enriquecimiento de contexto\n  - **TriageAgent**: Correlación de métricas (Prometheus), logs (Loki) y traces (Tempo)\n  - **ReportAgent**: Generación de reportes markdown con timeline, evidencia y próximos pasos\n- ✅ **Quick Commands**: 5 comandos rápidos de observabilidad con verificación inteligente\n  - `recent-incidents`: Incidencias recientes con filtros + verificación de salud y tendencias\n  - `health`: Health check de servicios en tiempo real + contexto de incidencias\n  - `post-deployment`: Monitoreo post-deployment automático + análisis de anomalías\n  - `trends`: Análisis de tendencias comparativas + correlación con estado actual\n  - `daily-digest`: Resumen diario automático + detección de incidentes críticos\n  - **Slash Commands**: Ejecutá comandos desde el chat con `/novedades`, `/salud`, `/deploy`, etc.\n  - **Sistema de Recomendaciones**: Cada comando indica si es NOTIFY (accionable) o FYI (informativo)\n  - **Verificación con Evidencia**: Checks automáticos adicionales para validar situaciones\n  - **Deduplicación**: TTL de 30 min para evitar notificaciones repetitivas\n- ✅ **QueryAgent**: Interpreta lenguaje natural para ejecutar quick commands\n- ✅ **Context Engineering**: Configuración avanzada para reportes de alta calidad\n- ✅ **API REST Completa**: Endpoints para webhooks, quick commands y reportes\n- ✅ **AgentOS + AgnoUI**: Runtime oficial de Agno con interfaz web moderna\n- ✅ **Grafana Stack**: Integración con Prometheus, Loki, Tempo y Grafana MCP\n\n---\n\n## 📚 Quick Start\n\n### 1. Clonar el repositorio\n\n```bash\ngit clone https://github.com/polsebas/agente-admin-observabilidad.git\ncd agente-admin-observabilidad\n```\n\n### 2. Configurar variables de entorno\n\n```bash\ncp .env.example .env\n# Editar .env con tus claves\n# Opcional: Editar config.yaml para ajustes avanzados\n```\n\nObtener `OPENAI_API_KEY`: https://platform.openai.com/api-keys  \nObtener `GRAFANA_API_KEY`: Ver [sección de Grafana Service Account](#grafana-service-account-token)\n\n### 3. Levantar el stack\n\n#### Opción A: Con Docker Compose (Recomendado)\n\n```bash\nexport OPENAI_API_KEY=sk-xxx\nexport GRAFANA_API_KEY=glsa_xxx\nexport GRAFANA_URL=http://host.docker.internal:3001\n\ndocker compose up -d\n```\n\n- **AgentOS**: http://localhost:7777\n- **AgnoUI**: http://localhost:3002\n\n#### Opción B: Local (Development)\n\n```bash\n# Instalar dependencias\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Ejecutar servidor\nuvicorn main:app --host 0.0.0.0 --port 7777\n```\n\n---\n\n## 🔧 Configuración de Grafana\n\n### Grafana Service Account Token\n\n1. Ir a Grafana → **Administration** → **Service Accounts**\n2. **Add service account**:\n   - Name: `mcp-grafana`\n   - Role: **Admin** (o **Editor** mínimo)\n3. **Add service account token**:\n   - Name: `agno-token`\n   - Copiar el token generado (`glsa_...`)\n4. Exportar: `export GRAFANA_API_KEY=glsa_xxx`\n\n### Webhook de Alertmanager\n\n1. En Grafana → **Alerting** → **Contact points**\n2. **Add contact point**:\n   - Name: `agno-webhook`\n   - Integration: **Webhook**\n   - URL: `http://localhost:7777/api/alerts`\n   - HTTP Method: **POST**\n3. Probar conexión\n\n---\n\n## 📖 Uso\n\n### Slash Commands en el Chat (⚡ Nuevo)\n\n![Slash Commands Demo](docs/slash-commands-demo.png)\n*Ejemplo de ejecución de `/novedades hoy` con verificación automática, evidencia y recomendaciones inteligentes*\n\nEjecutá Quick Commands directamente desde el chat con abreviaturas intuitivas:\n\n```bash\n# Incidencias recientes\n/novedades hoy\n/inc hours=8 severity=critical\n\n# Salud de servicios\n/salud\n/health services=auth-service\n\n# Post-deployment\n/deploy service=auth-service deployment_time=2025-12-10T14:00:00Z\n\n# Tendencias\n/tendencias period_hours=48\n\n# Digest diario\n/digest ayer\n\n# Ayuda\n/qc\n```\n\n**Aliases disponibles:**\n- `/novedades`, `/nov`, `/inc` → recent-incidents\n- `/salud`, `/sal`, `/health` → health check\n- `/deploy`, `/dep`, `/pd` → post-deployment\n- `/tendencias`, `/tend`, `/tr` → trends\n- `/digest`, `/dig`, `/dd` → daily digest\n- `/qc`, `/quick`, `/help` → ayuda\n\nVer [guía completa de slash commands](docs/QUICK_COMMANDS.md#uso-en-el-chat-slash-commands).\n\n### Quick Commands (API REST)\n\n```bash\n# Health check de servicios\ncurl http://localhost:7777/api/quick/health\n\n# Incidencias recientes (últimas 24h)\ncurl http://localhost:7777/api/quick/recent-incidents?hours=24\n\n# Filtrar por severidad y servicio\ncurl \"http://localhost:7777/api/quick/recent-incidents?hours=8\u0026severity=critical\u0026service=auth-service\"\n\n# Monitoreo post-deployment\ncurl \"http://localhost:7777/api/quick/post-deployment?service=auth-service\u0026deployment_time=2025-12-10T14:00:00Z\"\n\n# Análisis de tendencias\ncurl \"http://localhost:7777/api/quick/trends?metric=alert_count\u0026period_hours=48\"\n\n# Resumen diario\ncurl http://localhost:7777/api/quick/daily-digest\n\n# Ver ayuda completa\ncurl http://localhost:7777/api/quick/help\n```\n\n### Webhook de Grafana\n\n```bash\n# Enviar alerta de prueba\ncurl -X POST http://localhost:7777/api/alerts \\\n  -H \"Content-Type: application/json\" \\\n  -d @test-alert.json\n```\n\n### QueryAgent (Lenguaje Natural)\n\nUsa AgnoUI en http://localhost:3002 o la API directamente:\n\n```python\n# Ejemplos de queries en lenguaje natural\n\"Dame las novedades de las últimas 8 horas\"\n\"Cómo está el sistema ahora?\"\n\"Monitoreá el deploy de auth-service de las 14:00\"\n\"Analizá las tendencias de la última semana\"\n```\n\n---\n\n## 🏗️ Arquitectura del Sistema\n\n```\n┌─────────────────────────────────────────┐\n│         Grafana Alertmanager            │\n│         (Webhook POST)                  │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────────┐\n│         AgentOS (FastAPI)               │\n│  Endpoint: /api/alerts                  │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────────┐\n│       ObservabilityTeam                 │\n│  ┌────────────────────────────────────┐ │\n│  │  WatchdogAgent                     │ │\n│  │  → Classify, Dedupe (Redis)        │ │\n│  │  → Enrich Context                  │ │\n│  └─────────────┬──────────────────────┘ │\n│                ▼                        │\n│  ┌────────────────────────────────────┐ │\n│  │  TriageAgent                       │ │\n│  │  → Dynamic Service Discovery       │ │\n│  │  → Correlate Metrics/Logs/Traces   │ │\n│  └─────────────┬──────────────────────┘ │\n│                ▼                        │\n│  ┌────────────────────────────────────┐ │\n│  │  ReportAgent                       │ │\n│  │  → Generate Markdown Report        │ │\n│  └────────────────────────────────────┘ │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────────┐\n│  Storage: PostgreSQL (Async)            │\n│  Cache: Redis (Deduplication)           │\n└─────────────────────────────────────────┘\n```\n\n### Componentes Clave\n\n- **WatchdogAgent**: Clasifica severidad (critical/major/minor/info), detecta duplicados, enriquece contexto\n- **TriageAgent**: Correlaciona métricas de Prometheus, logs de Loki, traces de Tempo para identificar causa raíz\n- **ReportAgent**: Genera reportes markdown con timeline, evidencia, análisis de causa raíz y próximos pasos\n- **ObservabilityTeam**: Coordina el flujo secuencial entre los 3 agentes\n- **QueryAgent**: Ejecuta quick commands desde lenguaje natural\n\n---\n\n## 📚 Documentación\n\n### Context Engineering\n- **[Guía de Context Engineering](docs/CONTEXT_ENGINEERING.md)**: Documentación completa sobre cómo se usa el context engineering en este proyecto, incluyendo arquitectura, parámetros por agente, best practices y ejemplos.\n- **[Referencia Rápida de Contexto](docs/CONTEXT_QUICK_REFERENCE.md)**: Una guía concisa para consultas rápidas sobre los parámetros de contexto y su uso.\n- **[Resumen de Implementación](docs/IMPLEMENTATION_SUMMARY.md)**: Un resumen ejecutivo de los cambios implementados, resultados y mejoras observables.\n\n### Quick Commands\n- **[Guía de Quick Commands](docs/QUICK_COMMANDS.md)**: Documentación completa de comandos rápidos de observabilidad, incluyendo 5 comandos principales, modo híbrido, ejemplos prácticos y casos de uso.\n- **[Resumen de Implementación](QUICK_COMMANDS_IMPLEMENTATION.md)**: Resumen técnico de la implementación, arquitectura, testing y próximos pasos.\n\n#### Slash Commands en el Chat\n\nEjecutá comandos rápidos directamente desde el chat:\n\n```bash\n# Incidencias recientes\n/novedades hoy              # Últimas 24h\n/inc hours=8 severity=critical\n\n# Salud del sistema\n/salud                      # Todos los servicios\n/health services=auth-service,payment-service\n\n# Post-deployment\n/deploy service=auth-service deployment_time=2025-12-14T14:00:00Z\n\n# Tendencias\n/tendencias period_hours=48\n/tr metric=alert_count\n\n# Digest diario\n/digest ayer\n/dd date=2025-12-09\n\n# Ayuda\n/qc\n```\n\n**Características:**\n- 🔔 **Recomendaciones Inteligentes**: Cada comando indica si es NOTIFY (accionable) o FYI (informativo)\n- 📋 **Verificación con Evidencia**: Checks automáticos adicionales para validar situaciones\n- 🔄 **Deduplicación**: TTL de 30 min para evitar notificaciones repetitivas\n- ⚡ **Abreviaturas**: Aliases cortos como `/nov`, `/sal`, `/dep`, `/tend`, `/dig`\n\nVer [documentación completa](docs/QUICK_COMMANDS.md) para más detalles sobre aliases, evidencia y criterios de notify/fyi.\n\n### General\n- **[Índice de Documentación](docs/README.md)**: Punto de entrada a toda la documentación del proyecto.\n\n---\n\n## 🧪 Testing\n\n```bash\n# Probar quick commands\n./test_quick_commands.sh\n\n# Enviar alerta de prueba\ncurl -X POST http://localhost:7777/api/alerts \\\n  -H \"Content-Type: application/json\" \\\n  -d @test-alert.json\n\n# Ver reporte generado\ncat test-alert-report.md\n```\n\n---\n\n## 🚀 Roadmap (Fase 2)\n\n- [ ] **Análisis IA completo**: Integración real de `analyze_with_ai=True` con agentes\n- [ ] **Métricas reales**: Comparación de métricas de Prometheus en tendencias\n- [ ] **Automatización**: Daily digest automático con cron/scheduled tasks\n- [ ] **Acciones automáticas**: Restart, scale, runbooks ejecutables\n- [ ] **Exportación**: Reportes en PDF/HTML, integración con Jira/PagerDuty\n- [ ] **Performance**: Cache de queries, paginación, índices optimizados\n- [ ] **Dashboard**: Panel de Grafana con quick commands embebidos\n\n---\n\n## 🤝 Contribuir\n\nLas contribuciones son bienvenidas! Por favor:\n\n1. Fork el repositorio\n2. Crea una rama para tu feature (`git checkout -b feature/amazing-feature`)\n3. Commit tus cambios (`git commit -m 'Add amazing feature'`)\n4. Push a la rama (`git push origin feature/amazing-feature`)\n5. Abre un Pull Request\n\nVer [docs/CONTEXT_ENGINEERING.md](docs/CONTEXT_ENGINEERING.md) para guías de desarrollo.\n\n---\n\n## 📝 Licencia\n\nEste proyecto está bajo la licencia MIT. Ver [LICENSE](LICENSE) para más detalles.\n\n---\n\n## 🙏 Agradecimientos\n\n- [Agno Framework](https://www.agno.com/) - Multi-agent framework\n- [Grafana](https://grafana.com/) - Observability stack\n- [OpenAI](https://openai.com/) - LLM provider\n\n---\n\n## 📞 Contacto\n\n**Pol Sebastian** - [@polsebas](https://github.com/polsebas)\n\n**Project Link**: [https://github.com/polsebas/agente-admin-observabilidad](https://github.com/polsebas/agente-admin-observabilidad)\n\n---\n\n⭐ Si te gusta este proyecto, dale una estrella en GitHub!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolsebas%2Fagente-admin-observabilidad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolsebas%2Fagente-admin-observabilidad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolsebas%2Fagente-admin-observabilidad/lists"}