Runtime & Systems
Processes & ports
The backend is a small set of processes fronted by the Gateway:
| Process | Module | Port | Started by |
|---|---|---|---|
| Gateway | kavai.gateway.app:app |
8080 | scripts/start-gateway.sh (serve-gateway) |
| ADK Runtime | kavai.app:app |
50052 | scripts/start-runtime-adk.sh (serve) |
| Kawa adapter | servers.kawa (python -m servers.kawa) |
8082 | serve-kawa-adapter (isolated kawa env) |
pixi run serve-all (→ scripts/start-all.sh) clears ports 8080/50052 and launches the runtime and gateway together. See Environments & operations.
Routing
The Gateway is a thin HTTP/SSE reverse proxy — it does not import AI frameworks, keeping it lightweight and conflict-free. Every chat request hits POST /chat/agui/stream; the gateway picks a backend from the request’s system_type:
SYSTEM_TO_BACKENDmapsargus/dataadk/orion→ the adk backend andkawa/hermes→ the kawa backend.BACKEND_URLSresolves those toADK_BACKEND_URL(defaulthttp://localhost:50052) andKAWA_ADAPTER_URL(defaulthttp://127.0.0.1:8082).- Retired names (
atlas,crewai,phantom,datagraphcg, …) fall back to the default backend with a warning (SystemRouter.resolve_system).
Those defaults are the deployed reality, not just a local convenience: on Cloud Run the web app, the gateway and the Kawa adapter run as three containers in one service (kap-dev), and Cloud Run sidecars share a network namespace. They reach each other on localhost — the same shape docker compose up gives you over its bridge network, with no public address and no *.run.app URL to keep in sync.
The traffic runs in both directions, which is why co-location matters rather than being a tidiness preference:
| from | to | address |
|---|---|---|
| gateway | Kawa adapter | http://localhost:8082 (KAWA_ADAPTER_URL) |
| Kawa adapter | gateway | http://localhost:8080 (KAVAI_GATEWAY_URL) |
| gateway | web app | http://localhost:3000 (NEXT_PUBLIC_APP_URL) |
| web app | kap-render (the GPU render worker, Cloud Run us-east4) |
https://kap-render-hsf3d7ur5q-uk.a.run.app (KAP_RENDER_SERVICE_URL) — only the two render/* routes, and only on a host without a GPU; unset locally, where the routes render themselves |
The second row is the one that forced the arrangement. Kawa calls the gateway’s image-skill endpoint (ADR-007, docs/adr/) for surface-analysis, and while Kawa ran as its own Cloud Run service (kap-kawa-dev, now retired) it had no address to call: the gateway is a sidecar with no ingress of its own, so nothing outside the pod can dial it. The same property is why the certification suite cannot be pointed at dev.
The gateway also serves GET /health, GET /chat/agui/capabilities, GET /systems, and GET /systems/verified. The full request/response contract is CONTRACT-CDC-001.
The systems
Which systems load is controlled by KAVAI_SYSTEMS (comma-separated) in systems/__init__.py — each is lazily imported via importlib; unset loads all active systems. The runtime default is argus,orion,kawa.
| System | Module | What it is |
|---|---|---|
| dataadk | kavai.systems.dataadk_package.system |
The packaged DataADK reference — a thin wrapper over the kavai-dataadk package, byte-synced with KavApps kavai_server. |
| argus | kavai.systems.argus.system |
The in-repo DataADK track — a Google ADK sequential NL-to-SQL pipeline. The improvement fork of DataADK; the default engine until 2026-09-26, when Kawa became KAP’s default (SYSTEM_TYPE overrides). |
| orion | kavai.systems.orion.system |
The next-gen multi-agent ADK 2.x pipeline (investigation manager, context manager, SQL guardrails, T3 memory). Requires ADK 2.x. |
| kawa | kavai.systems.kawa.runtime |
A tool-using AG-UI agent (API 584 IOW workflow, Kawa/hermes runtime). Legacy alias hermes → same module. Runs as the standalone adapter on :8082. |
Registration flows through SystemRegistry (systems/base.py); the packaged dataadk always resolves to the package and argus always to the in-repo module (the KAVAI_DATAADK_IMPL selector is retired inside KAP — see DataADK packages).
The in-process kawa system in the ADK runtime needs the external Kawa (hermes-agent) runtime, which the adk environment does not install — it registers but cannot execute there. The runnable Kawa integration is the standalone Kawa adapter (serve-kawa-adapter, :8082) in the isolated kawa environment.