Isoler les sessions d'agents avec Google Agent Substrate

Un agent passe la plus grande partie de sa vie à attendre. Il exécute du code pendant quelques secondes, puis reste inactif pendant qu’un modèle réfléchit, qu’un outil répond ou qu’une personne lit. Dans Kubernetes ordinaire, cette session inactive garde quand même un Pod, avec la mémoire et la puissance de calcul verrouillées sur une conversation qui ne fait rien.

Agent Substrate s’attaque à ce gaspillage. Google l’a construit, il a atteint la version 1.0 cette semaine et Google l’a donné à la Cloud Native Computing Foundation, où il se trouve dans le CNCF Sandbox. Google dit que la forme gérée, Agent Substrate sur GKE, est maintenant offerte en disponibilité générale. Ce tutoriel utilise la version libre que le projet kagent documente : Substrate 0.0.9 sur un cluster kind local, avec un agent qui fonctionne dans un bac à sable gVisor.

Ce que vous allez construire ou apprendre

Vous terminerez avec un cluster kind local qui fait fonctionner Agent Substrate dans l’espace de noms ate-system et kagent avec le lien Substrate activé. Vous créerez un agent déclaratif nommé hello-substrate. Cet agent fonctionne comme un Acteur Substrate dans gVisor, et non comme un Déploiement ordinaire.

Vous apprendrez aussi les trois mots qui expliquent tout le système. Un Acteur garde une session et son état. Un Travailleur fournit la puissance de calcul depuis un bassin partagé. Une Passerelle contrôle le trafic qui entre et qui sort et peut injecter des secrets selon l’identité de l’Acteur, pour que les clés restent hors de l’environnement de l’agent. Google décrit cette division dans son annonce 1.0, et les étapes ci dessous suivent le guide kagent pour Agent Substrate.

Avant de commencer

Lisez la portée avant de taper. C’est un cluster de test local, pas une installation de production. Le guide kagent indique que le graphique Substrate 0.0.9 utilise par défaut une authentification JWT adossée aux jetons ServiceAccount de Kubernetes, alors un cluster kind ordinaire fonctionne sans portes de fonctionnalités et sans configuration kind personnalisée. Les choix de production comme l’isolement avec des microVM Cloud Hypervisor, le stockage et la politique d’accès se trouvent hors de ce parcours.

Une affirmation a besoin d’une étiquette avant le début des étapes. Les chiffres dans la version courte, restauration en moins de 500 millisecondes, densité 10x par rapport aux environnements d’exécution de conteneurs standard et plus de 500 actions de suspension et de reprise par seconde, sont des chiffres de Google pour la version 1.0. Ce tutoriel ne les mesure pas. Un seul travailleur sur un portable peut montrer la forme de la suspension et de la reprise. Il ne peut pas prouver la densité à grande échelle.

Étape 1 : créer un cluster kind

Action : créez un cluster Kubernetes local nommé kagent-substrate.

kind create cluster --name kagent-substrate

Résultat attendu : kind signale le cluster prêt et kubectl pointe vers lui. Aucune configuration personnalisée n’est nécessaire pour Substrate 0.0.9, selon le guide kagent.

Étape 2 : exporter votre clé de modèle et la vérifier

Action : exportez une clé API OpenAI dans le même shell que vous utiliserez pour Helm, puis prouvez que le shell peut la voir. Utilisez un espace réservé dans toutes les notes que vous gardez.

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"

Résultat attendu : la vérification affiche la longueur de la clé et n’affiche jamais la clé. Le guide met en garde contre le fait de mettre l’exportation et la commande Helm sur une même ligne, parce que le shell peut développer la variable avant que l’affectation s’exécute et passer une chaîne vide.

Étape 3 : installer Agent Substrate 0.0.9

Action : installez d’abord les ressources personnalisées Substrate, puis le plan de contrôle et le plan de données Substrate, les deux dans 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

Résultat attendu : la liste des pods montre les pods ate-api-server, ate-controller, atelet, atenet-router, les pods valkey-cluster et rustfs à l’état Running, plus quelques tâches d’initialisation à l’état Completed. Les noms varient en suffixe. C’est l’état qui compte ici.

Étape 4 : installer kagent avec Substrate activé

Action : installez les ressources personnalisées kagent, puis kagent lui même avec les drapeaux Substrate du guide. Épinglez les graphiques. Les versions avant v0.9.7 n’ont pas les valeurs que cette étape règle, et Helm ignore les valeurs inconnues en silence, alors un vieux graphique démarre sans lien Substrate et sans erreur.

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

