ai-automation-lab

Ein Incident-Triage-Agent, der gegen meinen eigenen K3s-Cluster läuft. Wenn Alertmanager auslöst, untersucht er mit schreibgeschütztem Zugriff auf die Telemetrie des Clusters und liefert eine priorisierte Hypothese, auf die ein Mensch reagieren kann. Danach zeichnet er auf, ob er richtig lag.

Genau das ist der Punkt. Eine Warnung in ein Sprachmodell zu leiten, ist ein Wochenendprojekt. Zu messen, ob die Ausgabe korrekt war, die Kosten zu begrenzen und zu beweisen, dass er nichts anfassen kann, was er nicht anfassen darf, ist die eigentliche Arbeit.

Dies ist das dritte Labor in einer Serie: devops-homelab-k3s-hybrid-cloud ist die Plattform, die er überwacht, und qa-engineering-lab ist die Testsuite, die sechs echte Fehler in dieser Plattform gefunden hat.

Architektur

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"]

Zwei Eigenschaften sind strukturell und nicht konventionell. Tool-Ausgaben durchlaufen eine Schwärzung bevor sie das Modell erreichen, sodass nichts Ungeschwärztes den Cluster verlassen kann, selbst wenn der Agent sich fehlverhält. Und das Modell führt niemals etwas aus: Es liest, es denkt, es schlägt vor. Die Behebung ist für v1 außerhalb des Rahmens.

Related MCP server: kubeview-mcp

Status

Phase für Phase aufgebaut, und diese Tabelle ist der ehrliche Stand.

Die vollständige Aufschlüsselung, einschließlich der Definition von „fertig" für jede Phase und der Teile des Briefings, gegen die ich argumentiert habe, finden Sie in plan.md.

Ausführen

Hier ist nichts nötig, was einen API-Schlüssel, eine Datenbank oder Cluster-Zugriff erfordert. Der Standard-Provider ist ein deterministischer Mock, der auch von CI verwendet wird.

uv sync
uv run pytest
uv run opsagent show-config

environment=local
log_level=INFO
log_json=None

Qualitätsgates, die gleichen vier CI-Läufe:

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

Die Workflow-Synchronisierung benötigt eine laufende Instanz und einen API-Schlüssel, also ist sie das Einzige, was aus einem sauberen Klon nicht funktioniert:

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

Die Werkzeuge von Hand bedienen

Die Tool-Schicht ist ein MCP-Server, bevor sie eine Abhängigkeit des Agents ist, also können die Werkzeuge aus einer Editor-Sitzung gegen den echten Cluster verwendet werden. Registrieren Sie ihn:

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

Er liest den aktiven kubeconfig-Kontext, also richten Sie ihn auf einen schreibgeschützten aus. Die sechs Werkzeuge sind get_pod_status, get_events, query_logs, query_metrics, get_recent_deploys und get_runbook. Jedes Ergebnis enthält, wie viele Werte geschwärzt wurden und ob es abgeschnitten wurde, sodass ein Aufrufer eine Teilantwort niemals mit einer vollständigen verwechseln kann.

Designentscheidungen, die es wert sind, verteidigt zu werden

Das Repository läuft mit null API-Schlüsseln und null Kosten. Ein Prüfer, der dies klont, erhält ein funktionierendes System, nicht eine README, die eines beschreibt. Das zwang die Provider-Abstraktion von Anfang an zu existieren, anstatt nachträglich eingebaut zu werden.

Die Schwärzung sitzt an der Tool-Grenze, nicht vor dem Prompt. Sie in den Agent zu legen, bedeutet, dass jeder zukünftige Aufrufer der Tool-Schicht sich an die Schwärzung erinnern muss. Sie in die Werkzeuge zu legen, macht es unmöglich, sie zu vergessen, und sie ist der am stärksten getestete Code im Repository.

Die Schwärzung bewahrt Identität, anstatt sie zu löschen. Dieselbe Adresse wird immer zu derselben <ip-1>, sodass das Modell weiterhin schlussfolgern kann, dass der Pod bei <ip-1> <ip-2> nicht erreichen kann, und das über einen Log-Auszug und ein Ereignis korrelieren kann. Alles auf ein <redacted> zu maskieren, würde genau die Struktur zerstören, aus der eine Ursache besteht.

Das ServiceAccount des Agents kann keine Secrets lesen und nichts schreiben. Die Fehlerinjektions-Harness in Phase 6 benötigt Schreibzugriff, um absichtlich Dinge zu brechen, also trägt sie ihre eigenen separaten Anmeldeinformationen. Der Agent bekommt nie welche.

Logzeilen sind nicht vertrauenswürdige Eingaben. Jeder, der in ein Log schreiben kann, das ich lese, kann meinem Agenten Anweisungen schreiben. Das ist im Bedrohungsmodell enthalten, und Phase 6 misst, was tatsächlich passiert, anstatt anzunehmen, dass der Prompt gehalten hat.

Dokumentation

Autor

Kostiantyn Osmakov cv.batpepe.online | @batpepe