AI Handbook

Understanding KAP Federated Runtimes and Environments

1 Introduction

Kav AI Platform (KAP) uses a Federated Runtime architecture to manage multiple AI systems with conflicting dependencies. By isolating different frameworks into dedicated Python environments, we ensure maximum stability and flexibility for both Atlas (CrewAI) and Argus/Orion (Google ADK).

---

1.1 🏗️ The Federated Model

To avoid versioning conflicts (specifically opentelemetry-sdk incompatibilities), KAP separates backends into independent processes managed by a central Gateway.

graph TD
    UI[Frontend / AG-UI] -->|Port 8080| GW[Gateway]
    GW -->|Port 50051| R1[CrewAI Runtime]
    GW -->|Port 50052| R2[ADK Runtime]
    
    subgraph "default environment"
    R1
    end
    
    subgraph "adk environment"
    R2
    end

---

1.2 1. The default Environment (Atlas)

This environment is the primary workspace for general orchestration and planning tasks.

• Primary System: crewai (Atlas)
• Secondary System: datagraphcg (Phantom)
• Key Features: Multi-agent crews, sequential/hierarchical task flows, and LangGraph integration.
• Port: 50051
• Execution: pixi run serve-crewai

---

1.3 2. The adk Environment (Argus / Orion)

This environment is purpose-built for high-fidelity reasoning and automated evaluation using the Google ADK framework.

• Primary Systems: dataadk (Argus), orion (Orion)
• Key Features: Sequential agent pipelines, rigorous evaluation frameworks, and dedicated trace UIs.
• Port: 50052
• Execution: pixi run -e adk serve-adk

---

1.4 🧪 Dependency Isolation Strategy

1.4.1 The OpenTelemetry Conflict

There is a fundamental conflict between crewai and google-adk regarding the opentelemetry-sdk version:

• crewai requires a modern version compatible with the openinference-instrumentation suite.
• google-adk requires an earlier version for its internal telemetry.

Solution: By splitting these into separate pixi environments, we can run both systems on the same machine without crashing the Python interpreter.

---

1.5 🚦 Routing & Communication

The Gateway (kavai.gateway.app) acts as a thin HTTP/SSE reverse proxy. It does not import AI frameworks directly, making it lightweight and conflict-free.

1.5.1 Routing Logic

When a request hits :8080/chat/agui/stream, the Gateway inspects the system_type:

• crewai | datagraphcg → Proxied to localhost:50051
• dataadk | orion → Proxied to localhost:50052

---

1.6 🛠️ Developer Operations

1.6.1 Running All Services Locally

To start the full federated backend in one command:

pixi run serve-all

This script (ai/scripts/start-all.sh) launches the Gateway and both Runtimes in the background.

1.6.2 Environment Management

• Add CrewAI dep: Add to [tool.pixi.feature.crewai.pypi-dependencies]
• Add ADK dep: Add to [tool.pixi.feature.adk.pypi-dependencies]
• Update all: pixi update (handles both environments independently).

---

Last Updated: 2026-04-05