Notes pratiques : Démystifier le réseau agentiel : Échelle des agents IA et des LLM

Ce guide reconstitue le parcours allant des matières premières à un système fonctionnel pour : Démystifier le réseau agentiel : Échelle des agents IA et des LLM sur Kubernetes. L’accent est mis sur des étapes opérationnelles, des vérifications explicites, ainsi que du code que vous pouvez intégrer directement dans un dépôt sans devoir deviner l’intention derrière lui. Pour l’étape d’aperçu, définissez les entrées, le responsable de l’étape et les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans avoir à deviner l’état caché. Documentez conjointement le parcours normal et celui de récupération. Les tentatives de répétition, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.

Les principaux goulets d’étranglement de l’IA agente en production

Lorsque vous travaillez sur l’étape « The Core Bottlenecks », notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables à des scripts volumineux. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus complexe et embrouillé. Mémorisez les instructions du système stables ainsi que les schémas des outils. Envoyer à nouveau un préambule identique est une cause fréquente de gaspillage de ressources.

Découvrez le Stack : la feuille de route du Agentic Mesh

Lorsque vous travaillez sur l’étape « Meet the Stack », notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’honnêteté des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez les terminations partielles silencieuses. Cachez les instructions du système stable ainsi que les schémas des outils. L’envoi répété d’un préambule identique est une source fréquente de problèmes.

1. kagent : L’environnement d’exécution de l’agent

Lors du travail sur l’étape 1 kagent The Agent, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Mémorisez les instructions du système stables ainsi que les schémas des outils. Envoyer à nouveau un préambule identique est une cause fréquente de gaspillage. Lors du travail sur l’étape 1 kagent The Agent, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.

2. agentgateway : Le policier du trafic

The 2 agentgateway The Traffic stage fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt qu’un processus embrouillé. Fixez un budget de tokens par tour et par session. Les outils agents élargissent lourdement le contexte ; des plafonds stricts empêchent que les démonstrations ne se transforment en factures inattendues.

3. llm-d : Le diviseur de charge

La phase Workload des 3 llm-d fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de rollback avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des critères de succès et refusez les complétions partielles silencieuses. Fixez un budget de tokens par tour et par session. Les outils agents élargissent lourdement le contexte ; des plafonds stricts empêchent que les démos ne se transforment en factures inattendues.

4. vLLM : La puissance des GPU

The 4 vLLM : l’étape GPU fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés. Fixez un budget en tokens par tour et par session : les outils agents élargissent de manière importante le contexte ; des plafonds stricts empêchent que les démonstrations ne se transforment en factures inattendues. The 4 vLLM : l’étape GPU fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et celui de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non traités font partie intégrante du produit, et non d’une mise en forme ultérieure.

1. Architecture du système

Pour l’étape d’architecture système, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Préférez des sorties structurées avec validation de schéma à du texte libre lorsque l’étape suivante consiste en du code ou une appel d’outil.

Dans les détails : Traitement d’une demande dans le Mesh

Pour l’étape de traitement interne, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des vérifications de succès et refusez les terminations partielles silencieuses. Préférez des sorties structurées avec validation de schéma plutôt que du texte libre lorsque l’étape suivante consiste en du code ou une appel à outil.

2. Installer les contrôleurs et CRDs

Pour l’étape 2 Install Controllers CRDs, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Préférez des sorties structurées avec validation de schéma plutôt que du texte libre lorsque l’étape suivante consiste en du code ou une appel à outil. Pour l’étape 2 Install Controllers CRDs, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives de répétition, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une amélioration ultérieure.

# 1. Install Kubernetes Gateway API & Inference Extension CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.0/standard-install.yaml
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api-inference-extension/releases/download/v0.1.0/manifests.yaml

# 2. Add Helm Registries
helm repo add agentgateway oci://cr.agentgateway.dev/charts
helm repo add kagent https://charts.kagent.dev
helm repo update

# 3. Install agentgateway (Control & Data Plane)
helm upgrade -i agentgateway-crds agentgateway/agentgateway-crds -n agentgateway-system --create-namespace
helm upgrade -i agentgateway agentgateway/agentgateway -n agentgateway-system

# 4. Install kagent (Agent Runtime)
helm upgrade -i kagent kagent/kagent -n kagent-system --create-namespace

3. Déployer une infrastructure d’inférence GPU (vLLM & llm-d)

Lors de la phase 3 de déploiement d’une infrastructure d’inférence GPU, notez d’abord les exigences : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Mémorisez les instructions système stables ainsi que les schémas des outils. Envoyer à nouveau un préambule identique est une cause fréquente de gaspillage.

Réinitialiser et déchiffrer le déploiement (vllm-infrastructure.yaml)

Lors du traitement de l’étape Prefill Decode Deployment vllm-infrastructure, notez d’abord les conditions contractuelles : entrées requises, signal de succès, et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’honnêteté des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez toute exécution partielle silencieuse. Cachez les instructions système stables ainsi que les schémas des outils. L’envoi répété d’un préambule identique est une cause fréquente de problèmes.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-prefill
  namespace: llm-serving
  labels:
    app: vllm-prefill
