kagent agentes de IA Kubernetes: el framework en detalle

kagent agentes de IA Kubernetes: agentes en YAML, herramientas MCP, elección del modelo, instalación según la doc, límites y trazas OpenTelemetry.
kagent agents IA Kubernetes : le framework en détail

kagent agentes de IA Kubernetes: el repositorio kagent-dev/kagent describe un framework «nativo de Kubernetes» para construir, desplegar y gestionar agentes de IA. En él, un agente se convierte en un recurso de Kubernetes, declarado en YAML, versionado en Git y reconciliado por un controlador. El repositorio tiene licencia Apache 2.0 y su README presenta kagent como un proyecto de la Cloud Native Computing Foundation.

El problema es conocido por los equipos de plataforma. Cada equipo lanza sus agentes a su manera, con sus claves de modelo y sus herramientas, sin una vista común. kagent propone pasar por la API de Kubernetes: el modelo, las herramientas MCP y el comportamiento del agente son objetos declarativos. ¿Qué contiene el repositorio, cómo se instala y, sobre todo, cómo se supervisan agentes que llaman a herramientas en tu clúster?

Aclaración de honestidad: span.observer no ha instalado ni ejecutado kagent. Lo que sigue procede del README, de la carpeta docs/ del repositorio (leída en un clon el 8 de noviembre de 2026) y de las páginas de documentación de kagent.dev. Las capturas provienen del repositorio o reproducen sus archivos.

kagent agentes de IA Kubernetes: lo que dice el repositorio

  • Licencia: el archivo LICENSE contiene el texto de la Apache License 2.0.
  • Quién está detrás: el repositorio pertenece a la organización de GitHub kagent-dev. El README termina con «kagent is a Cloud Native Computing Foundation project» y no nombra a ningún proveedor comercial.
  • Lenguajes: el repositorio contiene un módulo Go (go/, con go.mod), paquetes Python (python/), una interfaz web (ui/) y charts de Helm. El panel de lenguajes de la página de GitHub estaba vacío al leerla, así que no citamos ningún porcentaje.
  • Estrellas: la página del repositorio mostraba unas 4,2 k estrellas el 8 de noviembre de 2026 (valor redondeado). La API de GitHub fue rechazada y no se pudo releer ningún valor exacto.
  • Versión: la página del repositorio no mostraba ninguna release al leerla, y no citamos una «última versión» oficial. La documentación de instalación de la serie 1.x usa v1.0.0-rc3 para el CLI: es una candidata a la versión 1.0, no una versión final.
  • Actividad: el último commit del clon es del 7 de noviembre de 2026. El README habla de un proyecto «en desarrollo activo», con una hoja de ruta en un tablero de GitHub.

Los conceptos: agentes, modelos y herramientas MCP

El README enumera las piezas. Un Agent es un recurso personalizado de Kubernetes. Un AgentTemplate define el comportamiento: prompt de sistema, herramientas, subagentes y modelo. Un Harness decide cómo se ejecuta el agente: runtimes de Go o Python propios de kagent, Codex, Claude o un runtime personalizado.

Los modelos se configuran en un recurso ModelConfig. El README cita OpenAI, Azure OpenAI, Anthropic, Google Vertex AI y Ollama, además de proveedores personalizados detrás de una pasarela. Las opciones posibles dependen del Harness elegido.

Las herramientas pasan por MCP. Según el README, kagent incluye un servidor MCP con herramientas para Kubernetes, Istio, Helm, Argo, Prometheus, Grafana o Cilium. Los agentes se conectan a él mediante recursos RemoteMCPServer, que se pueden compartir entre agentes. Para conocer el riesgo de este modelo, lee el envenenamiento de herramientas MCP.

La primera captura muestra la lista de agentes de la interfaz web, extraída del GIF del README. Es de una versión anterior de la interfaz: la de la versión 1.x puede ser distinta.

Interfaz web de kagent tomada del GIF del README: tarjetas de agentes (gcp-gke-agent, github-agent, hashicorp-vault-agent, helm-agent, istio-agent, k8s-agent, kgateway-agent) con su descripción y el modelo OpenAI gpt-4.1-mini
Source : github.com

Arquitectura: controlador, PostgreSQL y Substrate

La documentación de arquitectura describe un plano de control. Kubernetes almacena la configuración deseada (Agent, Harness, AgentTemplate, EgressPolicy, entre otros). PostgreSQL almacena la identidad de ejecución, el historial A2A y el estado del ciclo de vida. Los «Actors» de Substrate ejecutan los procesos de los agentes, con suspensión, reanudación e instantáneas.

