Kagenti Lifecycle Operators

This document provides detailed information about each component of the Kagenti platform.

Table of Contents

• Overview
• Architecture Diagram
• Agent Lifecycle Operator
• MCP Gateway
• Plugins adapter
• Kagenti UI
• Identity & Auth Bridge
• Infrastructure Services
• Supported Agent Frameworks
• Communication Protocols

Overview

Kagenti is a cloud-native middleware providing a framework-neutral, scalable, and secure platform for deploying and orchestrating AI agents through a standardized REST API. It addresses the gap between agent development frameworks and production deployment by providing:

• Authentication and Authorization — Secure access control for agents and tools
• Trusted Identity — SPIRE-managed workload identities
• Deployment & Configuration — Kubernetes-native lifecycle management
• Scaling & Fault-tolerance — Auto-scaling and resilient deployments
• Discovery — Agent and tool discovery via A2A protocol
• Persistence — State management for agent workflows

Value Proposition

Despite the extensive variety of frameworks available for developing agent-based applications, there is a distinct lack of standardized methods for deploying and operating agent code in production environments, as well as for exposing it through a standardized API. Agents are adept at reasoning, planning, and interacting with various tools, but their full potential can be limited by deployment challenges.

Kagenti addresses this gap by enhancing existing agent frameworks with production-ready infrastructure.

For a detailed architecture diagram showing component interactions and data flow, see Technical Details.

Architecture Diagram

All the Kagenti components and their deployment namespaces

┌───────────────────────────────────────────────────────────────────────┐
│                           Kubernetes Cluster                          │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                      kagenti-system Namespace                   │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐ │  │
│  │  │ Kagenti UI │  │ Shipwright │  │  Ingress   │  │   Kiali    │ │  │
│  │  │            │  │  (Builds)  │  │  Gateway   │  │            │ │  │
│  │  │            │  │            │  │            │  │            │ │  │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘ │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                       │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │                Workload Namespaces (team1, team2, ...)           │ │
│  │     ┌──────────────┐  ┌──────────────┐   ┌──────────────┐        │ │
│  │     │  A2A Agents  │  │  MCP Tools   │   │ Custom       │        │ │
│  │     │  (LangGraph, │  │  (weather,   │   │ Workloads    │        │ │
│  │     │   CrewAI,    │  │   slack,     │   │              │        │ │
│  │     │   AG2...)    │  │   fetch...)  │   │              │        │ │
│  │     └──────────────┘  └──────────────┘   └──────────────┘        │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                       │
│           ┌────────────────────┐  ┌────────────────────┐              |
│           │  gateway-system    │  │     mcp-system     │              │
│           │  ┌──────────────┐  │  │  ┌──────────────┐  │              │
│           │  │ MCP Gateway  │  │  │  │ MCP Broker   │  │              │
│           │  │   (Envoy)    │  │  │  │ Controller   │  │              │
│           │  └──────────────┘  │  │  └──────────────┘  │              │
│           └────────────────────┘  └────────────────────┘              │
│                                                                       │
│    ┌────────────────┐  ┌────────────────┐  ┌────────────────────┐     │
│    │     SPIRE      │  │       IAM      │  │  Istio Ambient     │     │
│    │  (Identity)    │  │(e.g. Keycloak) |  │  (Service Mesh)    │     │
│    └────────────────┘  └────────────────┘  └────────────────────┘     │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

Agent Deployment Architecture

Kagenti deploys agents using standard Kubernetes workloads (Deployments + Services), providing a simple, portable, and operator-free deployment model.

Capabilities

Container Build System

Kagenti uses Shipwright for building container images from source:

Shipwright Build Flow:

1. UI creates a Shipwright Build CR with source configuration
2. UI creates a BuildRun CR to trigger the build
3. UI polls BuildRun status until completion
4. On success, UI creates the Deployment + Service for the agent

Agent Resources

Agents are deployed as standard Kubernetes resources:

# Deployment - Manages agent pods
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weather-service
  namespace: team1
  labels:
    kagenti.io/type: agent
    protocol.kagenti.io/a2a: ""
    kagenti.io/framework: LangGraph
    app.kubernetes.io/name: weather-service
    app.kubernetes.io/managed-by: kagenti-ui
spec:
  replicas: 1
  selector:
    matchLabels:
      kagenti.io/type: agent
      app.kubernetes.io/name: weather-service
  template:
    metadata:
      labels:
        kagenti.io/type: agent
        protocol.kagenti.io/a2a: ""
        app.kubernetes.io/name: weather-service
    spec:
      containers:
        - name: agent
          image: ghcr.io/kagenti/weather-service:latest
          env:
            - name: PORT
              value: "8000"
            - name: OPENAI_API_KEY
              valueFrom:
                secretKeyRef:
                  name: openai-secret
                  key: api-key
          ports:
            - containerPort: 8000
              name: http

# Service - Exposes the agent within the cluster
apiVersion: v1
kind: Service
metadata:
  name: weather-service
  namespace: team1
  labels:
    kagenti.io/type: agent
    app.kubernetes.io/name: weather-service
