Cách triển khai AI Agent lên Kubernetes trong 30 phút bằng kagent

Hãy thử hình dung bạn muốn đưa một AI Agent vào production. Mọi thứ thường bắt đầu từ một file Python: import LangChain, xây dựng reasoning loop, kết nối các tool rồi xử lý từng lỗi có thể phát sinh. Khi phần code đã chạy ổn, công việc triển khai mới thực sự bắt đầu, đóng gói thành Docker image, viết Deployment/Service/ConfigMap và thiết lập observability.

Với các team đã quen vận hành hạ tầng bằng kubectl apply, đây là một quy trình khá khác biệt so với cách họ quản lý infrastructure hàng ngày.

kagent đặt ra một hướng tiếp cận khác: nếu một AI Agent chỉ là một Kubernetes Custom Resource, tương tự Deployment hay Service, thì sao? Thay vì tự viết Dockerfile và reasoning loop bằng Python, bạn chỉ cần một file YAML khai báo system prompt, tools và model, sau đó triển khai bằng:

kubectl apply -f agent.yaml

Kagent là gì và vấn đề mà kagent có thể giải quyết

kagent là một framework mã nguồn mở, Kubernetes-native, cho phép bạn định nghĩa, triển khai và vận hành AI agent như một Kubernetes resource thuần túy. Thay vì viết code Python phức tạp để build agent, bạn khai báo agent bằng YAML, giống hệt cách bạn deploy một Deployment hay Service.

Mỗi agent trong kagent là một Kubernetes Custom Resource (CRD), có thể:

• kubectl apply để tạo hoặc cập nhật agent
• kubectl get để xem danh sách và trạng thái
• kubectl delete để xóa agent
• Quản lý qua GitOps — commit YAML lên Git, agent tự động sync

Trước khi có kagent, việc triển khai một AI Agent lên production trên Kubernetes thường trải qua năm bước: viết code với LangChain hoặc framework tương đương, build và push Docker image, viết Kubernetes manifest, tự triển khai observability/retry/error handling, rồi quản lý config và API key cho từng LLM provider.

Mỗi AI Agent mới vì thế có thể kéo theo một vòng lặp CI/CD riêng.

kagent rút gọn bộ quy trình đó lại thành hai bước: viết một file YAML định nghĩa agent, và kubectl apply -f agent.yaml. Agent trở thành một CRD (Custom Resource Definition) thực thụ — có thể kubectl get, kubectl describe, kubectl delete, và quản lý qua GitOps như bất kỳ resource K8s nào khác.

Triết lý cốt lõi: Agent-as-Code. Agent được định nghĩa bằng YAML declarative, versioned, review qua pull request, deploy bằng đúng workflow K8s mà team vận hành đã quen dùng, thay vì một nhánh quy trình riêng cho AI.

kagent được Solo.io - công ty đứng sau Istio và kgateway - mở mã nguồn ngày 17/3/2025, và chỉ trong một tuần đã đạt hơn 300 GitHub star. Tháng 4/2025, project được đóng góp cho CNCF Sandbox tại KubeCon Europe. Đến tháng 8/2025, kagent đã có hơn 100 contributor, với hơn 85% đến từ bên ngoài Solo.io - một tín hiệu cho thấy đây không còn là dự án nội bộ của một công ty.

Về mặt kỹ thuật, kagent được xây trên Google ADK (Agent Development Kit) và hỗ trợ tích hợp thêm LangGraph, CrewAI, OpenAI Agents SDK. Nó không cố thay thế các framework này — nó tập trung làm tốt một việc: đưa agent vào vòng đời Kubernetes một cách tự nhiên nhất.

Kiến trúc tổng thể của kagent: 4 thành phần, một luồng chạy

kagent gồm bốn thành phần cốt lõi, mỗi thành phần đảm nhiệm một vai trò riêng:

Khi bạn tạo một Agent resource, chuỗi sự kiện diễn ra khá quen thuộc với ai từng debug một Deployment: Controller nhận event từ API Server, tạo Pod chạy Engine theo config trong Agent spec, Engine khởi động và load system prompt, kết nối tới MCP server, rồi đăng ký với control plane để sẵn sàng nhận request. Từ đó, mỗi lượt chat là một vòng: user gọi qua UI hoặc API → Engine gọi LLM → LLM quyết định có cần gọi tool hay không → Engine thực thi tool → trả kết quả về.

Go ADK hay Python ADK?

Từ phiên bản v0.9, kagent cho phép lựa chọn giữa hai runtime cho Engine. Lựa chọn này ảnh hưởng trực tiếp đến thời gian cold start khi autoscale:

Chuyển sang Go runtime chỉ là một dòng trong spec:

spec:
  type: Declarative
  declarative:
    runtime: go # hoặc "python" (mặc định)

Với agent chạy thường trực, khác biệt 15s vs 2s không đáng kể. Nhưng với agent scale-to-zero theo traffic, đây là khác biệt giữa một request chờ 15 giây và một request gần như tức thời.

Những khái niệm cần nắm trước khi xây dựng agent đầu tiên

