ai-automation-lab

내 K3s 클러스터를 대상으로 실행되는 인시던트 트라이지 에이전트입니다. Alertmanager가 알림을 발생시키면 클러스터 텔레메트리에 대한 읽기 전용 액세스로 조사하고, 사람이 조치를 취할 수 있는 순위가 매겨진 가설을 반환합니다. 그런 다음 그 가설이 맞았는지 기록합니다.

마지막 부분이 핵심입니다. 알림을 언어 모델에 연결하는 것은 주말 프로젝트에 불과합니다. 출력이 올바른지 측정하고, 비용을 제한하고, 건드리면 안 되는 것을 건드릴 수 없음을 입증하는 것이 실제 작업입니다.

이것은 시리즈 중 세 번째 랩입니다. 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"]

두 가지 속성은 관례적인 것이 아니라 구조적인 것입니다. 도구 출력은 모델에 도달하기 전에 마스킹을 거치므로, 에이전트가 잘못 작동하더라도 마스킹되지 않은 어떤 것도 클러스터 밖으로 나갈 수 없습니다. 또한 모델은 어떤 것도 실행하지 않습니다. 읽고, 추론하고, 제안할 뿐입니다. v1에서 수정 조치는 범위 밖입니다.

Related MCP server: kubeview-mcp

상태

단계별로 구축되었으며, 이 표가 그 솔직한 현재 상태입니다.

각 단계의 완료 정의와 내가 반대했던 브리프 부분을 포함한 전체 분석은 plan.md에 있습니다.

실행하기

여기 있는 어떤 것도 API 키, 데이터베이스 또는 클러스터 액세스가 필요 없습니다. 기본 프로바이더는 결정론적 mock이며, CI도 이것을 사용합니다.

uv sync
uv run pytest
uv run opsagent show-config

environment=local
log_level=INFO
log_json=None

품질 게이트, 동일한 네 가지 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 컨텍스트를 읽으므로 읽기 전용 컨텍스트를 가리키세요. 여섯 가지 도구는 get_pod_status, get_events, query_logs, query_metrics, get_recent_deploys, get_runbook입니다. 모든 결과에는 값이 몇 개 마스킹되었는지와 잘렸는지 여부가 포함되므로, 호출자는 부분적인 답을 완전한 답으로 착각할 수 없습니다.

방어할 가치가 있는 설계 결정

이 리포지토리는 API 키도 비용도 0인 상태로 실행됩니다. 이 저장소를 클론하는 검토자는 하나를 설명하는 README가 아니라 작동하는 시스템을 얻습니다. 그 덕분에 프로바이더 추상화가 나중에 소급 적용되는 것이 아니라 처음부터 존재해야 했습니다.

마스킹은 프롬프트 앞이 아니라 도구 경계에 있습니다. 마스킹을 에이전트에 두면 미래의 모든 도구 레이어 호출자가 마스킹을 기억해야 합니다. 도구에 두면 잊을 수 없으며, 이는 이 리포지토리에서 가장 많이 테스트된 코드입니다.

마스킹은 식별성을 지우는 대신 보존합니다. 같은 주소는 항상 같은 <ip-1>이 되므로, 모델은 <ip-1>의 파드가 <ip-2>에 도달할 수 없다는 것을 여전히 추론할 수 있고, 이를 로그 발췌와 이벤트에 걸쳐 연관지을 수 있습니다. 모든 것을 하나의 <redacted>로 마스킹하면 근본 원인을 구성하는 바로 그 구조가 파괴됩니다.

에이전트의 ServiceAccount는 시크릿을 읽을 수 없고 어떤 것도 쓸 수 없습니다. 6단계의 장애 주입 하네스는 일부러 문제를 일으키기 위해 쓰기 액세스가 필요하므로 별도의 자격 증명을 보유합니다. 에이전트는 절대 그런 자격 증명을 받지 않습니다.

로그 줄은 신뢰할 수 없는 입력입니다. 내가 읽는 로그에 쓸 수 있는 사람은 누구나 내 에이전트에 지시를 쓸 수 있습니다. 이것은 위협 모델에 포함되어 있으며, 6단계는 프롬프트가 유지되었다고 가정하는 대신 실제로 일어나는 일을 측정합니다.

문서

작성자

Kostiantyn Osmakov cv.batpepe.online | @batpepe