spec:
  type: ClusterIP
  selector:
    kagenti.io/type: agent
    app.kubernetes.io/name: weather-service
  ports:
    - name: http
      port: 8080
      targetPort: 8000

# Shipwright Build - For building from source
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: weather-service
  labels:
    kagenti.io/type: agent
    protocol.kagenti.io/a2a: ""
spec:
  source:
    type: Git
    git:
      url: https://github.com/kagenti/agent-examples
      revision: main
    contextDir: a2a/weather_service
  strategy:
    name: buildah-insecure-push  # or "buildah" for external registries
    kind: ClusterBuildStrategy
  output:
    image: registry.cr-system.svc.cluster.local:5000/weather-service:v0.0.1

Architecture

┌─────────────────────────────────────────────────────┐
│                    Kagenti UI                       │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Import    │  │   Build     │  │   Deploy    │  │
│  │   Agent     │  │   (Source)  │  │   Agent     │  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  │
│         │                │                │         │
│         ▼                ▼                ▼         │
│  ┌─────────────────────────────────────────────┐    │
│  │            Kubernetes API Server            │    │
│  │  (Deployment, Service, Build, HTTPRoute)    │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

Label Standards

All agent workloads use consistent labels for discovery:

MCP Gateway

Repository: Kuadrant/mcp-gateway

The MCP Gateway provides a unified entry point for Model Context Protocol (MCP) servers and tools. It acts as a “front door” for all MCP-based tool interactions.

Capabilities

Components

Registering Tools with the Gateway

Tools are registered using Kubernetes Gateway API resources:

# HTTPRoute - Define routing to MCP server
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: weather-tool-route
  labels:
    mcp-server: "true"
spec:
  parentRefs:
  - name: mcp-gateway
    namespace: gateway-system
  hostnames:
  - "weather-tool.mcp.local"
  rules:
  - backendRefs:
    - name: weather-tool
      port: 8000

# MCPServerRegistration - Register with the gateway
apiVersion: mcp.kagenti.com/v1alpha1
kind: MCPServerRegistration
metadata:
  name: weather-tool-servers
spec:
  toolPrefix: weather_
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: weather-tool-route

For detailed gateway configuration, see MCP Gateway Instructions.

MCP Tool Builds with Shipwright

Similar to agents, MCP tools can be built from source using Shipwright. The build process is:

1. UI creates a Shipwright Build CR with source configuration
2. UI creates a BuildRun CR to trigger the build
3. UI polls BuildRun status until completion
4. On success, UI creates a Deployment + Service for the MCP tool

# Shipwright Build for MCP Tool
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: weather-tool
  labels:
    kagenti.io/type: tool
    protocol.kagenti.io/streamable_http: ""
spec:
  source:
    type: Git
    git:
      url: https://github.com/kagenti/agent-examples
      revision: main
    contextDir: mcp/weather_tool
  strategy:
    name: buildah-insecure-push
    kind: ClusterBuildStrategy
  output:
    image: registry.cr-system.svc.cluster.local:5000/weather-tool:v0.0.1

# Deployment - Manages MCP tool pods
apiVersion: apps/v1
kind: Deployment
metadata:
  name: weather-tool
  namespace: team1
  labels:
    kagenti.io/type: tool
    protocol.kagenti.io/mcp: ""
    kagenti.io/transport: streamable_http
    app.kubernetes.io/name: weather-tool
spec:
  replicas: 1
  selector:
    matchLabels:
      kagenti.io/type: tool
      app.kubernetes.io/name: weather-tool
  template:
    metadata:
      labels:
        kagenti.io/type: tool
        protocol.kagenti.io/mcp: ""
        kagenti.io/transport: streamable_http
        app.kubernetes.io/name: weather-tool
    spec:
      containers:
        - name: mcp
          image: registry.cr-system.svc.cluster.local:5000/weather-tool:v0.0.1
          ports:
            - containerPort: 8000
              name: http

For detailed tool deployment instructions, see Importing a New Tool.

Plugins Adapter

Repository: kagenti/plugins-adapter

The Plugins Adapter enables dynamic plugin loading and execution within Envoy-based gateways, including the MCP gateway, via Envoy’s External Processing API (ext_proc). It allows runtime extension of gateway capabilities without recompiling or redeploying the gateway.

Capabilities

Kagenti UI

Location: kagenti/ui-v2/