Một Agent trong kagent gồm ba phần: Agent Instructions (system prompt định nghĩa vai trò và hành vi), Tools (các function agent có thể gọi), và Skills (mô tả năng lực giúp agent hành động tự chủ hơn). Ví dụ tối thiểu:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: k8s-troubleshoot-agent
  namespace: kagent
spec:
  description: "Agent điều tra incident K8s tự động"
  type: Declarative
  declarative:
    modelConfig: default-model-config
    systemMessage: |
      Bạn là SRE agent chuyên điều tra incident trên Kubernetes.
      Khi nhận alert, hãy: get pods, get events, check logs
      và đề xuất fix steps cụ thể.
    tools:
      - type: McpServer
        mcpServer:
          name: kagent-tool-server
          kind: RemoteMCPServer
          toolNames:
            - k8s_get_resources
            - k8s_get_pod_logs
            - k8s_describe_resource

ModelConfig là nơi agent trỏ đến LLM provider. Đây cũng là điểm kagent linh hoạt nhất: một CRD riêng cho model, tách khỏi logic agent, nên đổi provider không đụng gì đến system prompt hay tool list. kagent hỗ trợ OpenAI, Anthropic, Google Gemini (qua API hoặc Vertex AI), Azure OpenAI, Ollama tự host, và bất kỳ endpoint nào tương thích chuẩn OpenAI — bao gồm GreenNode MAAS:

apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: greennode-maas
  namespace: kagent
spec:
  provider: OpenAI
  model: qwen/qwen3-5-27b
  apiKeySecret: maas-api-secret
  openAI:
    baseUrl: https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1

Tools và MCP. kagent dùng Model Context Protocol (MCP) làm chuẩn kết nối tool — một MCP server expose nhiều tool, agent khai báo dùng tool nào từ đó. Có ba nguồn tool: RemoteMCPServer (MCP server built-in — kagent-tool-server đi kèm sẵn 124 tools, chia theo nhóm Kubernetes (~40), Helm (~10), Prometheus (~8), Grafana (~6), Cilium (30+), Argo Rollouts (~8), Istio (~10), Gateway API (~6)); MCPServer tự deploy cho tool riêng của team; và Agent as Tool — dùng một agent khác làm tool, mở đường cho kiến trúc multi-agent.

Human-in-the-Loop. Với các hành động nhạy cảm (xoá resource, apply manifest), kagent hỗ trợ pause chờ approve trước khi thực thi:

requireApproval:
  - k8s_delete_resource
  - k8s_apply_manifest

Khi bạn reject một tool call, lý do từ chối được gửi ngược lại cho LLM làm context - agent điều chỉnh hướng tiếp cận thay vì fail hoàn toàn. Ngoài ra mọi agent đều có sẵn tool ask_user để tự pause hỏi người dùng khi cần làm rõ yêu cầu, không cần config thêm.

Memory và Context Compaction. Từ v0.9, agent có thể bật vector memory để nhớ context xuyên suốt các conversation (tự động nhận thêm ba tool: save_memory, load_memory, prefetch_memory, extract sau mỗi 5 tin nhắn). Khi hội thoại dài vượt context window, cơ chế compaction tự tóm tắt các message cũ:

spec:
  declarative:
    context:
      compaction:
        compactionInterval: 5 # compact sau mỗi 5 user message
        overlapSize: 2 # giữ 2 message overlap
        tokenThreshold: 10000 # hoặc khi vượt 10k tokens

Agent-to-Agent (A2A). Agent có thể gọi agent khác như tool, cho phép xây multi-agent workflow — ví dụ SRE agent gọi promql-agent để tạo PromQL query, sau đó gọi k8s-agent để correlate với K8s events. Mọi agent tự động được expose như MCP server tại endpoint /mcp, nghĩa là Cursor hay Claude Desktop cũng có thể gọi thẳng agent của bạn như sub-agent.

Hướng dẫn cài đặt kagent trên GreenNode VKS

Cài kagent theo docs chính thức chạy trơn tru trên nhiều cluster, nhưng trên GreenNode VKS có vài điểm đặc thù đáng biết trước để không mất thời gian debug.

Yêu cầu: Kubernetes v1.28+ (đã test trên GreenNode VKS v1.30.10), Helm v3.8+, kubectl đã trỏ tới cluster, và API key của LLM provider (GreenNode MAAS, OpenAI, Anthropic...).

Bước 1: Cài CRDs. kagent publish qua OCI registry (ghcr.io), không phải Helm repo HTTP thông thường — helm repo add sẽ trả về lỗi 404. Cài CRDs riêng trước để tránh mất data khi uninstall:

helm install kagent-crds \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --namespace kagent \
  --create-namespace

Bước 2: Tạo secret cho GreenNode MaaS

kubectl create secret generic kagent-maas-secret \
  --namespace kagent \
  --from-literal=OPENAI_API_KEY=<your-maas-api-key>

Bước 3: Cài kagent

helm install kagent \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --namespace kagent \
  --set providers.default=openAI \
  --set providers.openAI.apiKeySecretRef=kagent-maas-secret \
  --set providers.openAI.baseURL=https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1 \
  --set providers.openAI.model=qwen/qwen3-5-27b

