https://github.com/axsaucedo/kaos
🚀 K8s Agent Orchestration System: Managing the KAOS in your large-scale distributed multi-agent systems
https://github.com/axsaucedo/kaos
Last synced: 2 months ago
JSON representation
🚀 K8s Agent Orchestration System: Managing the KAOS in your large-scale distributed multi-agent systems
- Host: GitHub
- URL: https://github.com/axsaucedo/kaos
- Owner: axsaucedo
- License: apache-2.0
- Created: 2025-12-28T11:49:15.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-05-24T07:17:53.000Z (2 months ago)
- Last Synced: 2026-05-24T08:25:18.499Z (2 months ago)
- Language: TypeScript
- Homepage: https://axsaucedo.github.io/kaos
- Size: 51.6 MB
- Stars: 253
- Watchers: 1
- Forks: 16
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - axsaucedo/kaos - 🚀 K8s Agent Orchestration System: Managing the KAOS in your large-scale distributed multi-agent systems (TypeScript)
- awesome-production-agentic-systems - KAOS - KAOS is a Kubernetes-native framework for deploying and orchestrating AI agents with tool access, multi-agent coordination, and seamless LLM integration. (Agentic Frameworks)
README
# KAOS: K8s Agent Orchestration System
Deploy, manage, and orchestrate AI agents on Kubernetes
Docs Nav
Features
Quick Start
Architecture
Documentation
---
KAOS is a Kubernetes-native framework for deploying and orchestrating AI agents with tool access, multi-agent coordination, and seamless LLM integration.
## Features
| 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 |
## Quick Start
### Prerequisites
- Kubernetes cluster
- kubectl configured
- helm installed
### Option 1: KAOS CLI/UI
For CLI/UI documentation, see the [CLI Guide](https://axsaucedo.github.io/kaos/cli/overview).
```bash
# Install the CLI
pip install kaos-cli
# Install KAOS in your cluster
kaos system install
# Create a few resources
kaos modelapi deploy my-api --mode Hosted --model "smollm2:135m"
kaos agent deploy my-agent --modelapi my-api --model "smollm2:135m"
# Send a request
kaos agent invoke my-agent --message "Hello"
# 📤 Response:
# Hello! How can I assist you today? If you have any questions, feel free to share them!
# Open the UI
kaos ui
```
This command opens [axsaucedo.github.io/kaos-ui](https://axsaucedo.github.io/kaos-ui) and runs a `kubectl proxy`.
You can also open the UI with telemetry enabled:
```
kaos ui --monitoring-enabled
```
Make sure you [enable observability](https://axsaucedo.github.io/kaos/v0.1.4/operator/telemetry.html#using-with-signoz).
### Option 2: Helm/kubectl
```bash
# 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
```
#### Deploy Your First Agent
```yaml
# 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"
```
```bash
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!"}]}'
```
#### Multi-Agent Systems
KAOS supports hierarchical multi-agent systems where a coordinator delegates tasks to specialist agents:
```yaml
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
- analyst
```
See [`operator/config/samples/`](operator/config/samples/) for complete multi-agent examples.
## Architecture
```mermaid
flowchart TB
subgraph operator["KAOS Operator"]
ac["Agent Controller"]
mc["MCPServer Controller"]
mac["ModelAPI Controller"]
end
subgraph resources["Managed Resources"]
agent["Agent Pod
Agent Runtime"]
mcp["MCP Server Pod
MCP Tools"]
model["ModelAPI Pod
Ollama/LiteLLM"]
end
ac --> agent
mc --> mcp
mac --> model
agent --> mcp
agent --> model
```
## Agent Runtime: Pydantic AI Server (PAIS)
KAOS agents are powered by [**PAIS**](https://github.com/axsaucedo/pydantic-ai-server) — an enterprise server wrapper for [Pydantic AI](https://ai.pydantic.dev). PAIS adds OpenAI-compatible HTTP API, distributed memory, multi-agent delegation, A2A discovery, health probes, and OpenTelemetry instrumentation on top of Pydantic AI agents.
## Documentation
| Resource | Link |
|----------|------|
| Full Documentation | [axsaucedo.github.io/kaos](https://axsaucedo.github.io/kaos) |
| Quick Start | [Getting Started](https://axsaucedo.github.io/kaos/getting-started/quickstart) |
| CLI Guide | [CLI Commands](https://axsaucedo.github.io/kaos/cli/commands) |
| Web UI | [UI Features](https://axsaucedo.github.io/kaos/ui/features) |
| Agent CRD | [Agent Reference](https://axsaucedo.github.io/kaos/operator/agent-crd) |
| Multi-Agent | [Multi-Agent Tutorial](https://axsaucedo.github.io/kaos/tutorials/multi-agent) |
## Development
```bash
# 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-tests
```
## Sample Configurations
See [`operator/config/samples/`](operator/config/samples/) for examples:
1. **Simple Agent** - Single agent with echo MCP tool
2. **Multi-Agent** - Coordinator with worker agents
3. **Hierarchical** - Multi-level agent hierarchy
4. **Custom Tools** - Dynamic tool creation with `tools.fromString`
## License
Apache 2.0