Résultat attendu : le secret existe avec une entrée de données, et un WorkerPool nommé kagent-default existe. Un travailleur suffit pour ce parcours. Le guide note que les Acteurs de session libèrent leur emplacement quand ils retournent en instantané dans le stockage, alors un seul Travailleur peut servir beaucoup de sessions en séquence. Ajoutez des travailleurs plus tard si vous voulez des sessions qui se chevauchent dans le temps.

Si Helm expire pendant que les pods démarrent, attendez le contrôleur à la main puis continuez :

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

Étape 5 : ouvrir l’interface kagent

Action : transférez l’interface kagent vers votre machine et ouvrez la dans un navigateur.

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

Résultat attendu : l’interface se charge à http://localhost:8001. Sautez l’assistant de premier lancement s’il apparaît. Laissez le transfert en marche dans ce terminal et utilisez un deuxième terminal pour l’étape suivante.

Étape 6 : créer un agent sur Substrate

Action : appliquez un manifeste SandboxAgent. Le bloc substrate pointe l’agent vers le WorkerPool kagent-default. L’environnement d’exécution doit être Go. Le guide indique que l’ADK Python n’est pas pris en charge sur Substrate aujourd’hui.

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

Résultat attendu : l’agent atteint Ready. Le guide place le premier instantané doré à environ 60 à 90 secondes. Un instantané doré est l’état de départ enregistré à partir duquel les nouveaux Acteurs se restaurent, pour que les sessions suivantes démarrent vite au lieu de construire à partir de zéro.

Étape 7 : clavarder et regarder l’Acteur se suspendre

Action : dans l’interface à http://localhost:8001, ouvrez la liste des agents, choisissez kagent/hello-substrate et envoyez cette invite : What are you, and where are you running? Answer in one sentence.

Résultat attendu : l’agent répond avec la phrase de son message système, se nommant comme un agent déclaratif Go ADK dans un Acteur gVisor. Derrière cette réponse, un Acteur de session s’est restauré depuis l’instantané doré, a exécuté l’appel au modèle et est retourné en instantané dans le stockage. Ouvrez View, puis Substrate, dans l’interface pour voir l’Acteur dans l’inventaire. Entre les demandes, il devrait rester à l’état Suspended. Ce seul mot est tout l’objet du système, rendu visible.

Vérification

Parcourez cette liste de contrôle avant de déclarer l’installation terminée :

1. kubectl get pods -n ate-system montre les pods Substrate à Running, avec seulement des tâches d’initialisation à Completed.
2. kubectl get secret kagent-openai -n kagent montre un secret avec une entrée de données.
3. kubectl get workerpools.ate.dev -A montre kagent-default.
4. L’agent hello-substrate atteint Ready et répond à l’invite de test dans l’interface.
5. La vue Substrate montre l’Acteur de session comme Suspended entre les demandes.

Si les cinq points tiennent, vous avez la boucle centrale qui fonctionne : l’état dans l’Acteur, la puissance de calcul dans le Travailleur et aucun Pod pris en otage par un clavardage inactif.

Dépannage

Prochaines étapes

Lisez la page de concepts Agent Substrate liée depuis le guide kagent pour le compte rendu complet des instantanés, des Acteurs et des WorkerPools. Regardez ensuite la voie AgentHarness dans la même documentation, qui place des agents de codage de longue durée sur Substrate. Les lecteurs qui font fonctionner Hermes se soucieront de cette voie en particulier, et notre tutoriel d’installation de Hermes Agent couvre le côté agent de ce jumelage.

Pour une lecture de production, comparez cette voie locale avec Agent Substrate sur GKE dans la documentation Google Cloud, et pesez gVisor contre les microVM Cloud Hypervisor comme frontière d’isolement. Google dit que Substrate accepte les conteneurs OCI standard et fonctionne avec les agents ADK et les installations de codage avec état. Testez cette affirmation avec un petit agent à vous avant de déplacer toute une flotte dessus.

Commencez petit, regardez l’état Suspended faire son travail et mettez le WorkerPool à l’échelle seulement quand vos sessions se chevauchent vraiment. La densité est une affirmation jusqu’à ce que votre propre trafic la prouve.

Étapes, versions et commandes vérifiés par rapport au guide Agent Substrate de kagent et à l’annonce 1.0 de Google Cloud le 2026-11-07. Cette procédure a été vérifiée par rapport à ces documents; elle n’a pas été exécutée de bout en bout sur une machine de test pour cet article.

Sources

• Agent Substrate guide and install commands: kagent documentation, Agent Substrate example
• 1.0, CNCF donation, Actors, Workers, Gateways and Google performance figures: Google Cloud Blog, Open infrastructure for autonomous agents comes to CNCF, 2026-11-05
• Diagram: Google Cloud Blog