Core Concepts

Overview

KAOS provides a declarative way to deploy AI agents that can:

• Process natural language messages using LLMs
• Call external tools via the Model Context Protocol (MCP)
• Delegate tasks to other agents (Agent-to-Agent / A2A)
• Maintain conversation memory and context

Architecture

Custom Resource Definitions (CRDs)

Agent

The Agent CRD defines an AI agent deployment. Each Agent:

• References a ModelAPI for LLM access
• Can reference multiple MCPServers for tool access
• Exposes HTTP endpoints for interaction
• Can delegate to other Agents via A2A protocol

apiVersion: kaos.tools/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  modelAPI: my-model      # Required: LLM backend
  mcpServers: [tools]     # Optional: Tool servers
  agentNetwork:           # Optional: A2A networking
    expose: true
    access: [worker-1]
  config:                 # Optional: Agent configuration
    instructions: "..."

ModelAPI

The ModelAPI CRD deploys LLM access. Two modes:

Proxy Mode: LiteLLM proxy to external backends

spec:
  mode: Proxy
  proxyConfig:
    apiBase: "http://ollama:11434"

Hosted Mode: Ollama running in-cluster

spec:
  mode: Hosted
  serverConfig:
    model: "smollm2:135m"

MCPServer

The MCPServer CRD deploys tool servers using the Model Context Protocol:

spec:
  runtime: python-string
  params: |
    def my_tool(x: str) -> str:
        """My custom tool."""
        return x.upper()

Agentic Loop

The agent implements a reasoning loop that enables tool use and delegation:

1. Receive user message
2. Build system prompt (instructions + available tools + available agents)
3. Send to LLM
4. Parse response:
   - If contains tool_call → execute tool → add result → go to step 3
   - If contains delegate → invoke sub-agent → add response → go to step 3
   - Otherwise → return final response
5. Store events in memory

Maximum iterations are controlled by config.reasoningLoopMaxSteps (default: 5).

Agent-to-Agent (A2A) Protocol

Agents can discover and invoke each other using the A2A protocol:

1. Discovery: Agents expose /.well-known/agent.json endpoint with capabilities
2. Invocation: Agents use A2A JSON-RPC SendMessage on peer agents, falling back to /v1/chat/completions
3. Delegation: Via DelegationToolset — sub-agents exposed as delegate_to_{name} tools

The operator automatically configures peer agent URLs based on agentNetwork.access.

Memory and Sessions

Agents keep conversation context and can build durable, cross-session memory:

• Local memory (default, no MemoryStore): a pod-local short-term window of recent turns for conversational continuity within a session.
• Remote memory (bound to a MemoryStore): a central memory service adds two more tiers on top of the short-term window — a medium-term rolling digest per session, and a long-term semantic store that extracts facts and recalls them by relevance across sessions.

A MemoryStore is a first-class resource the operator deploys (see the MemoryStore CRD). An agent binds to one via config.memory and selects a scope (private, user, shared, session) that governs whose long-term memory it reads and writes. Memory is augmentation, not a hard dependency: if the store is unavailable, the agent keeps serving in short-term-only mode.

See Memory Architecture for the full design.

Environment Variable Configuration

The operator configures agent pods via environment variables:

Variable	Source
AGENT_NAME	Agent metadata.name
MODEL_API_URL	ModelAPI status.endpoint
AGENT_SUB_AGENTS	agentNetwork.access list
REASONING_LOOP_MAX_STEPS	config.reasoningLoopMaxSteps

See Environment Variables for complete list.