A modern web dashboard built with React (PatternFly frontend and FastAPI backend for managing agents and tools.

Architecture

Features

Pages

Access

# Kind cluster
open http://kagenti-ui.localtest.me:8080

# OpenShift
kubectl get route kagenti-ui -n kagenti-system -o jsonpath='{.status.ingress[0].host}'

Identity & Auth Bridge

Repository: kagenti/kagenti-extensions/AuthBridge

Kagenti provides a unified framework for identity and authorization in agentic systems, replacing static credentials with dynamic, short-lived tokens. We call this collection of assets Auth Bridge.

Auth Bridge solves a critical challenge in microservices and agentic architectures: how can workloads authenticate and communicate securely without pre-provisioned static credentials?

Auth Bridge Components

Client Registration

Automatically registers Kubernetes workloads as Keycloak clients at pod startup:

• Uses SPIFFE ID as client identifier (e.g., spiffe://localtest.me/ns/team/sa/my-agent)
• Eliminates manual client creation and secret distribution
• Writes credentials to shared volume for application use

AuthProxy

An Envoy-based sidecar that handles both inbound JWT validation and outbound token exchange, using an external processor (ext-proc) for token operations:

                 Incoming request
                       │
                       ▼
┌────────────────────────────────────────────────────────────────────┐
│                          WORKLOAD POD                               │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                   AuthProxy Sidecar (Envoy + Ext Proc)      │   │
│  │                                                             │   │
│  │  INBOUND:  Validate JWT (signature, issuer, audience via    │   │
│  │            JWKS). Return 401 if invalid.                    │   │
│  │  OUTBOUND: Exchange token for target audience via Keycloak  │   │
│  │            (RFC 8693). HTTPS traffic passes through as-is.  │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                          │              │                           │
│                    ┌─────┘              └─────┐                     │
│                    ▼                          ▼                     │
│           ┌──────────────┐           ┌──────────────┐              │
│           │  Application │           │   Keycloak   │              │
│           └──────────────┘           └──────────────┘              │
└────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │   TARGET SERVICE    │
                         │  (aud: auth-target) │
                         └─────────────────────┘

Key Features:

• Inbound JWT Validation — Validates token signature, expiration, and issuer using JWKS keys fetched from Keycloak. Optionally validates the audience claim. Returns HTTP 401 for missing or invalid tokens.
• Outbound Token Exchange — Performs OAuth 2.0 Token Exchange (RFC 8693) to replace the caller’s token with one scoped to the target service audience
• Transparent to applications — Traffic interception via iptables; no application code changes required
• Configuration — Inbound validation is configured via ISSUER (required) and EXPECTED_AUDIENCE (optional) environment variables. Outbound exchange uses TOKEN_URL, CLIENT_ID, CLIENT_SECRET, and TARGET_AUDIENCE.

SPIRE (Workload Identity)

SPIRE provides cryptographic workload identities using the SPIFFE standard.

Identity Format: spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>

Keycloak (Access Management)

Keycloak manages user authentication and OAuth/OIDC flows.

Authorization Pattern

The Agent and Tool Authorization Pattern replaces static credentials with dynamic SPIRE-managed identities, enforcing least privilege and continuous authentication:

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│   User   │────▶│ Keycloak │────▶│  Agent   │────▶│   Tool   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
                      │                │                │
                      ▼                ▼                ▼
                 ┌─────────────────────────────────────────┐
                 │              SPIRE Server               │
                 │    (Issues short-lived identities)      │
                 └─────────────────────────────────────────┘

1. User authenticates with Keycloak, receives access token
2. Agent receives user context via delegated token
3. Agent identity is attested by SPIRE
4. Tool access uses exchanged tokens with minimal scope

Security Properties:

• No Static Secrets - Credentials are dynamically generated at pod startup
• Short-Lived Tokens - JWT tokens expire and must be refreshed
• Audience Scoping - Tokens are scoped to specific audiences, preventing reuse
• Transparent to Application - Token exchange is handled by the sidecar

For detailed overview of Identity and Authorization Patterns, see the Identity Guide.

Tornjak (SPIRE Management UI)

# API
curl http://spire-tornjak-api.localtest.me:8080/

# UI
open http://spire-tornjak-ui.localtest.me:8080/

Infrastructure Services

Ingress Gateway

The Ingress Gateway routes external HTTP requests to internal services using the Kubernetes Gateway API.

• Namespace: kagenti-system
• Implementation: Istio Gateway

Istio Ambient Mesh

Istio Ambient provides service mesh capabilities without sidecar proxies.

Benefits:

• Zero-config mTLS between services
• No sidecar resource overhead
• Transparent to applications

Kiali (Service Mesh Observability)

Kiali provides visualization of the service mesh topology and traffic flows.

Phoenix (Tracing) – Optional

LLM observability and tracing for agent interactions. Phoenix is disabled by default and can be enabled via components.phoenix.enabled: true in both the kagenti-deps and kagenti charts. Requires components.otel.enabled: true.

Supported Agent Frameworks

Kagenti is framework-neutral and supports agents built with any framework that can be exposed via the A2A protocol:

Example Agents

Communication Protocols

A2A (Agent-to-Agent)

A2A is Google’s standard protocol for agent communication.

Features:

• Agent discovery via Agent Cards
• Standardized task execution API
• Streaming support for long-running tasks

Endpoints:

GET  /.well-known/agent-card.json    # Agent Card (discovery)
POST /                          # Send message/task
GET  /tasks/{id}                # Get task status

MCP (Model Context Protocol)

MCP is Anthropic’s protocol for tool integration.

Features:

• Tool discovery and invocation
• Resource access
• Prompt templates

Endpoints:

POST /mcp    # MCP JSON-RPC messages

Related Documentation

• Installation Guide
• Demo Documentation
• Technical Details
• Identity, Security, and Auth Bridge
• MCP Gateway Instructions
• New Agent Guide
• New Tool Guide