Lưu ý: --set providers.openAI.baseURL không tự động map vào ModelConfig — cần patch thủ công ở bước 5.

Bước 4: Fix PostgreSQL Pending mãi. Đây là điểm đặc thù của VKS: default StorageClass dùng WaitForFirstConsumer, khiến PostgreSQL pod bị stuck vì không có PVC nào được tạo tự động. Tạo PVC thủ công:

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: kagent-postgresql
  namespace: kagent
spec:
  accessModes: [ReadWriteOnce]
  storageClassName: vngcloud-nvme-5000-delete
  resources:
    requests:
      storage: 8Gi
EOF

kubectl -n kagent delete pod -l app.kubernetes.io/name=postgresql

Bước 5: Patch baseURL cho GreenNode MaaS. Field đúng là spec.openAI.baseUrl — chữ l thường, không phải baseURL. Đây là lỗi phổ biến nhất khi setup. Kiểm tra trước bằng kubectl explain:

kubectl explain modelconfig.spec.openAI

kubectl -n kagent patch modelconfig default-model-config \
  --type=merge \
  -p '{"spec":{"openAI":{"baseUrl":"https://maas-llm-aiplatform-hcm.api.vngcloud.vn/v1"}}}'

Bước 6: Expose UI qua Ingress (nếu cluster có nginx ingress controller):

cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: kagent-ui-ingress
  namespace: kagent
spec:
  ingressClassName: nginx
  rules:
    - host: kagent.<IP ingress>.nip.io
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: kagent-ui
                port:
                  number: 8080
EOF

Sau khoảng 30 phút (bao gồm thời gian troubleshoot), toàn bộ stack đã running: controller, engine, 10 agents, PostgreSQL, UI.

Cách để vận hành hàng ngày

Tạo agent mới chỉ là viết YAML rồi apply:

kubectl apply -f my-sre-agent.yaml
kubectl -n kagent get agents

Các lệnh dùng thường xuyên nhất:

# Xem tất cả agents
kubectl -n kagent get agents

# Xem chi tiết một agent
kubectl -n kagent describe agent k8s-agent

# Xem tất cả resource kagent
kubectl -n kagent get agents,modelconfigs,toolservers,memories

# Xem log của kagent-engine
kubectl -n kagent logs -l app.kubernetes.io/component=engine -f

# Port-forward UI nếu không có ingress
kubectl -n kagent port-forward service/kagent-ui 8080:8080

Dashboard tại http://kagent.<ingress-ip>.nip.io (hoặc localhost:8080 qua port-forward) gom bốn việc vào một chỗ: chat trực tiếp với bất kỳ agent nào bằng ngôn ngữ tự nhiên, approve/reject tool call nguy hiểm, xem lại lịch sử session, và theo dõi danh sách MCP server/tool đang khả dụng.

Với 10 agent mặc định đi kèm, một vài câu hỏi thực tế trông như thế này:

Các lỗi thường gặp trên GreenNode VKS

kagent so với tự build agent

Câu hỏi thực tế nhất khi cân nhắc kagent là: so với việc team tự viết một SRE agent bằng code, được và mất gì?

Nói ngắn gọn: kagent đánh đổi một phần flexibility để lấy tốc độ triển khai và một bộ vận hành (observability, HITL, UI) có sẵn theo đúng convention Kubernetes. Với team đã vận hành nhiều cluster và muốn agent đi theo cùng workflow GitOps như mọi resource khác, đây là đánh đổi hợp lý. Với agent cần logic rất đặc thù hoặc kiểm soát runtime tuyệt đối, viết tay vẫn là lựa chọn phù hợp hơn.

Khi nào không nên sử dụng kagent

kagent phát huy giá trị khi bạn cần vận hành nhiều agent như một phần hạ tầng Kubernetes, GitOps, RBAC, observability đồng bộ với phần còn lại của cluster. Nếu chỉ cần một microservice AI đơn lẻ expose qua REST endpoint, không cần vòng đời CRD hay chat UI, phần overhead của kagent (CRD, controller, engine pod) không mang lại lợi ích tương xứng; một service gọi thẳng LLM API sẽ đơn giản hơn. Tương tự, nếu hạ tầng của bạn chưa dùng Kubernetes, phần giá trị cốt lõi của kagent - Agent-as-Code trên K8s - không áp dụng được.

Kết luận

kagent đưa AI agent vào đúng vị trí mà team hạ tầng đã quen thao tác: một CRD, một kubectl apply, một pull request review trước khi merge. Trên VKS GreenNode, phần dựng hạ tầng chỉ mất khoảng 30 phút nếu biết trước ba điểm đặc thù - OCI registry thay vì Helm repo, PVC phải tạo thủ công do WaitForFirstConsumer, và field baseUrl viết thường. Sau đó, việc thêm một agent mới chỉ còn là viết YAML.

Nội dung được tổng hợp từ kagent official docs và trải nghiệm thực tế triển khai trên GreenNode VKS 14 node.