{
  "markdown": "# DevOps Incident Analyzer\n\nMulti-datasource incident analysis agent powered by LangGraph and 7 datasource MCP servers. A supervisor orchestrates specialist sub-agents that query Elasticsearch, Kafka, Couchbase Capella, Kong Konnect, GitLab, Atlassian (Jira/Confluence), and AWS in parallel, then correlates findings into actionable incident reports.\n\nThe repo also ships a second top-level agent, **elastic-iac** -- a GitOps proposer for Elastic Cloud infrastructure changes (served by an 8th MCP server on port 9086). Selected by the UI agent toggle, it answers \"change it\" requests by editing deployment/policy JSON and opening a GitLab merge request; CI plans and humans merge/apply (agent proposes, GitOps disposes). See [docs/architecture/elastic-iac-proposer.md](docs/architecture/elastic-iac-proposer.md).\n\n## Architecture\n\n```\nUser Query\n    |\n[classify] -> simple:        responder -> followUp -> END\n    |          learn cmd:     [HIL learning lane] -> END   (HIL_LEARNING_ENABLED)\n    |          complex:\n[normalize] -> [selectRunbooks] -> [entityExtractor] -> [awsEstateRouter] -> [resolveIdentifiers]\n    |\n[supervisor] -> fan-out via Send API\n    |\n[elastic]  [kafka]  [capella]  [konnect]  [gitlab]  [atlassian]  [aws]\n    |         |         |          |         |          |          |\n[align] -> check cross-datasource consistency, retry if gaps\n    |\n[aggregate] -> [extractFindings] -> correlate timeline, causal chains, confidence score\n    |\n[enforceCorrelations] -> mandatory cross-agent correlation, cap confidence if degraded\n    |\n[checkConfidence] -> gate on minimum confidence threshold\n    |\n[validate] -> anti-hallucination check, retry aggregate on fail\n    |\n[proposeInvestigate | proposeMonitor | proposeEscalate] -> [aggregateMitigation] -> remediation\n    |\n[followUp] -> suggested next questions\n    |\nIncident Report\n```\n\nAn explicit `learn from TICKET-123` turn routes into the human-in-the-loop **learning lane** (`classify -> learnFetchTicket -> ... -> applyLearnings`, gated by `HIL_LEARNING_ENABLED`), which distills confirmed root causes and diagnostic knowledge from a resolved ticket back into the knowledge graph and durable memory. See [docs/architecture/agent-pipeline.md](docs/architecture/agent-pipeline.md#hil-learning-lane).\n\nSee [docs/architecture/agent-pipeline.md](docs/architecture/agent-pipeline.md) for the full 31-node StateGraph (21 base nodes + 4 gated knowledge-graph nodes + 6 gated HIL-learning nodes; `grep -c addNode packages/agent/src/graph.ts` = 31) including retry loops, conditional edges, the SIO-828 AWS estate router, the SIO-681 cross-agent correlation enforcement detour, and the SIO-1126 human-in-the-loop learning lane. The separate 31-node elastic-iac proposer graph is documented in [docs/architecture/elastic-iac-proposer.md](docs/architecture/elastic-iac-proposer.md).\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Copy and fill in environment variables\ncp .env.example .env\n\n# Start MCP servers (separate terminals) -- minimal example\nMCP_TRANSPORT=sse MCP_PORT=9080 bun packages/mcp-server-elastic/src/index.ts\nMCP_TRANSPORT=http MCP_PORT=9081 bun packages/mcp-server-kafka/src/index.ts\n\n# Start the web frontend + agent\nbun run --filter @devops-agent/web dev\n```\n\nOpen http://localhost:5173. For all eight MCP servers see [docs/deployment/local-development.md](docs/deployment/local-development.md).\n\n## Project Structure\n\n```\nagents/                          Gitagent declarative definitions (YAML/Markdown)\n  incident-analyzer/\n    agent.yaml                   Orchestrator: model, tools, skills, sub-agents, compliance\n    SOUL.md / RULES.md           Identity and hard constraints\n    agents/                      7 sub-agents: elastic, kafka, capella, konnect, gitlab, atlassian, aws\n    tools/                       MCP tool schemas with dynamic prompt templates\n    skills/                      Procedural knowledge (normalize, aggregate, mitigate)\n  elastic-iac/                   Second agent: GitOps proposer for Elastic Cloud infra changes\n\npackages/\n  gitagent-bridge/               YAML-to-LangGraph adapter\n  agent/                         LangGraph 31-node pipeline (21 base + 4 gated knowledge-graph + 6 gated HIL-learning nodes) plus a separate 31-node elastic-iac proposer graph\n  shared/                        Cross-package types, Zod schemas, Agent Memory REST client (SIO-938)\n  checkpointer/                  Transient per-thread LangGraph state (memory / bun:sqlite)\n  observability/                 Pino logging, OpenTelemetry, LangSmith\n  knowledge-graph/               Embedded entity + correlation graph (lbug/LadybugDB; SIO-850/954/965; gated on KNOWLEDGE_GRAPH_ENABLED)\n  memory-pr/                     PR-based human-in-the-loop for durable agent learnings (SIO-849)\n  skillflow/                     Declarative workflow (DAG) loader + executor (SIO-848)\n  mcp-server-elastic/            Elasticsearch MCP (multi-deployment)\n  mcp-server-kafka/              Kafka MCP (local/MSK/Confluent)\n  mcp-server-couchbase/          Couchbase Capella MCP (query analysis)\n  mcp-server-konnect/            Kong Konnect MCP (API gateway)\n  mcp-server-gitlab/             GitLab MCP (proxy + code analysis)\n  mcp-server-atlassian/          Atlassian MCP (Jira/Confluence proxy)\n  mcp-server-aws/                AWS MCP (multi-estate via cross-account AssumeRole)\n  mcp-server-elastic-iac/        Elastic IaC MCP (GitOps proposer tools, port 9086)\n  mcp-server-knowledge-graph/    In-process Knowledge Graph MCP (curated kg_* + read-only Cypher, port 9087)\n\napps/\n  web/                           SvelteKit frontend (Svelte 5, Tailwind, SSE streaming; 34 components)\n```\n\n## MCP Servers\n\n| Server | Port | Tools | Config |\n|--------|------|-------|--------|\n| Elasticsearch | 9080 | 117 (101 cluster incl. 9 ML anomaly-detection + 4 ES\\|QL/async-search + 16 conditional cloud/billing on `EC_API_KEY`) | `ES_URL`, `ES_API_KEY`, multi-deployment via `ELASTIC_DEPLOYMENTS` |\n| Kafka | 9081 | 11-61 (11 base + up to 50 gated: SR + ksqlDB + Connect + REST Proxy) | `KAFKA_PROVIDER` (local/msk/confluent), `KAFKA_BROKERS` |\n| Couchbase Capella | 9082 | ~39 (SIO-1107 official Couchbase tools: buckets, INFER, EXPLAIN, Index Advisor, covering-index detectors) | `COUCHBASE_URL`, `COUCHBASE_USERNAME`, `COUCHBASE_PASSWORD` |\n| Kong Konnect | 9083 | 67+ | `KONNECT_ACCESS_TOKEN`, `KONNECT_REGION` |\n| GitLab | 9084 | 21+ (proxy + code analysis) | `GITLAB_PERSONAL_ACCESS_TOKEN`, `GITLAB_INSTANCE_URL` |\n| Atlassian | 9085 (OAuth :9185) | proxy + custom | `ATLASSIAN_SITE_NAME`, `ATLASSIAN_UPSTREAM_MCP_URL`, `ATLASSIAN_READ_ONLY` |\n| AWS | 3001 (SigV4 proxy) | multi-estate read-only (CloudWatch incl. Metrics Insights, EC2 + network-path tracing, ECS, Lambda, RDS, S3, X-Ray) | `AWS_MCP_URL`, `AWS_ESTATES`, `AWS_DEFAULT_ESTATE` |\n| Elastic IaC | 9086 | GitOps proposer tools (terraform/git/gitlab/elastic-cloud) | `ELASTIC_IAC_MCP_URL`, `ELASTIC_IAC_GITLAB_TOKEN` |\n| Knowledge Graph | 9087 (in-process) | curated `kg_*` graph readers + read-only Cypher (lbug); off unless enabled | `KNOWLEDGE_GRAPH_ENABLED`, `KG_MCP_ALLOW_CYPHER` |\n\n## Agent Memory (live-memory backend)\n\nBoth agents (incident-analyzer and elastic-iac) keep durable, cross-session **live memory** -- distinct from the LangGraph checkpointer, which holds only transient per-thread state. Live memory is read into the prompt at session bootstrap and appended at safe boundaries through a single writer (`packages/agent/src/memory-writer.ts`: `readLiveMemory` / `appendDailyLog` / `recordKeyDecision`, gated by `LIVE_MEMORY_ENABLED`, always PII-redacted).\n\nThe storage behind that writer is swappable via `LIVE_MEMORY_BACKEND` (SIO-938):\n\n- **`file`** (default) -- git-tracked markdown under `agents/<agent>/memory/runtime/{context,key-decisions,dailylog}.md` + `memory/wiki/`. Human-readable, PR-reviewable.\n- **`agent-memory`** -- the [Couchbase Agent Memory](https://docs.couchbase.com/) REST service. Adds semantic recall and TTL decay. Mapping: `context` + `key-decisions` + wiki pages -> durable **facts** (no TTL); `dailylog` turns -> conversational **messages** (short TTL); on bootstrap the agent semantic-searches its past sessions for relevant context. One Agent Memory user per agent (`incident-analyzer`, `elastic-iac`); each chat thread is a session.\n\nThe backend is a direct REST client in `packages/shared` (no MCP server, no LLM tool surface) wired through the lifecycle bootstrap/teardown seams. Writes are queued behind the synchronous writer and drained at session teardown, so the default file path is unchanged when `LIVE_MEMORY_BACKEND` is unset. See [the design spec](docs/superpowers/specs/2026-06-17-couchbase-agent-memory-backend-design.md).\n\nBeyond the bootstrap recall + dailylog breadcrumb, the agents use memory in several specific scenarios — IaC-change proposal facts + \"check my MR\" recall, in-flight fleet-upgrade recovery across sessions, post-turn skill-learning proposals (`kind:skill`), lifecycle reconciliation of proposed -> applied/failed changes, and annotation-keyed dedup. The full read/write catalog is in [docs/architecture/agent-memory.md](docs/architecture/agent-memory.md#scenario-catalog).\n\n## Knowledge Graph (lbug)\n\nAn optional embedded entity-and-correlation graph (lbug/LadybugDB), gated on `KNOWLEDGE_GRAPH_ENABLED`. It records the services, incidents, deployments, and config changes a turn touches, so a later turn can recall service dependencies, vector-similar past incidents, and a deployment's change history. The graph is exposed to the elastic-iac agent through an **in-process MCP server on :9087** (it must run in-process because embedded lbug takes an exclusive file lock) with curated `kg_*` readers plus a read-only-guarded `kg_run_cypher`. Eight pipeline nodes write/enrich it across the two agents (`recordEntities`/`graphEnrich`/`recordRootCause`/`recordBindings`; `recordIacPrompt`/`graphEnrichIac`/`recordIacEntities`/`recordIacOutcome`), plus a scheduled cron topology sweep (SIO-1104). `recordBindings` (SIO-1100 W8) writes the turn's confirmed telemetry-to-service bindings, which `resolveIdentifiers` reads back on later turns (SIO-1101 R7). It joins to Agent Memory by shared annotation keys. Full deep-dive: [docs/architecture/knowledge-graph.md](docs/architecture/knowledge-graph.md).\n\n## Commands\n\n```bash\nbun install                     # Install all workspace dependencies\nbun run test                    # Run all tests\nbun run typecheck               # TypeScript check all packages\nbun run lint                    # Biome lint check\nbun run lint:fix                # Biome auto-fix\n\n# Run specific package tests\nbun test packages/gitagent-bridge/src/index.test.ts\nbun test packages/agent/src/validation.test.ts\n```\n\n### Evals & audits\n\nOn-demand quality harness (none run in CI). Scripts are mirrored into the root `package.json`, so `bun run eval:*` works from the repo root:\n\n```bash\nbun run eval:agent                 # end-to-end LangSmith final_response regression (full graph)\nbun run eval:incident-replay       # live-replay incident eval + trajectory-grounded evaluators\nbun run eval:incident-replay -- --ticket DEVOPS-1234   # scope to one dataset example (SIO-1454)\nbun run eval:mcp-tool              # MCP tool-call correctness eval (per datasource)\nbun run eval:tool-probe            # direct per-tool health probe (which tools return data)\nbun run eval:spec-audit            # tier-1 static/semantic OKF spec audit\n```\n\nFull reference (tiers, sound-freeze record/replay, feedback keys, cost) in [`packages/agent/src/eval/README.md`](packages/agent/src/eval/README.md) and [docs/development/testing.md](docs/development/testing.md).\n\n## Environment Variables\n\nSee [.env.example](.env.example) for the full list. Minimum required:\n\n- `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` -- Bedrock LLM access\n- `ES_URL`, `ES_API_KEY` -- Elasticsearch connection\n- `ELASTIC_MCP_URL`, `KAFKA_MCP_URL`, `COUCHBASE_MCP_URL`, `KONNECT_MCP_URL`, `GITLAB_MCP_URL`, `ATLASSIAN_MCP_URL`, `AWS_MCP_URL` -- MCP server URLs for the agent\n- `ATLASSIAN_UPSTREAM_MCP_URL` -- upstream Atlassian Cloud Rovo endpoint (the local proxy forwards to it); `ATLASSIAN_SITE_NAME` -- your Atlassian Cloud site\n- `AWS_ESTATES`, `AWS_DEFAULT_ESTATE` -- multi-estate AWS config (cross-account AssumeRole)\n- `ELASTIC_IAC_MCP_URL`, `ELASTIC_IAC_GITLAB_TOKEN` -- elastic-iac agent: IaC MCP server URL and the GitLab token used to open merge requests\n\nOptional (live memory, all off/file by default):\n\n- `LIVE_MEMORY_ENABLED` -- turn live memory on (read at bootstrap, append at teardown)\n- `LIVE_MEMORY_BACKEND` -- `file` (default) or `agent-memory` (Couchbase Agent Memory REST)\n- `AGENT_MEMORY_BASE_URL`, `AGENT_MEMORY_ENABLED` -- the Agent Memory service (used only when `LIVE_MEMORY_BACKEND=agent-memory`)\n- `AGENT_MEMORY_BEARER_TOKEN` -- OIDC bearer token, only if the service runs with `OIDC_AUTH_ENABLED`\n- `AGENT_MEMORY_DAILYLOG_TTL_SECONDS` -- short TTL for dailylog breadcrumbs (omit for no decay; facts are always durable)\n- `HIL_LEARNING_ENABLED` -- human-in-the-loop learning lane; defaults ON (kill-switch semantics -- the lane only fires on an explicit `learn from TICKET-123` command, so it never triggers on normal traffic). Set to `false` to disable. Requires `KNOWLEDGE_GRAPH_ENABLED`.\n- `RESOLVE_IDENTIFIERS_ENABLED` -- resolve the incident service to canonical per-datasource identifiers before fan-out; defaults ON\n- `KG_BINDINGS_WRITE_ENABLED` / `KG_BINDINGS_READ_ENABLED` -- telemetry-binding write (W8) and read (R7) paths on the knowledge graph; both default ON when the graph is enabled\n\nSee [docs/configuration/environment-variables.md](docs/configuration/environment-variables.md) for the full AWS estate and elastic-iac configuration.\n\n## Documentation\n\n| Need to... | Go to... |\n|------------|----------|\n| Full documentation index | [docs/README.md](docs/README.md) |\n| Understand the architecture | [System Overview](docs/architecture/system-overview.md) |\n| Set up the project | [Getting Started](docs/development/getting-started.md) |\n| Deploy to AgentCore | [AgentCore Deployment](docs/deployment/agentcore-deployment.md) |\n| Add or modify MCP tools | [Adding MCP Tools](docs/development/adding-mcp-tools.md) |\n\n## Tech Stack\n\n- **Runtime**: Bun\n- **Agent**: LangGraph TypeScript with AWS Bedrock (Claude Sonnet/Haiku)\n- **Frontend**: SvelteKit, Svelte 5 runes, Tailwind CSS v4\n- **MCP**: Model Context Protocol SDK for tool integration\n- **Validation**: Zod\n- **Linting**: Biome\n- **Tracing**: LangSmith\n",
  "bytes": 14591,
  "sha": "9d0bbd45f2fc4da0b717d5e8944c73ec60a7803cc3a843e8f20d9e10529a85e1",
  "repo_slug": "zx8086/devops-incident-analyzer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_zx8086_devops_incident_analyzer_agents_e_dfc23abe/readme"
}