compagnonsdudev/kex-agent-ai repository overview

⁠Kex Agent AI

A governed AI agent for Kafka operations. It watches your integration processes through MCP tools, explains what it sees, and asks a named human before it acts — every decision carrying its confidence, its evidence and an audit trail.

Built on Spring Boot 4 / Spring AI 2, Java 25. Ships with a browser console (the Control Center) served by the agent itself, no build step and no CDN. The console manages MCP connections at runtime, shows session activity and lifecycle, and includes a Playground for tools, resources and parameterized resource templates.

• Source, issues and full documentation: https://github.com/devdownin/Kex-agent-ai⁠
• Licence: GPL-3.0-or-later

⁠Tags

Pre-releases never move latest — a docker pull without a tag should not bring back code nobody has finished judging.

linux/amd64 only: an arm64 image would mean QEMU and an emulated Maven build, an order of magnitude more build time. Each image ships an SBOM, and is scanned for vulnerabilities before it is pushed — the scan runs on a locally loaded build, so a vulnerable image is never published first and judged afterwards. After the push it is pulled back from the registry and started, because a successful push says the layers left, not that the manifest is servable.

⁠Quick start

Against a Kafka SQL Explorer you already run:

docker run --rm -p 8081:8081 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e KEX_AGENT_API_KEY="$(openssl rand -hex 32)" \
  -e KAFKA_EXPLORER_URL=http://host.docker.internal:8080 \
  compagnonsdudev/kex-agent-ai:latest

Then open http://localhost:8081⁠ and paste the same bearer once — it lives in sessionStorage and never leaves the browser. Or talk to the API directly:

curl -X POST localhost:8081/api/agent/chat \
  -H "Authorization: Bearer $KEX_AGENT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message":"List the topics whose name starts with demo. and tell me which ones are empty."}'

The whole stack — Kafka 4.3 (KRaft), Explorer with its MCP server on, and this agent wired to it — is one docker compose up away from the repository⁠.

⁠MCP from the browser

Under Technical → MCP servers, connections can be tested before they are added, enabled or disabled, restricted per tool, diagnosed, and imported/exported. HTTP, SSE and stdio transports are supported. The same workspace exposes active/idle MCP sessions and recent activity. Its Playground lets you call tools, browse/read resources and select resource templates; template fields are generated immediately from the selected template instead of requiring a URI to be assembled manually.

Runtime connections can be encrypted and persisted with KEX_MCP_STORAGE_KEY. For stdio servers, executables remain opt-in through KEX_MCP_STDIO_ALLOWED_COMMANDS. MCP sessions expire after 30 minutes of inactivity by default.

⁠Kafka operational reviews

On an agent image built after this feature is released, and with a compatible Kafka SQL Explorer MCP server connected, the agent can answer (check its advertised tools):

Configure topic policies and DLQ routes on Kafka SQL Explorer, not on the agent. For a baseline that survives Explorer restarts or works across replicas, configure its shared lag history directory on a writable volume with interprocess locking. See Kafka SQL Explorer's deployment example⁠ and the agent's MCP guide⁠. The agent distinguishes declarations from live observations and treats unavailable data as unmeasured.

⁠Configuration

An unreachable MCP server never blocks startup: the agent boots, says so, and keeps serving what it still can. Every setting, with its reasons⁠.

⁠Health and observability

The container exposes 8081 and runs as an unprivileged user (10001:10001).

⁠Persistence

/var/lib/kex holds everything the agent remembers outside a database: long-term facts, skills a human approved, the operating charter, and the encrypted MCP connections created from the console. It is declared as a volume — mount a named one over it, or those survive only as long as the container does:

docker run --rm -p 8081:8081 -v kex_state:/var/lib/kex ... compagnonsdudev/kex-agent-ai:latest

With the shared-memory profile and a PostgreSQL datasource, memory, skills, the supervision audit and the decision state move to the database instead — which is what you want behind a load balancer, where a decision approved on one replica has to exist for the others. The encrypted MCP connections stay on disk either way, so the volume is never pointless.

⁠What it will not do

The Kafka SQL Explorer MCP server is read-only by default. In front of it the agent observes and recommends; it does not act. Where a capability can act, autonomy is declared per capability, an execution mode can only narrow it, and anything below the confidence floor goes back to a human. Nothing here is a default you inherit by accident: an unlisted capability is forbidden.