El controlador expone APIs gRPC, A2A y MCP. Una sesión conserva el historial y la documentación habla de puntos de control (checkpoints) para bifurcar una conversación. La misma documentación enumera lo que aún no está implementado: los enlaces de agentes dedicados, la delegación entre sesiones bajo política, el uso compartido de checkpoints y la coordinación de pasarelas con varias réplicas.

Instalar kagent, según la documentación

Requisitos citados por la página de instalación 1.x: Kubernetes 1.37 o superior, con las API PodCertificateRequest y ClusterTrustBundle; helm v3 y kubectl; una clave de API de un modelo. Para un clúster local, la página cita kind v0.32.0 o superior. kagent 1.0 no se actualiza in situ desde la 0.10.x.

Camino de evaluación: el CLI

El CLI despliega una base PostgreSQL de desarrollo y luego instala los charts en orden. Comandos de la página (clave ficticia):

kind create cluster --name kagent --image kindest/node:v1.37.0
export OPENAI_API_KEY="your-api-key-here"

curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v1.0.0-rc3
kagent version

cat > kagent-values.yaml <<EOF
config:
  server:
    grpcReflection: true
EOF
cat > kagent-config.yaml <<EOF
install:
  kagent:
    valuesFiles: [kagent-values.yaml]
EOF

kagent --config kagent-config.yaml install --namespace kagent
kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s

La documentación del repositorio precisa que la base de desarrollo no está pensada para producción y que kagent install crea autoridades de certificación válidas durante un año, que nada renueva.

Camino de producción: Helm

Aquí aportas tú PostgreSQL 15 o superior: los charts no despliegan ninguno. La página encadena los charts kagent-crds y substrate-crds, los pools de autoridades y de claves JWT (plugin kubectl-ate), substrate-podcert, substrate-atelet, substrate y, por último, kagent desde oci://ghcr.io/kagent-dev/kagent/helm/kagent. Los archivos de valores completos están en la documentación oficial: no los copiamos.

Verificar

kubectl get pods -n kagent
kubectl get pods -n ate-system
kubectl get workerpools -n kagent
kubectl port-forward -n kagent svc/kagent-ui 8082:8080

La página espera pods en Running y un WorkerPool kagent-default listo, y después una interfaz en el puerto local 8082. La guía «Your first agent» crea a continuación un Harness, un AgentTemplate y un Agent, y sigue el estado con kagent agent get.

Un agente declarado en YAML

La carpeta docs/architecture/ contiene un ejemplo completo, que la captura reproduce: un ModelConfig y un RemoteMCPServer en un espacio de nombres compartido, y un AgentTemplate y un Agent en team-a. Se da por hecho que el Harness llamado runner ya existe. La API es api.kagent.dev/v1alpha3, por lo que sigue siendo una versión alfa de la API de Kubernetes.

Manifiestos YAML del repositorio kagent-dev/kagent: ModelConfig shared-model, RemoteMCPServer shared-tools, AgentTemplate assistant y Agent assistant en el espacio de nombres team-a, con api.kagent.dev/v1alpha3
Source : github.com

Puntos a retener: apiKeySecret designa un Secret de Kubernetes y allowedNamespaces controla quién puede usar el modelo o el servidor de herramientas. Con from: Selector, solo tienen acceso los espacios de nombres cuyas etiquetas coinciden. El Secret model-auth hay que crearlo aparte: sus credenciales no se copian a team-a.

Límites y puntos abiertos

  • Madurez: la serie 1.x se presenta como candidata a versión (rc3 en la documentación leída), la API está en v1alpha3 y la ruta de migración desde la 0.10.x es manual. Un cambio de versión puede recrear instantáneas o bases de datos (la documentación señala migraciones no retrocompatibles en Substrate).
  • Complejidad: hacen falta PostgreSQL, Substrate, una PKI interna y un Kubernetes muy reciente. No es un simple chart que se instala y listo.
  • Permisos RBAC: sin restricción de espacios de nombres, el chart crea ClusterRoles y ClusterRoleBindings. El README de Helm distingue un rol de reconciliación y un rol de gestión que escribe CRD, Secrets y ConfigMaps; precisa que ningún modo desactiva esas escrituras. Restringe con rbac.namespaces o global.watchNamespaces.
  • Secretos: según la documentación, las claves de modelo no van en el entorno compilado: la pasarela de Substrate las inyecta en la cabecera HTTP saliente, con una caché que puede tardar hasta cinco minutos en refrescarse tras una rotación.
  • Herramientas: un agente conectado al servidor de herramientas de Kubernetes o Helm actúa sobre el clúster. Limita sus permisos y sus espacios de nombres, como en las barreras de protección de los agentes de IA en producción.
  • No verificado: rendimiento, costes de modelo y comportamiento real de los agentes. No hemos medido nada.

