Aísla sesiones de agente con Google Agent Substrate

Un agente pasa la mayor parte de su vida esperando. Ejecuta código durante unos segundos, y luego queda inactivo mientras un modelo piensa, una herramienta responde o una persona lee. En Kubernetes simple, esa sesión inactiva sigue ocupando un Pod, con memoria y cómputo bloqueados en una conversación que no está haciendo nada.

Agent Substrate ataca ese desperdicio. Google lo construyó, llegó a la versión 1.0 esta semana y lo donó a la Cloud Native Computing Foundation, donde está en el CNCF Sandbox. Google dice que la forma gestionada, Agent Substrate en GKE, ya está disponible de forma general. Este tutorial usa la versión de código abierto que documenta el proyecto kagent: Substrate 0.0.9 en un clúster kind local, con un agente ejecutándose dentro de un sandbox gVisor.

Lo que vas a construir o aprender

Terminarás con un clúster kind local que ejecuta Agent Substrate en el namespace ate-system y kagent con el enlace a Substrate activado. Crearás un agente declarativo llamado hello-substrate. Ese agente se ejecuta como un Actor de Substrate dentro de gVisor, no como un Deployment simple.

También aprenderás las tres palabras que explican todo el sistema. Un Actor guarda una sesión y su estado. Un Worker aporta cómputo desde un grupo compartido. Una Gateway controla el tráfico entrante y saliente y puede inyectar secretos por identidad del Actor, para que las claves permanezcan fuera del entorno del agente. Google describe esa división en su anuncio de la 1.0, y los pasos siguientes siguen la guía de kagent para Agent Substrate.

Antes de empezar

Lee el alcance antes de escribir. Este es un clúster de prueba local, no una configuración de producción. La guía de kagent afirma que el chart de Substrate 0.0.9 usa por defecto autenticación JWT respaldada por tokens de ServiceAccount de Kubernetes, así que un clúster kind simple funciona sin puertas de funciones y sin configuración personalizada de kind. Las decisiones de producción como el aislamiento con microVM de Cloud Hypervisor, el almacenamiento y la política de acceso quedan fuera de este recorrido.

Una afirmación necesita una etiqueta antes de que empiecen los pasos. Las cifras en la Versión corta, restauración en menos de 500 milisegundos, densidad 10x sobre tiempos de ejecución de contenedores estándar y más de 500 acciones de suspensión y reanudación por segundo, son cifras de Google para la versión 1.0. Este tutorial no las mide. Un solo trabajador en una computadora portátil puede mostrar la forma de suspensión y reanudación. No puede demostrar densidad a escala.

Paso 1: Crea un clúster kind

Acción: crea un clúster local de Kubernetes llamado kagent-substrate.

kind create cluster --name kagent-substrate

Resultado esperado: kind informa que el clúster está listo y kubectl apunta a él. No se necesita configuración personalizada para Substrate 0.0.9, según la guía de kagent.

Paso 2: Exporta tu clave de modelo y revísala

Acción: exporta una clave de API de OpenAI en la misma shell que usarás para Helm, y luego demuestra que la shell puede verla. Usa un marcador en cualquier nota que guardes.

export OPENAI_API_KEY="your-key-here"
[[ -n "${OPENAI_API_KEY:-}" ]] && echo "key is set (len=${#OPENAI_API_KEY})" || echo "OPENAI_API_KEY is empty, export it first"

Resultado esperado: la comprobación imprime la longitud de la clave y nunca imprime la clave. La guía advierte contra poner la exportación y el comando de Helm en una línea, porque la shell puede expandir la variable antes de que se ejecute la asignación y pasar una cadena vacía.

Paso 3: Instala Agent Substrate 0.0.9

Acción: instala primero los recursos personalizados de Substrate, y luego el plano de control y el plano de datos de Substrate, ambos en ate-system.

helm upgrade --install substrate-crds oci://ghcr.io/kagent-dev/substrate/helm/substrate-crds --version 0.0.9 --namespace ate-system --create-namespace --wait

helm upgrade --install substrate oci://ghcr.io/kagent-dev/substrate/helm/substrate --version 0.0.9 --namespace ate-system --wait --timeout 10m

kubectl get pods -n ate-system

Resultado esperado: la lista de pods muestra pods ate-api-server, ate-controller, atelet, atenet-router, los pods valkey-cluster y rustfs en estado Running, más algunos trabajos de inicio en estado Completed. Los nombres varían en el sufijo. El estado es lo que importa aquí.

Paso 4: Instala kagent con Substrate activado

Acción: instala los recursos personalizados de kagent, y luego kagent mismo con las banderas de Substrate de la guía. Fija los charts. Las versiones anteriores a v0.9.7 carecen de los valores que este paso define, y Helm ignora valores desconocidos en silencio, así que un chart antiguo empieza sin enlace a Substrate y sin error.

helm upgrade --install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds --version 0.10.6 --namespace kagent --create-namespace --wait

helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent --version 0.10.6 --namespace kagent --timeout 10m --wait --set providers.openAI.apiKey="$OPENAI_API_KEY" --set providers.default=openAI --set controller.substrate.enabled=true --set controller.substrate.ateApiEndpoint=dns:///api.ate-system.svc:443 --set controller.substrate.ateApiInsecure=true --set substrateWorkerPool.create=true --set substrateWorkerPool.replicas=1 --set substrateWorkerPool.ateomImage=ghcr.io/kagent-dev/substrate/ateom-gvisor:v0.0.9

