kagent: kagent kubernetes mcp agentes en tu clúster (Guía Homelab 2026)

TL;DR

kagent es un marco open source (Apache-2.0) para construir agentes de IA nativos en Kubernetes, con herramientas MCP empaquetadas como piezas declarativas del clúster. Puedes instalar con CLI (kagent install --profile demo) o Helm (charts OCI en ghcr.io/kagent-dev). Antes de dar permisos amplios al ServiceAccount, recuerda que MCP no sustituye políticas de seguridad: es contrato de llamadas, no magia de cumplimiento. Si solo necesitas RAG visual sin operar el plano de control, mira Flowise; aquí el foco es plataforma. Tiempo de lectura: unos veinticinco minutos.

Tabla de contenidos

• TL;DR
• Introducción
• Glosario rápido
• Qué problema resuelve kagent con MCP y agentes
• Arquitectura: kagent, ModelConfig y MCP
• Requisitos de clúster y herramientas
• Instalación con la CLI (perfil demo)
• Instalación con Helm ([OpenAI u Ollama)](#instalación-con-helm-openai-u-ollama)
• Seguridad: RBAC, secretos y blast radius
• Observabilidad: trazas y métricas
• Matriz de riesgo: MCP frente a kubectl improvisado
• Comparativas: kagent y agentes en Kubernetes
• Homelab: dimensionar kind, k3s y perfiles demo
• GitOps: kagent, valores Helm y MCP
• Istio, Helm y [Prometheus desde la mirada del agente](#istio-helm-y-prometheus-desde-la-mirada-del-agente)
• Roadmap de seguridad en cuatro fases
• Ollama en LAN: [DNS, TLS y políticas](#ollama-en-lan-dns-tls-y-políticas)
• Troubleshooting práctico
• 📦 Descargar ejemplos
• Enlaces relacionados
• Preguntas frecuentes
• Conclusión

Introducción

Si buscas kagent kubernetes mcp agentes en 2026, probablemente ya dominas K8s a nivel básico y has leído sobre el Model Context Protocol: un estándar para exponer herramientas a modelos de forma interoperable. El salto difícil es operacional: ¿dónde vive el agente?, ¿cómo versionas prompts y herramientas?, ¿cómo auditar qué hizo el modelo en tu plataforma? Ahí entra kagent, que coloca agentes y tool servers en el mismo lenguaje declarativo que ya usas para apps (Dapr Agents, OpenAI Agents SDK en otros contextos).

Este artículo no sustituye la documentación oficial (kagent.dev, kagent-dev/kagent): sirve como mapa de decisión y checklist de homelab enlazado a ejemplos reproducibles en GitHub. Si tras leer sigues con dudas sobre el scope de un agente, vuelve al README: allí se explicita el enfoque Cloud Native Agentic AI y la lista de integraciones que evoluciona release a release. Anota siempre la versión (v0.9.x beta en el momento de redactar) para no comparar manzanas con peras cuando leas issues antiguos.

Glosario rápido

• Agente: unidad lógica con prompt, herramientas y políticas.
• ToolServer: recurso que expone herramientas MCP reutilizables.
• ModelConfig: configuración del proveedor LLM.
• kmcp: componente hermano incluido por defecto desde versiones recientes; puede deshabilitarse si choca con tu despliegue previo.

Qué problema resuelve kagent con MCP y agentes

Sin un marco como kagent, es tentador montar un pod con Python, pegarle kubectl al contenedor y llamarlo “agente”. Funciona en la demo; falla en el incidente del viernes porque no hay separación clara entre identidad del agente, alcance de herramientas y trazabilidad. kagent empaqueta MCP en recursos reutilizables del clúster (p. ej. ToolServers para Helm, Prometheus, Istio, Argo, Grafana, Cilium según el README del proyecto), de modo que varios agentes compartan herramientas homogéneas en lugar de forks privados.

En otras palabras: kagent kubernetes mcp agentes es la promesa de alinear “cómo habla el modelo” con “cómo se gobierna el clúster”, sin renunciar a revisión humana ni a políticas de mínimo privilegio.

Arquitectura: kagent, ModelConfig y MCP

1. Agente: prompt de sistema + herramientas + políticas. Es la unidad que un desarrollador o plataforma quiere versionar.
2. ModelConfig: describe el proveedor LLM (OpenAI, Anthropic, Gemini, Azure OpenAI, Ollama, otros vía pasarelas). La guía de instalación muestra providers.default y claves por proveedor en valores Helm.
3. ToolServers MCP: exponen capacidades con contrato MCP; en kagent aparecen como CRDs reutilizables entre agentes.
4. kmcp: desde la versión 0.7 se incluye por defecto; si ya tienes kmcp aparte, desactívalo con kmcp.enabled=false en kagent y kagent-crds para evitar choques.

Visualiza el flujo como un control loop: el usuario declara estado deseado, el operador reconcilia y la UI (kagent-ui) da feedback. Si vienes de observabilidad con Prometheus y Grafana, el patrón “declarar + reconciliar + auditar” te resultará familiar aunque el dominio ahora sea LLM + herramientas. Esa familiaridad es la ventaja real frente a “un chat con acceso sudo”: reduces sorpresas porque el modelo opera dentro de límites que tú versionas en Git.

Requisitos de clúster y herramientas

• K8s estable (homelab con kind o k3s es válido; ajusta recursos si usas perfil demo).
• kubectl y Helm 3 instalados.
• Claves de proveedor si usas nube (OpenAI, Anthropic, etc.); Ollama reduce coste en casa.
• Red interna sana (DNS, MTU en bridges) — mismos dolores que en cualquier despliegue de datos plane.

Si vas a combinar inferencia GPU con agentes, revisa primero GPU scheduling en Kubernetes: kagent orquesta llamadas, pero no arregla un nodo sin drivers.

Instalación con la CLI (perfil demo)

La documentación oficial recomienda la CLI para arranque rápido. Flujo mínimo:

export OPENAI_API_KEY="tu-clave"
# macOS: brew install kagent
# Linux/macOS alternativo:
curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash

kagent install --profile demo
kagent dashboard

--profile demo trae agentes y herramientas precargadas; si quieres menos superficie, --profile minimal. Tras instalar, abre la URL que imprime el dashboard y valida que los pods en el namespace configurado estén Running antes de invitar a tu equipo a “jugar con producción”.

Instalación con Helm (OpenAI u Ollama)

Cuando prefieras GitOps puro, usa los charts OCI publicados en la guía Installing kagent:

kubectl create namespace kagent

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

export OPENAI_API_KEY="tu-clave"
helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --namespace kagent \
  --set providers.default=openAI \
  --set providers.openAI.apiKey="$OPENAI_API_KEY"

Antes de reinstalar, consulta la guía de uninstall oficial para limpiar CRDs y releases en el orden correcto; en homelab es fácil dejar webhooks colgando si borras namespaces a mano mientras Helm aún cree poseer el release. Un helm list -A honesto tras cada intento te ahorra horas de “pero si ya lo borré”.

Para Ollama, la misma página documenta providers.default=ollama sin API key en el snippet público (ajusta a tu topología real de red y DNS internos). Acceso UI típico:

kubectl port-forward -n kagent svc/kagent-ui 8080:8080

Seguridad: RBAC, secretos y blast radius

MCP define cómo se invoca una herramienta; no decide si el agente debería borrar un Namespace. Checklist corto:

• Crea Roles dedicados y evita cluster-admin salvo laboratorio controlado.
• Guarda claves en Secrets o gestores externos; nunca en el historial de shell compartido.
• Activa auditoría de acciones sensibles (Helm delete, cambios de malla Istio, políticas Cilium).
• Expón la UI solo vía Traefik o Caddy con TLS y allowlist IP en homelab.

Piensa en kagent kubernetes mcp agentes como un multiplicador de poder: útil y peligroso si el RBAC es perezoso.

Observabilidad: trazas y métricas

El proyecto menciona OpenTelemetry para entender dónde se fue el tiempo (LLM vs herramienta vs API). En homelab, conecta trazas a tu stack existente o, como mínimo, conserva logs estructurados del controlador cuando abras un ticket. Si ya correlacionas métricas con Prometheus + Grafana, añade paneles de latencia de invocaciones MCP y errores por ToolServer.

Métricas mínimas que sí importan

No necesitas un data lake para empezar: cuenta invocaciones MCP exitosas vs fallidas, histograma de latencia por herramienta y ratio de tokens consumidos por conversación. Si una herramienta de Helm dispara picos de error 401/403, revisa ServiceAccount antes de culpar al modelo. Si una herramienta de Prometheus se vuelve lenta, revisa query_range abusivo: el agente puede estar pidiendo ventanas temporales absurdamente anchas sin maldad, solo por prompt ambiguo.

Exporta esas métricas al mismo lugar donde ya miras saturación de nodos: une el plano de IA con el plano de plataforma. Cuando alguien pregunte “¿por qué kagent ‘va mal’?”, tu respuesta debe citar series temporales, no intuiciones.

Matriz de riesgo: MCP frente a kubectl improvisado

La tabla no dice que kagent sea “más seguro por magia”: dice que te da anclajes para aplicar prácticas que ya conoces de Kubernetes. Si ignoras RBAC, el resultado es peligroso en ambas columnas.

Comparativas: kagent y agentes en Kubernetes

Para orquestación de workflows híbridos (LLM + bases SQL), sigue teniendo sentido combinar con patrones de n8n y bases de datos–mysql-mongodb-guia-completa-tutorial-2025/): kagent no reemplaza ETL ni BPMN, resuelve agentes nativos en plataforma.

Homelab: dimensionar kind, k3s y perfiles demo

El perfil demo es pedagógico, no minimalista: arrastra varios tool servers y controladores que compiten por CPU y RAM en un nodo único. Antes de quejarte de “kagent va lento”, mide con kubectl top pod -n kagent y revisa throttling de CPU. En kind, aumentar memoria del nodo Docker/Colima suele importar más que subir la versión del modelo LLM.

Si tu homelab es un PC modesto, prueba --profile minimal y habilita herramientas de a una, validando impacto. Documenta en tu wiki interna: versión de chart, digest de imágenes críticas y tiempo de arranque en frío; es la misma disciplina que aplicarías a cualquier operador crítico en Kubernetes.

Cuando pases a k3s en bare metal, revisa también disco: pulls de imágenes medianas multiplicadas por varios agentes pueden saturar SSD baratos. Un local-path lento se nota como latencia MCP “inexplicable” porque el modelo espera a que el tool server arranque tras un Evicted silencioso.

GitOps: kagent, valores Helm y MCP

Tratar kagent kubernetes mcp agentes como código implica guardar manifests/Helm values en Git, sin secretos en claro. Usa helm upgrade --install con values.yaml versionado y sops/age o un External Secrets Operator si ya lo operas. El campo controller.env documentado en la guía oficial permite fijar nombres de servicio (KAGENT_CONTROLLER_NAME) y niveles de log sin reempaquetar la imagen.

Define un flujo de promoción: dev (namespace aislado) → staging (misma chart, dataset de prueba) → prod (solo cuando el RBAC y las políticas de red estén firmadas). Si saltas directo a prod porque “es casa”, al menos conserva helm get values exportados y un kubectl get de CRDs relevantes tras cada cambio: tu yo futuro lo agradecerá cuando un agente empiece a llamar una herramienta que deshabilitaste hace tres releases.

Istio, Helm y Prometheus desde la mirada del agente

Los ToolServers orientados a Istio, Helm o Prometheus son potentes porque acercan el lenguaje natural a acciones de plataforma; también multiplican el riesgo si el agente interpreta mal una instrucción. Reglas prácticas:

• Helm: evita permisos de borrado masivo en releases compartidas; usa namespaces de práctica.
• Istio: cambiar malla o rutas puede romper tráfico real; separa laboratorio y producción a nivel de clúster o al menos de mesh.
• Prometheus: consultas pueden ser caras; limita rangos temporales y protege el query path con cuotas.

Si ya observas el plano de datos con Prometheus + Grafana, añade paneles que correlacionen errores MCP con revisiones Helm recientes: muchos incidentes son drift de configuración, no alucinaciones del modelo.

Tabla de decisiones rápidas

Roadmap de seguridad en cuatro fases

Fase 1 — Inventario: lista ServiceAccounts, CRDs instalados por kagent, namespaces tocados y endpoints expuestos hacia LLM (Ollama en LAN, pasarela corporativa, etc.). Sin inventario honesto, cualquier auditoría de MCP será teatro.

Fase 2 — Mínimo privilegio: recorta verbos de kubectl efectivos vía Roles; separa agentes “solo lectura” de agentes “mutadores”. Documenta qué ToolServer puede hacer delete o rollout y quién puede invocarlo. Aquí kagent kubernetes mcp agentes deja de ser un slogan y pasa a ser matriz de riesgos.

Fase 3 — Observabilidad mínima viable: trazas OTel o, si no puedes, logs JSON con request_id correlacionado entre UI y controlador. Añade alertas simples: ratio 5xx en tool calls, latencia p95 del proveedor LLM, reinicios del controlador.

Fase 4 — Game days: una vez al mes, rompe a propósito un namespace de prueba y mide tiempo de detección/recuperación. Si el agente tarda más que tu equipo humano en diagnosticar, ajusta prompts, límites o herramientas antes de tocar producción.

Ollama en LAN: DNS, TLS y políticas

Cuando providers.default=ollama, el problema típico del homelab no es Helm sino red: el pod resuelve ollama.svc.cluster.local pero tu instancia vive en otra máquina sin DNS interno coherente. Opciones sanas: desplegar Ollama dentro del mismo clúster, publicarlo con un Service estable o usar un reverse proxy interno con TLS reutilizando patrones de Caddy. Evita HTTP plano cruzando WiFi de vecinos “porque es casa”: los prompts pueden llevar datos sensibles aunque el modelo sea local.

Si combinas con Traefik, centraliza certificados y middlewares de rate-limit para la UI de kagent y para el endpoint LLM, pero con rutas separadas para no mezclar cookies ni cabeceras de autorización.

Ejemplo de manifiesto parcial (ilustrativo)

apiVersion: v1
kind: Namespace
metadata:
  name: kagent-lab
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: kagent-lab
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress

Completa reglas egress hacia el Service LLM y ingress desde el namespace de observabilidad; el bloque anterior solo muestra el patrón “deny-all explícito” que muchos tutoriales omiten.

Troubleshooting práctico

1. ImagePullBackOff: revisa credenciales del registry y límites de red saliente.
2. Pods reiniciando tras install: orden CRDs → chart principal; mira kubectl logs -n kagent deploy/kagent-controller.
3. UI en blanco: confirma svc/kagent-ui y port-forward; limpia caché del navegador.
4. Herramienta MCP ausente: valida CRDs y que el ToolServer esté aplicado en el namespace correcto.
5. Latencias altas LLM: no culpes al controlador antes de medir tokens/s del proveedor (vLLM sigue siendo referencia para servir modelos, aunque sea capa distinta).
6. Webhook bloqueando recursos: revisa CRDs y jobs de certificación; a veces un helm uninstall parcial deja validatingwebhook apuntando a servicios inexistentes.
7. Desajuste de versión CLI vs chart: alinea versiones según release notes del proyecto; mezclar main con charts antiguos produce errores crípticos en reconciliación.

kubectl get pods -n kagent
kubectl get svc -n kagent
helm list -n kagent
kubectl get validatingwebhookconfiguration | grep -i kagent || true

📦 Descargar ejemplos

Repo público con scripts y fragmentos Helm:

https://github.com/ziruelen/learningaiagents/tree/main/kubernetes/kagent-kubernetes-mcp-agentes-ia-2026

Enlaces relacionados

• MCP: guía completa 2026
• OpenAI Agents SDK (multi-agent)
• Dapr Agents en Kubernetes
• GPU scheduling en Kubernetes
• Prometheus + Grafana (observabilidad)
• Flowise: RAG sin código

Preguntas frecuentes

¿Qué es exactamente kagent kubernetes mcp agentes en una frase?

Es la combinación del proyecto kagent, un clúster Kubernetes y herramientas MCP usadas por agentes declarativos. No sustituye políticas de seguridad ni revisión humana: ordena el caos operativo, no lo elimina.

¿Necesito GPU en el clúster?

No para el control plane; sí si tus agentes invocan inferencia local pesada. Separa el plano de control del plano de cómputo LLM. Si usas tool calls que disparan jobs de inferencia, etiqueta nodos con taints/labels y coloca nodeSelector/tolerations coherentes con la guía de scheduling que enlazamos arriba.

¿Puedo usar Ollama en casa?

Sí; la guía oficial lista providers.default=ollama. Asegura conectividad desde pods hasta el endpoint Ollama. Verifica también MTU y DNS internos: muchos “timeouts MCP” son en realidad paquetes negados o rutas asimétricas cuando mezclas CNI del host con túneles externos.

¿kmcp viene siempre activo?

Desde 0.7 se incluye por defecto; desactívalo si choca con tu kmcp previo (kmcp.enabled=false en ambos charts).

¿Es lo mismo kagent que kubectl-ai informal?

No: kagent es marco declarativo con CRDs/UI; un script suelto carece de ese contrato.

¿Cómo comparo con Dapr Agents?

Dapr Agents resuelve agentes durables y patrones de actores; kagent centra MCP y herramientas de plataforma. Pueden convivir conceptualmente, no son drop-in uno del otro.

¿Qué perfil elijo en homelab?

demo para aprender; minimal si tu nodo es justo de RAM.

¿Dónde veo ejemplos Helm avanzados?

Helm reference del proyecto y el repo de ejemplos de este artículo.

¿Cómo protejo la UI?

TLS con Traefik o Caddy y acceso restringido.

¿Puedo auditar llamadas MCP?

Debes: conserva trazas OTel/logs y limita RBAC por herramienta.

¿Qué pasa si instalo dos veces el chart?

Helm upgrade/install debe ser idempotente, pero revisa releases duplicadas (helm list -A).

¿Es producción-ready?

Revisa el roadmap y versiones (v0.9.x beta a fecha de documentación consultada); trata homelab como canario.

¿Cómo combino con n8n?

Usa n8n para workflows de negocio y kagent para operaciones declarativas del clúster; no mezcles secretos entre sistemas.

¿Hay curso o lab gratuito?

La web promociona Kagent Lab para practicar kagent y kmcp bajo demanda.

¿Qué hago si falla el port-forward?

Comprueba svc, Endpoints y políticas de red; a veces el servicio aún no tiene endpoints listos.

Conclusión

kagent acerca MCP y agentes al mundo GitOps sin pedirte renunciar a Kubernetes como fuente de verdad. Úsalo cuando quieras herramientas compartidas, UI y trazas en el mismo sitio donde ya operas cargas. Si tu objetivo es solo chatear con un modelo, bastará Ollama y una UI; si tu objetivo es kagent kubernetes mcp agentes con gobernanza, invierte tiempo en RBAC, secretos y observabilidad antes de abrir el clúster a más gente.

Cierra el ciclo descargando los scripts del repositorio de ejemplos, ejecutándolos primero en un namespace desechable y anotando en el changelog del homelab qué perfil Helm usaste. Esa cadena de evidencias —comandos, valores y resultado— es lo que separa un experimento de una plataforma que otro humano puede mantener contigo, no en tu ausencia.