opsgentic

🤖 OpsGentic — AI Agents for DevOps Automation

OpsGentic logo

Self-healing Kubernetes with AI agents.
OpsGentic turns an alert into a reviewed GitOps pull request — automated Root Cause Analysis, Validation, and Remediation, with a human in the loop.

OpsGentic website Kubernetes GitOps LangGraph multi-agent Model Context Protocol vLLM / OpenAI-compatible LLM Python 3.11+ License: GPLv3 PRs welcome

🌐 Website & Documentation  ·  Quickstart  ·  Architecture  ·  GitHub

Alert fires → agents find the root cause → propose a minimal manifest fix → open a PR on your GitOps repo → you approve → ArgoCD/Flux applies it.

No kubectl, no manual patching.

OpsGentic is an open-source AIOps / agentic SRE platform for Kubernetes incident response and auto-remediation. A multi-agent LangGraph pipeline performs automated root cause analysis on Prometheus/Alertmanager alerts (or a chat message), then remediates through GitOps — every change is a reviewable pull request opened on your ArgoCD/Flux repo, never a live kubectl mutation. Think of it as an AI SRE agent that turns alerts into self-healing infrastructure, with a human in the loop.

✨ Why OpsGentic

🧩 How it works

Prometheus/Alertmanager ─alert─▶ OpsGentic API ─enqueue─▶ Worker
                                                            │  RCA → Validation → [approve] → Action
   ArgoCD/Flux ◀─sync─ merge ◀─ Pull Request ◀──────────────┘
  1. A Grafana/Alertmanager webhook (or POST /chat) is enqueued; the API returns 202 { thread_id }.
  2. The worker runs RCA (root-cause hypothesis) → Validation (deterministic checks) → Action.
  3. Action reads the GitOps repo (read-only via MCP), proposes a minimal manifest edit, and opens a PR.
  4. You approve (or auto-approve); ArgoCD/Flux applies the merged change.

Deep dive: docs/ARCHITECTURE.md.

🧭 Editing the pipeline (blueprint)

The agent graph is declarative. Nodes, routing, and per-agent tool wiring live in config/pipeline.yaml, not in Python. Clone the repo, edit that file, and restart — the graph is rebuilt from the blueprint on startup.

# config/pipeline.yaml (agents section abbreviated)
entrypoint: rca
interrupt_before:
  - action                     # human-in-the-loop gate before opening a PR
nodes:
  - id: rca
    step: rca
    agents: [context, rca]
  - id: resolve_target
    step: resolve_target
    agents: [resolver]
  - id: validation
    step: validation
    agents: [validation]
  - id: action
    step: action
    agents: [remediation]
edges:
  - from: rca
    to: resolve_target
  - from: resolve_target
    to: validation
  - from: validation
    route: after_validation    # named router -> conditional edge
    branches:
      action: action
      rca: rca
      escalate: END
  - from: action
    to: END
agents:
  context:
    tools: [kubernetes, prometheus]
  remediation:
    tools: [kubernetes, github, prometheus]
  # rca / resolver / validation reason without MCP tools -> tools: []

Inspect and validate the blueprint from the CLI:

opsgentic pipeline show                  # print the active topology
opsgentic pipeline validate              # validate config/pipeline.yaml (exit 1 on error)
opsgentic pipeline validate my.yaml      # validate a specific file

Example — add a notify node after action:

  1. Register the step in src/opsgentic/pipeline/registry.py: 
    def notify_node(state: MachineState) -> dict:
    ...                                   # your logic; returns partial state
STEP_REGISTRY = {..., "notify": notify_node}
  2. Wire it in config/pipeline.yaml: ```yaml nodes:
    • id: notify step: notify agents: [] edges:
    • from: action to: notify # replaces: action -> END
    • from: notify to: END ```
  3. Run opsgentic pipeline validate, then restart. opsgentic pipeline show reflects the new graph.

Agent behavior (prompts) is tuned separately in the editable agent-skill library — see USAGE.md → Editing agent skills.

🚀 Quick start

One-command demo — provisions the cluster (or a local k3d/minikube/kind), ArgoCD, Prometheus, the demo apps, and opsgentic; forks the demo repo for you and only asks for a GitHub PAT:

./hack/demo-up.sh        # idempotent; ./hack/demo-down.sh to tear it down

Local dev — no cluster, just the graph:

python -m venv .venv && . .venv/bin/activate
pip install -e .
cp .env.example .env          # set LLM_BASE_URL / LLM_API_KEY (empty = canned fallback)

# try the full graph locally (synchronous, no cluster needed)
opsgentic --file examples/grafana_alert.json --source grafana --approve

Full walkthrough — one-command demo, local dev, and the manual end-to-end Kubernetes path (GitHub auth, ArgoCD, Alertmanager webhook, bootstrap.sh): QUICKSTART.md.

📚 Documentation

Doc What’s inside
Website Project homepage & docs hub
QUICKSTART.md Install & run — dev + Kubernetes, GitHub auth, ArgoCD, Alertmanager webhook, troubleshooting
docs/USAGE.md HTTP API, triggers, full configuration reference, editing agent skills, deploy
docs/ARCHITECTURE.md Agents, async queue/worker, graph flow, remediation & convergence, multi-repo resolution

🗺️ Roadmap

❓ FAQ

What is OpsGentic? An open-source AI agent for Kubernetes incident response. It reads Prometheus/Alertmanager alerts, runs automated root cause analysis with a multi-agent LangGraph pipeline, and opens a GitOps pull request with a minimal manifest fix — self-healing Kubernetes with a human in the loop.

How does OpsGentic remediate incidents without kubectl? It never mutates the cluster directly. All cluster and repo reads go through read-only MCP servers, and every change is written as a pull request on your GitOps repo, which ArgoCD or Flux applies after merge.

Which LLMs does it support? Any OpenAI-compatible endpoint — a self-hosted vLLM server, OpenAI, or other compatible APIs — configured via environment variables.

Does it work with ArgoCD and Flux? Yes. OpsGentic is GitOps-native and multi-repo: it discovers the owning repository from your ArgoCD/Flux Applications and supports GitHub, GitLab, and Gitea.

How do I try it quickly? Run ./hack/demo-up.sh for a one-command demo (cluster + ArgoCD + Prometheus + demo apps), or use the local-dev path with no cluster. See the Quickstart.

🤝 Contributing

Issues and PRs are welcome. Licensed under GPLv3. Website & docs: https://lehuannhatrang.github.io/opsgentic/

Keywords: Kubernetes · Kubernetes incident response · SRE · DevOps · AIOps · AI SRE agent · AI agent · agentic AI · multi-agent · LLM · vLLM · LangGraph · MCP · Model Context Protocol · auto-remediation · self-healing Kubernetes · self-healing infrastructure · root cause analysis · RCA · GitOps · ArgoCD · Flux · Prometheus · Alertmanager · alert remediation · incident response automation · pull request automation

This site is open source. Improve this page.