kubectl get secret kagent-openai -n kagent
kubectl get workerpools.ate.dev -A

Resultado esperado: el secreto existe con una entrada de datos, y existe un WorkerPool llamado kagent-default. Un trabajador es suficiente para este recorrido. La guía señala que los Actors de sesión liberan su espacio cuando se guardan como instantánea de vuelta al almacenamiento, así que un Worker puede servir muchas sesiones en secuencia. Agrega trabajadores más adelante si quieres sesiones que se superpongan en el tiempo.

Si Helm agota el tiempo mientras los pods inician, espera al controlador a mano y luego continúa:

kubectl wait deploy/kagent-controller -n kagent --for=condition=Available --timeout=10m

Paso 5: Abre la interfaz de kagent

Acción: redirige la interfaz de kagent a tu computadora y ábrela en un navegador.

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

Resultado esperado: la interfaz carga en http://localhost:8001. Omite el asistente de primera ejecución si aparece. Deja la redirección en ejecución en esta terminal y usa una segunda terminal para el paso siguiente.

Paso 6: Crea un agente en Substrate

Acción: aplica un manifiesto SandboxAgent. El bloque substrate apunta el agente al WorkerPool kagent-default. El tiempo de ejecución debe ser Go. La guía afirma que el ADK de Python no es compatible con Substrate hoy.

kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: SandboxAgent
metadata:
  name: hello-substrate
  namespace: kagent
spec:
  type: Declarative
  description: Tiny declarative agent running inside a substrate actor
  declarative:
    runtime: go
    modelConfig: default-model-config
    systemMessage: |
      You are a friendly assistant living inside an Agent Substrate sandbox.
      When asked who you are, say "I am hello-substrate, a Go ADK declarative agent running inside a gVisor actor."
  substrate:
    workerPoolRef:
      name: kagent-default
EOF

kubectl wait sandboxagent/hello-substrate -n kagent --for=condition=Ready --timeout=5m

Resultado esperado: el agente llega a Ready. La guía sitúa la primera instantánea dorada en unos 60 a 90 segundos. Una instantánea dorada es el estado inicial guardado del que se restauran los nuevos Actors, así que las sesiones posteriores empiezan rápido en lugar de construir desde cero.

Paso 7: Conversa y observa cómo se suspende el Actor

Acción: en la interfaz en http://localhost:8001, abre la lista de agentes, elige kagent/hello-substrate y envía esta instrucción: What are you, and where are you running? Answer in one sentence.

Resultado esperado: el agente responde con la frase de su mensaje de sistema, nombrándose como un agente declarativo Go ADK dentro de un Actor gVisor. Detrás de esa respuesta, un Actor de sesión se restauró desde la instantánea dorada, ejecutó la llamada al modelo y se guardó como instantánea de vuelta al almacenamiento. Abre View, y luego Substrate, en la interfaz para ver el Actor en el inventario. Entre solicitudes debería estar en estado Suspended. Esa única palabra es todo el sentido del sistema, hecho visible.

Verificación

Ejecuta esta lista antes de dar la configuración por terminada:

1. kubectl get pods -n ate-system muestra los pods de Substrate en Running, con solo trabajos de inicio en Completed.
2. kubectl get secret kagent-openai -n kagent muestra un secreto con una entrada de datos.
3. kubectl get workerpools.ate.dev -A muestra kagent-default.
4. El agente hello-substrate llega a Ready y responde la instrucción de prueba en la interfaz.
5. La vista de Substrate muestra el Actor de sesión como Suspended entre solicitudes.

Si las cinco se cumplen, tienes el ciclo central funcionando: estado en el Actor, cómputo en el Worker y ningún Pod rehén de un chat inactivo.

Solución de problemas

Próximos pasos

Lee la página de conceptos de Agent Substrate enlazada desde la guía de kagent para el relato completo de instantáneas, Actors y WorkerPools. Luego mira la ruta AgentHarness en la misma documentación, que coloca agentes de programación de larga duración en Substrate. Quienes ejecutan Hermes se preocuparán por esa ruta en particular, y nuestro tutorial de configuración de Hermes Agent cubre el lado del agente de ese emparejamiento.

Para una lectura de producción, compara esta ruta local con Agent Substrate en GKE en la documentación de Google Cloud, y sopesa gVisor frente a microVM de Cloud Hypervisor como tu límite de aislamiento. Google dice que Substrate acepta contenedores OCI estándar y funciona con agentes ADK y configuraciones de programación con estado. Prueba esa afirmación con un agente pequeño propio antes de mover cualquier flota a él.

Empieza pequeño, observa el estado Suspended hacer su trabajo y escala el WorkerPool solo cuando tus sesiones realmente se superpongan. La densidad es una afirmación hasta que tu propio tráfico la demuestre.

Pasos, versiones y comandos verificados contra la guía de Agent Substrate de kagent y el anuncio 1.0 de Google Cloud el 2026-11-07. Este procedimiento se verificó contra esos documentos; no se ejecutó de extremo a extremo en una computadora de prueba para este artículo.

Fuentes

• Guía de Agent Substrate y comandos de instalación: documentación de kagent, ejemplo de Agent Substrate
• 1.0, donación a CNCF, Actors, Workers, Gateways y cifras de rendimiento de Google: Google Cloud Blog, Open infrastructure for autonomous agents comes to CNCF, 2026-11-05
• Diagrama: Google Cloud Blog