AgentKube
Kubernetes Multi-Agent AI Execution Platform with GitOps & Telemetry
1. THE PROBLEM
Running long-running multi-agent AI tasks synchronously freezes client interfaces and creates resource contention. Distributed AI workloads require robust task queuing, automated infrastructure provisioning, and continuous cluster health telemetry.
SYSTEM ARCHITECTURE & PIPELINE FLOW
FastAPI Ingestion & Redis Celery Queue
FastAPI endpoint accepts job requests with HTTP 202 Accepted (<15ms latency) and pushes tasks to Redis backed Celery workers.
Terraform AWS EKS & Kubernetes Workloads
Terraform provisions VPCs, EKS node groups, and IAM roles; Kubernetes manages dynamic HPA scaling (3 -> 8 worker replicas).
GitHub Actions & Argo CD Reconciliation
Build pipeline runs Pytest, Helm linting, and Trivy scans before pushing to ECR; Argo CD continuously reconciles cluster Helm state.
Prometheus Metrics & Grafana Dashboards
Exposes GET /metrics endpoint with correlation IDs (execution_id), PromQL alerts, and 4 Grafana operational dashboards.
2. TECHNICAL APPROACH & DECISIONS
1Asynchronous Task Engine with Celery & Redis
Decoupled task submission from agent execution using an async FastAPI API layer and Redis-backed Celery worker pools.
Synchronous long-polling HTTP requests
Synchronous requests risk gateway timeouts during complex multi-agent execution steps. Async enqueueing delivers instant HTTP 202 responses (<15ms) while workers execute in the background.
2GitOps Automation & K8s Production Hardening
Configured Argo CD for declarative Helm chart reconciliation and applied non-root security contexts with NetworkPolicies isolating Redis.
Manual kubectl apply script deployments
GitOps guarantees cluster state matches Git repository definitions with automated rollbacks and immutable tags.
CORE ARCHITECTURAL LOGIC
Asynchronous task enqueue handler returning immediate HTTP 202 status while offloading execution to Celery workers on Kubernetes.
| 1 | @app.post("/api/v1/agent/run", status_code=status.HTTP_202_ACCEPTED, response_model=TaskRunResponse) |
| 2 | async def submit_agent_task( |
| 3 | request: TaskRunRequest, |
| 4 | redis_client: Redis = Depends(get_redis_storage) |
| 5 | ): |
| 6 | execution_id = f"exec_{uuid.uuid4().hex[:12]}" |
| 7 | |
| 8 | # Store initial execution state with correlation ID |
| 9 | await redis_client.hset( |
| 10 | f"execution:{execution_id}", |
| 11 | mapping={ |
| 12 | "execution_id": execution_id, |
| 13 | "status": "queued", |
| 14 | "task": request.task, |
| 15 | "created_at": datetime.utcnow().isoformat() |
| 16 | } |
| 17 | ) |
| 18 | |
| 19 | # Offload asynchronous job to Celery K8s worker pool (<15ms response) |
| 20 | celery_app.send_task( |
| 21 | "worker.execute_agent_workflow", |
| 22 | args=[execution_id, request.task, request.context], |
| 23 | queue="agent_tasks" |
| 24 | ) |
| 25 | |
| 26 | return TaskRunResponse(execution_id=execution_id, status="queued") |
3. TRADE-OFFS & HONEST REFLECTION
Enforcing read-only root filesystems and isolated NetworkPolicies required explicit ephemeral volume mounts for Celery temporary files, but secured pods against unauthorized code injection.
4. CONCRETE OUTCOME & METRICS
Shipped an enterprise Kubernetes AI execution platform achieving 100% unit/integration test pass rate (35/35), sub-15ms task enqueue response times, and sub-30s HPA worker auto-scaling.