{"id":40537611,"url":"https://github.com/axsaucedo/kaos","last_synced_at":"2026-05-24T09:01:31.115Z","repository":{"id":330847203,"uuid":"1124126693","full_name":"axsaucedo/kaos","owner":"axsaucedo","description":"🚀 K8s Agent Orchestration System: Managing the KAOS in your large-scale distributed multi-agent systems","archived":false,"fork":false,"pushed_at":"2026-05-24T07:17:53.000Z","size":54142,"stargazers_count":253,"open_issues_count":9,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T08:25:18.499Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://axsaucedo.github.io/kaos","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axsaucedo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-28T11:49:15.000Z","updated_at":"2026-05-24T07:17:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/axsaucedo/kaos","commit_stats":null,"previous_names":["axsaucedo/agentic-kubernetes-operator","axsaucedo/kaos"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/axsaucedo/kaos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axsaucedo%2Fkaos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axsaucedo%2Fkaos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axsaucedo%2Fkaos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axsaucedo%2Fkaos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axsaucedo","download_url":"https://codeload.github.com/axsaucedo/kaos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axsaucedo%2Fkaos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33427584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T22:47:15.029Z","updated_at":"2026-05-24T09:01:31.005Z","avatar_url":"https://github.com/axsaucedo.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Python","Agentic Frameworks"],"sub_categories":[],"readme":"# KAOS: K8s Agent Orchestration System\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDeploy, manage, and orchestrate AI agents on Kubernetes\u003c/strong\u003e\n\u003c/p\u003e\n\n\n\u003ctable width=\"100%\"\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003cimg src=\"docs/public/kaos-banner.png\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e\n\u003cbr\u003e\n    \u003cp align=\"center\"\u003e\n      \u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003ca href=\"https://kubernetes.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/kubernetes-%3E%3D1.28-blue\" alt=\"Kubernetes\"\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003ca href=\"https://go.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/go-%3E%3D1.21-blue\" alt=\"Go\"\u003e\u003c/a\u003e\u003cbr\u003e\n      \u003ca href=\"https://python.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-%3E%3D3.11-blue\" alt=\"Python\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003c/p\u003e\n    \u003ch3 align=\"center\"\u003eDocs Nav\u003c/h3\u003e\n    \u003cp align=\"center\"\u003e\n      \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e \u003cbr\u003e\n      \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u003cbr\u003e\n      \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e \u003cbr\u003e\n      \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e \u003cbr\u003e\n    \u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\nKAOS is a Kubernetes-native framework for deploying and orchestrating AI agents with tool access, multi-agent coordination, and seamless LLM integration.\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Agentic Graphs** | Deploy distributed agents networks as Kubernetes resources |\n| **MCP Primitives** | Tool integration via the Model Context Protocol standard |\n| **Multi-Agent Support** | Hierarchical agent systems with automatic delegation |\n| **OpenAI-Compatible** | All agents expose `/v1/chat/completions` endpoints |\n| **KAOS CLI** | Install and manage agents and environments with `kaos` CLI |\n| **Visual Dashboard** | UI to monitor agents, test chat, debug memory and tools |\n\n## Quick Start\n\n### Prerequisites\n\n- Kubernetes cluster\n- kubectl configured\n- helm installed\n\n### Option 1: KAOS CLI/UI\n\nFor CLI/UI documentation, see the [CLI Guide](https://axsaucedo.github.io/kaos/cli/overview).\n\n```bash\n# Install the CLI\npip install kaos-cli\n\n# Install KAOS in your cluster\nkaos system install\n\n# Create a few resources\nkaos modelapi deploy my-api --mode Hosted --model \"smollm2:135m\"\nkaos agent deploy my-agent --modelapi my-api --model \"smollm2:135m\"\n\n# Send a request\nkaos agent invoke my-agent --message \"Hello\"\n# 📤 Response:\n# Hello! How can I assist you today? If you have any questions, feel free to share them! \n\n# Open the UI\nkaos ui\n```\n\nThis command opens [axsaucedo.github.io/kaos-ui](https://axsaucedo.github.io/kaos-ui) and runs a `kubectl proxy`. \n\n\u003cimg src=\"docs/public/demo.gif\"\u003e\n\nYou can also open the UI with telemetry enabled:\n\n```\nkaos ui --monitoring-enabled\n```\n\nMake sure you [enable observability](https://axsaucedo.github.io/kaos/v0.1.4/operator/telemetry.html#using-with-signoz).\n\n\n\u003cimg src=\"docs/public/demo-monitoring.gif\"\u003e\n\n### Option 2: Helm/kubectl\n\n```bash\n# Add the Helm repository\nhelm repo add kaos https://axsaucedo.github.io/kaos/charts\nhelm repo update\n\n# Install the operator\nhelm install kaos kaos/kaos-operator -n kaos-system --create-namespace\n```\n\n#### Deploy Your First Agent\n\n```yaml\n# simple-agent.yaml\napiVersion: kaos.tools/v1alpha1\nkind: ModelAPI\nmetadata:\n  name: ollama\nspec:\n  mode: Hosted\n  hostedConfig:\n    model: \"smollm2:135m\"\n\n---\napiVersion: kaos.tools/v1alpha1\nkind: MCPServer\nmetadata:\n  name: echo-tools\nspec:\n  type: python-runtime\n  config:\n    tools:\n      fromString: |\n        def echo(message: str) -\u003e str:\n            \"\"\"Echo back the message.\"\"\"\n            return f\"Echo: {message}\"\n\n---\napiVersion: kaos.tools/v1alpha1\nkind: Agent\nmetadata:\n  name: assistant\nspec:\n  modelAPI: ollama\n  mcpServers:\n    - echo-tools\n  config:\n    description: \"AI assistant with echo tools\"\n    instructions: \"You are a helpful assistant.\"\n    env:\n      - name: MODEL_NAME\n        value: \"ollama/smollm2:135m\"\n```\n\n```bash\nkubectl apply -f simple-agent.yaml\n\n# Wait for pods to be ready\nkubectl wait --for=condition=ready pod -l agent=assistant --timeout=120s\n\n# Port-forward and test\nkubectl port-forward svc/agent-assistant 8000:8000\ncurl http://localhost:8000/v1/chat/completions \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"model\": \"assistant\", \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]}'\n```\n\n#### Multi-Agent Systems\n\nKAOS supports hierarchical multi-agent systems where a coordinator delegates tasks to specialist agents:\n\n```yaml\napiVersion: kaos.tools/v1alpha1\nkind: Agent\nmetadata:\n  name: coordinator\nspec:\n  modelAPI: ollama\n  config:\n    description: \"Coordinator that delegates to specialists\"\n    instructions: \"Delegate research to researcher, calculations to analyst.\"\n  agentNetwork:\n    access:\n      - researcher\n      - analyst\n```\n\nSee [`operator/config/samples/`](operator/config/samples/) for complete multi-agent examples.\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph operator[\"KAOS Operator\"]\n        ac[\"Agent Controller\"]\n        mc[\"MCPServer Controller\"]\n        mac[\"ModelAPI Controller\"]\n    end\n    \n    subgraph resources[\"Managed Resources\"]\n        agent[\"Agent Pod\u003cbr/\u003eAgent Runtime\"]\n        mcp[\"MCP Server Pod\u003cbr/\u003eMCP Tools\"]\n        model[\"ModelAPI Pod\u003cbr/\u003eOllama/LiteLLM\"]\n    end\n    \n    ac --\u003e agent\n    mc --\u003e mcp\n    mac --\u003e model\n    agent --\u003e mcp\n    agent --\u003e model\n```\n\n## Agent Runtime: Pydantic AI Server (PAIS)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/public/pais-horizontal.jpg\" alt=\"PAIS — Pydantic AI Server\" height=\"300\"\u003e\n\u003c/p\u003e\n\nKAOS 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.\n\n## Documentation\n\n| Resource | Link |\n|----------|------|\n|  Full Documentation | [axsaucedo.github.io/kaos](https://axsaucedo.github.io/kaos) |\n|  Quick Start | [Getting Started](https://axsaucedo.github.io/kaos/getting-started/quickstart) |\n|  CLI Guide | [CLI Commands](https://axsaucedo.github.io/kaos/cli/commands) |\n|  Web UI | [UI Features](https://axsaucedo.github.io/kaos/ui/features) |\n|  Agent CRD | [Agent Reference](https://axsaucedo.github.io/kaos/operator/agent-crd) |\n|  Multi-Agent | [Multi-Agent Tutorial](https://axsaucedo.github.io/kaos/tutorials/multi-agent) |\n\n## Development\n\n```bash\n# Python tests\ncd python \u0026\u0026 uv sync \u0026\u0026 uv run pytest tests/ -v\n\n# Go tests  \ncd operator \u0026\u0026 make test\n\n# E2E tests (requires kind)\ncd operator \u0026\u0026 make kind-create\ncd operator \u0026\u0026 make kind-e2e-run-tests\n```\n\n## Sample Configurations\n\nSee [`operator/config/samples/`](operator/config/samples/) for examples:\n\n1. **Simple Agent** - Single agent with echo MCP tool\n2. **Multi-Agent** - Coordinator with worker agents\n3. **Hierarchical** - Multi-level agent hierarchy\n4. **Custom Tools** - Dynamic tool creation with `tools.fromString`\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxsaucedo%2Fkaos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxsaucedo%2Fkaos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxsaucedo%2Fkaos/lists"}