Deploy, manage, and orchestrate AI agents on Kubernetes
|
|
KAOS is a Kubernetes-native framework for deploying and orchestrating AI agents with tool access, multi-agent coordination, and seamless LLM integration.
| Feature | Description |
|---|---|
| Agentic Graphs | Deploy distributed agents networks as Kubernetes resources |
| MCP Primitives | Tool integration via the Model Context Protocol standard |
| Multi-Agent Support | Hierarchical agent systems with automatic delegation |
| OpenAI-Compatible | All agents expose /v1/chat/completions endpoints |
| KAOS CLI | Install and manage agents and environments with kaos CLI |
| Visual Dashboard | UI to monitor agents, test chat, debug memory and tools |
- Kubernetes cluster
- kubectl configured
- helm installed
# Install the CLI
pip install kaos-cli
# Install KAOS in your cluster
kaos install
# Open the UI
kaos ui
The UI opens at axsaucedo.github.io/kaos-ui. For CLI/UI documentation, see the CLI Guide.
# Add the Helm repository
helm repo add kaos https://axsaucedo.github.io/kaos/charts
helm repo update
# Install the operator
helm install kaos kaos/kaos-operator -n kaos-system --create-namespace# simple-agent.yaml
apiVersion: kaos.tools/v1alpha1
kind: ModelAPI
metadata:
name: ollama
spec:
mode: Hosted
hostedConfig:
model: "smollm2:135m"
---
apiVersion: kaos.tools/v1alpha1
kind: MCPServer
metadata:
name: echo-tools
spec:
type: python-runtime
config:
tools:
fromString: |
def echo(message: str) -> str:
"""Echo back the message."""
return f"Echo: {message}"
---
apiVersion: kaos.tools/v1alpha1
kind: Agent
metadata:
name: assistant
spec:
modelAPI: ollama
mcpServers:
- echo-tools
config:
description: "AI assistant with echo tools"
instructions: "You are a helpful assistant."
env:
- name: MODEL_NAME
value: "ollama/smollm2:135m"kubectl apply -f simple-agent.yaml
# Wait for pods to be ready
kubectl wait --for=condition=ready pod -l agent=assistant --timeout=120s
# Port-forward and test
kubectl port-forward svc/agent-assistant 8000:8000
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "assistant", "messages": [{"role": "user", "content": "Hello!"}]}'KAOS supports hierarchical multi-agent systems where a coordinator delegates tasks to specialist agents:
apiVersion: kaos.tools/v1alpha1
kind: Agent
metadata:
name: coordinator
spec:
modelAPI: ollama
config:
description: "Coordinator that delegates to specialists"
instructions: "Delegate research to researcher, calculations to analyst."
agentNetwork:
access:
- researcher
- analystSee operator/config/samples/ for complete multi-agent examples.
flowchart TB
subgraph operator["KAOS Operator"]
ac["Agent Controller"]
mc["MCPServer Controller"]
mac["ModelAPI Controller"]
end
subgraph resources["Managed Resources"]
agent["Agent Pod<br/>Agent Runtime"]
mcp["MCP Server Pod<br/>MCP Tools"]
model["ModelAPI Pod<br/>Ollama/LiteLLM"]
end
ac --> agent
mc --> mcp
mac --> model
agent --> mcp
agent --> model
| Resource | Link |
|---|---|
| Full Documentation | axsaucedo.github.io/kaos |
| Quick Start | Getting Started |
| CLI Guide | CLI Commands |
| Web UI | UI Features |
| Agent CRD | Agent Reference |
| Multi-Agent | Multi-Agent Tutorial |
# Python tests
cd python && uv sync && uv run pytest tests/ -v
# Go tests
cd operator && make test
# E2E tests (requires kind)
cd operator && make kind-create
cd operator && make kind-e2e-run-testsSee operator/config/samples/ for examples:
- Simple Agent - Single agent with echo MCP tool
- Multi-Agent - Coordinator with worker agents
- Hierarchical - Multi-level agent hierarchy
- Custom Tools - Dynamic tool creation with
tools.fromString
Apache 2.0