Observar kagent: trazas OpenTelemetry

La documentación describe una exportación de trazas OpenTelemetry desde el controlador y los runtimes de agentes. Nada está activo por defecto: se declara un exportador OTLP en el chart. La configuración admite también exportadores metrics y logs, cada uno con endpoint, protocol (grpc o http/protobuf) y timeout.

Valores de Helm de kagent tomados de docs/architecture/telemetry.md: config.telemetry.traces.endpoint hacia controller-collector:4317, runtimeDefaults.telemetry con agent-collector:4317, captureContent false, maxCaptureBytes 16384
Source : github.com

La página de trazado de kagent.dev insiste: el mismo bloque va en config.telemetry (el controlador) y en config.runtimeDefaults.telemetry (los agentes). Con solo uno, parte del recorrido queda sin trazas. Tras un helm upgrade, crea una sesión nueva: un Actor existente conserva la configuración con la que arrancó.

El contrato de telemetría usa las convenciones GenAI: gen_ai.agent.name, gen_ai.conversation.id, gen_ai.request.model, además de atributos kagent.* y a2a.*. Los spans llevan operaciones como invoke_agent y execute_tool. Los mensajes y los argumentos de las herramientas solo se registran si activas la captura de contenido: deja captureContent: false hasta que hayas evaluado el riesgo para tus datos.

Dos consejos de la documentación que conviene aplicar. Primero, mantén un muestreo de SDK de tipo parent-based AlwaysOn y muestrea en el Collector; si no, las trazas distribuidas pueden quedar incompletas. Segundo, activa la propagación de baggage solo con conocimiento de causa: los miembros del llamante pueden viajar hacia la API del modelo y hacia los servidores MCP.

Desde el lado SRE, se pueden deducir algunos SLI de esos spans: duración de invoke_agent, tasa de error de execute_tool, llamadas al modelo por invocación. Para el coste en tokens, consulta el coste de un agente de IA por tokens con OpenTelemetry. Los logs del controlador siguen siendo los de kubectl logs deployment/kagent-controller -n kagent. La documentación leída no describe una lista de métricas que vigilar: no inventamos ninguna.

¿Y Dynatrace?

kagent no documenta ninguna integración con Dynatrace y no suponemos ninguna. Como kagent exporta en OTLP, un Collector de OpenTelemetry puede recibir esas trazas. Lo que sigue depende de la documentación de Dynatrace: consulta el Collector de OpenTelemetry hacia Dynatrace en OTLP/HTTP. No hemos probado este encadenamiento.

Buenas prácticas

  • Evalúa kagent en un clúster kind aislado, con una clave de modelo con tope de gasto.
  • Versiona Agent, AgentTemplate y ModelConfig en Git y despliégalos como en Argo CD para Kubernetes.
  • Limita rbac.namespaces y allowedNamespaces a lo estrictamente necesario.
  • Activa las trazas en el controlador y en los runtimes, con la captura de contenido desactivada.
  • Relee las notas de versión antes de cada actualización: la API sigue siendo alfa.

Preguntas frecuentes

¿Está kagent listo para producción?

La documentación propone un camino Helm «de producción», pero la serie 1.x aparece como candidata a versión y la API en v1alpha3. Prueba primero, lee la lista de funciones no implementadas y prevé la migración desde la 0.10.x.

¿Qué modelos acepta kagent?

Según el README: OpenAI, Azure OpenAI, Anthropic, Google Vertex AI, Ollama y proveedores personalizados detrás de una pasarela, mediante ModelConfig. El soporte exacto depende del Harness elegido.

¿Cómo se sigue lo que hace un agente?

Activa la exportación de trazas OTLP en el chart, en el controlador y en runtimeDefaults, y después lee los spans invoke_agent y execute_tool en tu backend. Las sesiones y el historial de tareas también se conservan en PostgreSQL.

Conclusión

kagent da un marco de Kubernetes a los agentes de IA: recursos declarativos, herramientas MCP, modelos a elegir y trazas OpenTelemetry. Exige una infraestructura pesada y un clúster reciente, y su API sigue siendo alfa. Si tu equipo de plataforma quiere gestionar los agentes como el resto de sus cargas, merece una prueba en un clúster de test.

span.observer es un blog independiente de la comunidad, no afiliado al proyecto kagent, a la Cloud Native Computing Foundation ni a Dynatrace LLC. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba siempre los comandos y las opciones en su documentación oficial.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
agent-desktop computer use : piloter un bureau par agent IA

agent-desktop computer use: manejar un escritorio con un agente de IA

Next Post
Formation Dynatrace gratuite : 9 parcours pour débuter

Formación Dynatrace gratis: 9 rutas para empezar

Related Posts