opsagent

{"type":"text"}# ai-automation-lab

Un agente de triaje de incidentes que se ejecuta contra mi propio clúster K3s. Cuando Alertmanager se dispara, investiga utilizando acceso de solo lectura a la telemetría del clúster y devuelve una hipótesis clasificada sobre la que un humano puede actuar. Luego registra si tenía razón.

Esa última parte es el punto. Enviar una alerta a un modelo de lenguaje es un proyecto de fin de semana. Medir si la salida fue correcta, acotar su coste y demostrar que no puede tocar nada que no deba, es el trabajo real.

Este es el tercer laboratorio de una serie: devops-homelab-k3s-hybrid-cloud es la plataforma que observa, y qa-engineering-lab es el conjunto de pruebas que encontró seis defectos reales en esa plataforma.

Arquitectura

flowchart TB
    subgraph cluster["K3s cluster"]
        AM["Alertmanager"] -->|webhook| N8N["n8n<br/>workflows deployed from git"]
        N8N -->|"POST /investigations"| AGENT["opsagent<br/>FastAPI + agent loop"]

        AGENT -->|"read-only ServiceAccount"| TOOLS["tool layer"]
        TOOLS --> K8S["Kubernetes API<br/>pods, events, deploys"]
        TOOLS --> LOKI["Loki<br/>container logs"]
        TOOLS --> PROM["Prometheus<br/>PromQL"]
        TOOLS --> ARGO["ArgoCD<br/>sync history"]

        TOOLS -->|redaction| AGENT
        AGENT --> PG[("PostgreSQL<br/>investigations, cost, verdicts")]
    end

    AGENT -->|"redacted prompt"| LLM["LLM provider<br/>mock by default"]
    N8N --> TG["Telegram"]
    N8N --> GH["GitHub issue<br/>new alert class only"]
    HUMAN["me"] -->|"actual root cause"| PG
    PG --> EVAL["accuracy report"]

Dos propiedades son estructurales más que convencionales. La salida de las herramientas pasa por el enmascaramiento antes de llegar al modelo, de modo que nada sin enmascarar puede salir del clúster incluso si el agente se comporta mal. Y el modelo nunca ejecuta nada: lee, razona, propone. La remediación está fuera del alcance de la v1.

Related MCP server: kubeview-mcp

Estado

Construido fase por fase, y esta tabla es el estado honesto del mismo.

El desglose completo, incluida la definición de hecho para cada fase y las partes del encargo que cuestioné, está en plan.md.

Ejecutarlo

Nada aquí necesita una clave API, una base de datos o acceso al clúster. El proveedor predeterminado es un simulacro determinista, que es también lo que usa CI.

uv sync
uv run pytest
uv run opsagent show-config

environment=local
log_level=INFO
log_json=None

Puertas de calidad, las mismas cuatro ejecuciones de CI:

uv run ruff check .
uv run mypy
uv run pytest
uv run opsagent n8n validate

La sincronización de flujos de trabajo necesita una instancia en ejecución y una clave API, por lo que es lo único que no funciona desde un clon limpio:

opsagent n8n export    # instance to git, produces a reviewable diff
opsagent n8n diff      # compare, exits non-zero on drift, used as a CI gate
opsagent n8n import    # git to instance, reconciles activation state
opsagent n8n validate  # offline checks, no API key needed

Manejar las herramientas manualmente

La capa de herramientas es un servidor MCP antes de ser una dependencia del agente, por lo que las herramientas se pueden usar desde una sesión de editor contra el clúster real. Regístralo:

{
  "mcpServers": {
    "opsagent": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ai-automation-lab", "python", "-m", "opsagent.mcp"],
      "env": { "OPSAGENT_LOKI_URL": "http://localhost:3100" }
    }
  }
}

Lee el contexto de kubeconfig que esté activo, así que apúntalo a uno de solo lectura. Las seis herramientas son get_pod_status, get_events, query_logs, query_metrics, get_recent_deploys y get_runbook. Cada resultado indica cuántos valores fueron enmascarados y si fue truncado, de modo que un llamador nunca pueda confundir una respuesta parcial con una completa.

Decisiones de diseño que merecen defensa

El repositorio se ejecuta con cero claves API y cero gasto. Un revisor que clone esto obtiene un sistema funcional, no un README que lo describa. Eso obligó a que la abstracción de proveedor existiera desde el principio en lugar de ser añadida después.

El enmascaramiento se sitúa en el límite de la herramienta, no antes del prompt. Ponerlo en el agente significa que cada futuro llamador de la capa de herramientas tenga que recordar enmascarar. Ponerlo en las herramientas hace que sea imposible olvidarlo, y es el código más probado del repositorio.

El enmascaramiento preserva la identidad en lugar de borrarla. La misma dirección siempre se convierte en el mismo <ip-1>, de modo que el modelo aún puede razonar que el pod en <ip-1> no puede alcanzar <ip-2> y correlacionar eso a través de un extracto de log y un evento. Enmascarar todo a un único <redacted> destruiría exactamente la estructura de la que está hecha una causa raíz.

El ServiceAccount del agente no puede leer secretos ni escribir nada. El arnés de inyección de fallos de la fase 6 necesita acceso de escritura para romper cosas a propósito, por lo que lleva su propia credencial separada. El agente nunca obtiene una.

Las líneas de log son entrada no confiable. Cualquiera que pueda escribir en un log que yo lea puede escribir instrucciones a mi agente. Eso está en el modelo de amenazas, y la fase 6 mide lo que realmente sucede en lugar de asumir que el prompt se mantuvo.

Documentación

Autor

Kostiantyn Osmakov cv.batpepe.online | @batpepe