ai-automation-lab

自分のK3sクラスタに対して動作するインシデントトリアージエージェントです。Alertmanagerが発火すると、クラスタのテレメトリへの読み取り専用アクセスを使って調査し、人間が対応できるランク付けされた仮説を返します。その後、それが正しかったかどうかを記録します。

最後の部分がポイントです。アラートを言語モデルに流し込むのは週末プロジェクトです。出力が正しかったかを測定し、コストを制限し、触れてはいけないものに触れられないことを証明することが、実際の仕事です。

これはシリーズの3番目のラボです: devops-homelab-k3s-hybrid-cloud は監視対象のプラットフォームであり、 qa-engineering-lab は そのプラットフォームで6つの実際の欠陥を発見したテストスイートです。

アーキテクチャ

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

2つの特性は慣例ではなく構造的なものです。ツール出力はモデルに到達する前にリダクションを通過するため、エージェントが誤動作しても、リダクションされていないものがクラスタから出ることはありません。また、モデルは何も実行しません。読み取り、推論、提案のみ行います。修復はv1の範囲外です。

Related MCP server: kubeview-mcp

ステータス

フェーズごとに構築されており、この表が正直な状態です。

各フェーズの完了条件や、私が反対したブリーフの部分を含む完全な内訳は、plan.md にあります。

実行方法

ここで必要なものは、APIキー、データベース、クラスタアクセスのいずれもありません。デフォルトのプロバイダーは決定論的なモックであり、CIもこれを使用しています。

uv sync
uv run pytest
uv run opsagent show-config

environment=local
log_level=INFO
log_json=None

品質ゲート、同じ4つのCI実行:

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

ワークフロー同期には実行中のインスタンスとAPIキーが必要なため、クリーンなクローンからは動作しない唯一のものです:

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

ツールを手動で操作する

ツールレイヤーはエージェントの依存関係になる前にMCPサーバーであるため、エディタセッションから実際のクラスタに対してツールを使用できます。登録します:

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

アクティブなkubeconfigコンテキストを読み取るため、読み取り専用のものを指定してください。6つのツールは get_pod_status、get_events、query_logs、query_metrics、get_recent_deploys、get_runbook です。すべての結果には、リダクションされた値の数と切り詰められたかどうかが含まれるため、呼び出し元が部分的な回答を完全なものと誤解することは決してありません。

擁護する価値のある設計上の決定

このリポジトリは、APIキーゼロ、コストゼロで動作します。 クローンするレビュアーは、説明するREADMEではなく、動作するシステムを手に入れます。これにより、プロバイダー抽象化が後付けではなく最初から存在することを余儀なくされました。

リダクションはプロンプトの前ではなく、ツール境界にあります。 エージェントに置くと、ツールレイヤーの将来のすべての呼び出し元がリダクションを覚えておく必要があります。ツールに置くと、忘れることが不可能になり、リポジトリ内で最もテストされたコードになります。

リダクションは消去ではなくアイデンティティを保持します。 同じアドレスは常に同じ <ip-1> になるため、モデルは <ip-1> のポッドが <ip-2> に到達できないことを推論し、それをログの抜粋とイベントの間で関連付けることができます。すべてを1つの <redacted> にマスクすると、根本原因を構成する構造が正確に破壊されます。

エージェントのServiceAccountはシークレットを読み取れず、何も書き込めません。 フェーズ6のフォールトインジェクションハーネスは、意図的に壊すために書き込みアクセスが必要なため、独自の別の資格情報を持ちます。エージェントは決してそれを取得しません。

ログ行は信頼できない入力です。 私が読むログに書き込める人は誰でも、私のエージェントに指示を書き込めます。これは脅威モデルに含まれており、フェーズ6ではプロンプトが保持されたと想定するのではなく、実際に何が起こるかを測定します。

ドキュメント

著者

Kostiantyn Osmakov cv.batpepe.online | @batpepe