How julie-elkins/k8s-triage-agent works
k8s-triage-agent is a read-only Kubernetes triage agent that preserves distinctions between clean results and checks that were refused, unavailable, or inconclusive. The human workflow starts a run, lists pods before targeting one, gathers pod description, logs, and namespace metrics, then diagnoses and reports what could not be checked before pausing for approval. It also exposes the four read-only tools over MCP stdio. The excerpts show the API, contract, and orchestration seams; some graph-stage transitions and unsampled capabilities are documented but not directly visible in the excerpts.
Main entry points: server.py MCP server · tools.py Read-only tools · cli.py CLI runner · graph.py Evidence collection
Components 18
Entry points
- CLI runner
src/k8s_triage/cli.py - MCP server
src/k8s_triage/server.py
Triage workflow
- Run intake
src/k8s_triage/graph.py - Pod targeting
src/k8s_triage/graph.py - Evidence collection
src/k8s_triage/graph.py - Diagnosis and report
src/k8s_triage/graph.py - Approval gate
src/k8s_triage/graph.py
Cluster access
- Kubernetes client
src/k8s_triage/cluster.py - Kubernetes API
- RBAC boundary
deploy
Tool interfaces
- Local toolbelt
src/k8s_triage/toolbelt.py - MCP toolbelt
src/k8s_triage/mcp_toolbelt.py - Read-only tools
src/k8s_triage/tools.py
Contracts and state
- Outcome contracts
src/k8s_triage/contracts.py - Checkpointing
src/k8s_triage/checkpointing.py - SQLite checkpoints
Other components
- Operator
- MCP client
Connections 19
- Operator → CLI runner: starts run
src/k8s_triage/cli.py - CLI runner → Run intake: invokes graph
src/k8s_triage/cli.py - Run intake → Pod targeting: routes valid input
src/k8s_triage/graph.py - Pod targeting → Evidence collection: dispatches checks
src/k8s_triage/graph.py - Evidence collection → Local toolbelt: calls tools
src/k8s_triage/graph.py - Local toolbelt → Read-only tools: delegates
src/k8s_triage/toolbelt.py - Read-only tools → Kubernetes client: reads cluster
src/k8s_triage/tools.py - Kubernetes client → Kubernetes API: calls API
README.md - RBAC boundary → Kubernetes API: limits access
README.md - Evidence collection → Diagnosis and report: provides outcomes
src/k8s_triage/graph.py - Diagnosis and report → Approval gate: presents findings
src/k8s_triage/graph.py - CLI runner → Checkpointing: opens saver
src/k8s_triage/cli.py - Checkpointing → Outcome contracts: serializes types
src/k8s_triage/checkpointing.py - Checkpointing → SQLite checkpoints: writes state
src/k8s_triage/checkpointing.py - MCP client → MCP server: calls tools
README.md - MCP server → Read-only tools: calls handlers
src/k8s_triage/server.py - MCP server → Kubernetes client: provides client
src/k8s_triage/server.py - MCP toolbelt → MCP server: uses stdio
src/k8s_triage/mcp_toolbelt.py - Read-only tools → Outcome contracts: returns outcomes
src/k8s_triage/tools.py