spec:
  replicas: 1
  selector:
    matchLabels:
      app: vllm-prefill
  template:
    metadata:
      labels:
        app: vllm-prefill
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
        - "--model"
        - "meta-llama/Meta-Llama-3-8B-Instruct"
        - "--experimental-prefill-only" # Optimization: Dedicated Prefill role
        - "--gpu-memory-utilization"
        - "0.90"
        - "--port"
        - "8000"
        ports:
        - containerPort: 8000
          name: http
        resources:
          limits:
            nvidia.com/gpu: "1" # Schedule on premium compute node
            cpu: "4"
            memory: 16Gi
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: model-cache
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: vllm-model-cache-pvc
      - name: dshm
        emptyDir:
          medium: Memory
          sizeLimit: 4Gi
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-decode
  namespace: llm-serving
  labels:
    app: vllm-decode
spec:
  replicas: 3 # Scale out dynamically based on load
  selector:
    matchLabels:
      app: vllm-decode
  template:
    metadata:
      labels:
        app: vllm-decode
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
        - "--model"
        - "meta-llama/Meta-Llama-3-8B-Instruct"
        - "--experimental-decode-only" # Optimization: Dedicated token generator role
        - "--gpu-memory-utilization"
        - "0.90"
        - "--port"
        - "8000"
        ports:
        - containerPort: 8000
          name: http
        resources:
          limits:
            nvidia.com/gpu: "1" # Schedule on low-cost L4/A10G nodes
            cpu: "4"
            memory: 16Gi
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: model-cache
        - mountPath: /dev/shm
          name: dshm
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: vllm-model-cache-pvc
      - name: dshm
        emptyDir:
          medium: Memory
          sizeLimit: 4Gi

Configuration llm-d (llmd-routing.yaml)

Lors du travail sur l’étape yaml llmd-routing de la configuration llm-d, notez d’abord les exigences : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le système passe de l’environnement de démonstration à des environnements partagés. Mémorisez les instructions système stables et les schémas des outils. Envoyer à nouveau un préambule identique est une cause fréquente de gaspillage. Lors du travail sur l’étape yaml llmd-routing de la configuration llm-d, notez d’abord les exigences : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Documentez conjointement le parcours normal et les procédures de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non traités font partie intégrante du produit, et non d’améliorations apportées ultérieurement.

apiVersion: inference.networking.x-k8s.io/v1alpha1
kind: InferencePool
metadata:
  name: llama3-decode-pool
  namespace: llm-serving
spec:
  selector:
    matchLabels:
      app: vllm-decode
  targetPort: 8000
---
apiVersion: inference.networking.x-k8s.io/v1alpha1
kind: InferenceObjective
metadata:
  name: llama3-serving-objective
  namespace: llm-serving
spec:
  modelName: "meta-llama/Meta-Llama-3-8B-Instruct"
  prefillService:
    name: vllm-prefill
    port: 8000
  decodePool:
    name: llama3-decode-pool

4. Configurer agentgateway

La phase 4 de configuration d’agentgateway fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et les notes de réversion avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité et non vers un processus embrouillé. Fixez des limites de tokens par tour et par session. Les outils agents élargissent lourdement le contexte ; des plafonds stricts empêchent que les démonstrations ne se transforment en factures inattendues.

Définition du gateway (agent-gateway.yaml)

L’étape yaml agent-gateway de la définition Gateway fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définites des vérifications de succès et refusez toute complétion partielle silencieuse. Fixez un budget en tokens par tour et par session. Les outils agents élargissent l’contexte de manière importante ; des plafonds stricts empêchent que les démos ne se transforment en factures inattendues.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: agent-gateway
  namespace: agentgateway-system
spec:
  gatewayClassName: agentgateway
  listeners:
  - name: http
    protocol: HTTP
    port: 8080
    allowedRoutes:
      namespaces:
        from: All
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: llm-inference-route
  namespace: llm-serving
spec:
  parentRefs:
  - name: agent-gateway
    namespace: agentgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1/chat/completions
    backendRefs:
    - name: llama3-serving-objective
      kind: InferenceObjective
      group: inference.networking.x-k8s.io
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp-tools-route
  namespace: agent-tools
spec:
  parentRefs:
  - name: agent-gateway
    namespace: agentgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /mcp/tools
    backendRefs:
    - name: mcp-tool-server-service
      port: 50051

5. Déployer le pod d’agent AI kagent

L’étape 5 Déployer kagent AI fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démo aux environnements partagés.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kagent-orchestrator
  namespace: kagent-system
spec:
  replicas: 2
  selector:
    matchLabels:
      app: kagent-orchestrator
  template:
    metadata:
      labels:
        app: kagent-orchestrator
    spec:
      containers:
      - name: agent-runtime
        image: kagent/runtime:latest
        env:
        # Route all model and tool API calls through agentgateway
        - name: OPENAI_API_BASE
          value: "http://agent-gateway.agentgateway-system.svc.cluster.local:8080/v1"
        - name: MCP_SERVER_URL
          value: "http://agent-gateway.agentgateway-system.svc.cluster.local:8080/mcp/tools"
        resources:
          limits:
            cpu: "2"
            memory: 4Gi
          requests:
            cpu: "1"
            memory: 2Gi

6. Liste de contrôle pour l’optimisation et le réglage

Liste de contrôle opérationnelle