Container Service for Kubernetes:Déployer une application agent en tant que service Knative

Fonctionnement

La commande agentscope deploy knative automatise la conteneurisation d'une application agent et son déploiement dans un cluster. Le flux de travail principal est le suivant :

1. Empaquetage de l'application : cette étape regroupe le code Python de l'application agent spécifié, ses dépendances (fichier requirements.txt) et les variables d'environnement.

2. Construction de l'image : elle génère une image de conteneur incluant l'application agent dans votre environnement Docker local, à partir d'une image de base spécifiée.

3. Push de l'image : elle transfère l'image construite vers un registre d'images de conteneurs spécifié, tel que Container Registry (ACR).

4. Déploiement du service : elle génère et applique un manifeste de service Knative (ksvc) dans le cluster cible. Knative utilise ensuite ce manifeste pour créer un Deployment et des Pods, et configure automatiquement le routage réseau, l'équilibrage de charge ainsi que les politiques de mise à l'échelle automatique.

Prérequis

• Vous avez déployé les composants Knative dans le cluster.

• Vous avez déployé Knative dans le cluster ACS.

• Docker est installé et en cours d'exécution sur votre machine locale pour la construction des images de conteneurs.

• Vous avez installé AgentScope Runtime à l'aide de la commande pip.

  # Basic installation
  pip install agentscope-runtime>=1.1.0
  # Dependencies for Kubernetes deployment
  pip install "agentscope-runtime[ext]>=1.1.0"

Étape 1 : Créer un projet agent

Si vous ne disposez pas d'application agent, utilisez la structure de fichiers et le code d'exemple suivants.

1. Créez la structure de répertoires du projet :

   my-agent-project/
   ├── app_agent.py          # Main file for the agent application
   ├── requirements.txt      # Python dependencies (optional)
   └── .env                  # Environment variables (optional)

2. Rédigez le code de l'agent dans le fichier app_agent.py.

   Le code ci-dessous crée un agent qui utilise un modèle Qwen et prend en charge l'exécution de code ainsi que les conversations multi-tours.

   # -*- coding: utf-8 -*-
   import os
   from contextlib import asynccontextmanager
   from fastapi import FastAPI
   from agentscope.agent import ReActAgent
   from agentscope.formatter import DashScopeChatFormatter
   from agentscope.model import DashScopeChatModel
   from agentscope.pipeline import stream_printing_messages
   from agentscope.tool import Toolkit, execute_python_code
   from agentscope.memory import InMemoryMemory
   from agentscope.session import JSONSession
   from agentscope_runtime.engine.app import AgentApp
   from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
   @asynccontextmanager
   async def lifespan(app: FastAPI):
       """Initialize the service."""
       app.state.session = JSONSession(
           save_dir="./",  # Directory to save all session files
       )
       try:
           yield
       finally:
           print("AgentApp is shutting down...")
   # Create an AgentApp
   agent_app = AgentApp(
       app_name="MyAssistant",
       app_description="A helpful assistant agent",
       lifespan=lifespan,
   )
   @agent_app.query(framework="agentscope")
   async def query_func(
       self,
       msgs,
       request: AgentRequest = None,
       **kwargs,
   ):
       """Process user queries."""
       session_id = request.session_id
       user_id = request.user_id
       # Create toolkit with Python execution
       toolkit = Toolkit()
       toolkit.register_tool_function(execute_python_code)
       # Create agent
       agent = ReActAgent(
           name="MyAssistant",
           model=DashScopeChatModel(
               "qwen-turbo",
               api_key=os.getenv("DASHSCOPE_API_KEY"),
               enable_thinking=True,
               stream=True,
           ),
           sys_prompt="You're a helpful assistant.",
           toolkit=toolkit,
           memory=InMemoryMemory(),
           formatter=DashScopeChatFormatter(),
       )
       agent.set_console_output_enabled(False)
       await agent_app.state.session.load_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
       async for msg, last in stream_printing_messages(
           agents=[agent],
           coroutine_task=agent(msgs),
       ):
           yield msg, last
       await agent_app.state.session.save_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
   if __name__ == "__main__":
       agent_app.run()

Étape 2 : Déployer l'application agent

Utilisez la commande agentscope deploy pour déployer votre application agent locale en tant que service Knative.

Étape 3 : Accéder à l'agent déployé

1. Obtenez la passerelle d'accès.

   1. Sur la page ACK Clusters, cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, cliquez sur Applications > Knative.

   2. Connectez-vous à la console ACS. Dans le volet de navigation de gauche, cliquez sur Clusters.

   3. Sur la page Clusters, cliquez sur le nom du cluster cible. Dans le volet de navigation de gauche, choisissez Applications > Knative.

   4. Sur la page Services ou Component management, obtenez la Gateway.

      L'adresse IP de la Access Gateway (par exemple 120.xxx.159) se trouve en bas de la page. Avant d'accéder au service, vous devez résoudre le domaine du service vers cette adresse IP.

2. Envoyez une requête au service agent à l'aide de la commande curl.

   Remplacez 115.29.xxx.xxx par l'adresse IP de la passerelle d'accès et remplacez la valeur Host par l'URL d'accès obtenue précédemment.

   curl -i -X POST "http://115.29.xxx.xxx:80/process" \
     -H "Content-Type: application/json" \
     -H "Host: agent-03e*****.default.example.com" \
     -d '{
       "input": [
         {
           "role": "user",
           "content": [
             {
               "type": "text",
               "text": "Hello, how are you?"
             }
           ]
         }
       ],
       "session_id": "123"
     }'

3. Consultez le résultat. La réponse diffuse en continu le processus de réflexion de l'agent ainsi que la sortie finale.

Étape 4 : Observer la mise à l'échelle automatique

• Réduction (scale-down) : après une période d'inactivité, Knative réduit automatiquement le nombre de Pods du service à zéro pour économiser des ressources. Vous pouvez observer les changements concernant les Pods en exécutant la commande suivante :

  # Continuously watch the Pods in the specified namespace
  kubectl get pods -n default -w

  Vous pouvez également, sur la page Knative, cliquer sur Services, puis sur le nom du service. Vous pourrez consulter l'état d'exécution des Pods pour la révision actuelle en bas de la page.

  Dans l'onglet Revision information, la colonne Ready/requested Pods pour la révision actuelle affiche 0/0, ce qui confirme que les Pods ont été réduits à zéro.

• Montée en charge (scale-up) : lorsqu'une nouvelle requête arrive, Knative démarre automatiquement de nouveaux Pods en quelques secondes pour traiter la requête.

Recommandations pour la production

• Persistance de l'état : les services InMemoryStateService et InMemorySessionHistoryService mentionnés dans l'exemple perdent tout état et tout historique de conversation lors du redémarrage d'un Pod, ce qui les rend inadaptés à la production. Pour les déploiements en production, privilégiez une implémentation reposant sur Redis ou une autre solution de stockage persistant.

• Gestion des secrets : ne transmettez pas d'informations sensibles telles que API_KEY directement via la ligne de commande et ne les codez pas en dur dans votre application. Utilisez les Secrets Kubernetes et montez-les en tant que variables d'environnement dans le conteneur via la configuration du service Knative.

• Planification des ressources : en fonction de votre charge de travail prévue, effectuez des tests de charge et configurez des paramètres tels que --cpu-request, --cpu-limit, --memory-request et --memory-limit afin de garantir les performances et la stabilité du service.

• Amélioration de l'observabilité : configurez la collecte des journaux (par exemple Log Service) et la surveillance avec alertes (par exemple Application Real-Time Monitoring Service (ARMS)) pour résoudre les problèmes et surveiller l'état de santé du service.

Opérations connexes

• Mise à jour de l'agent : après avoir modifié le code, réexécutez la commande agentscope deploy knative avec un nouveau tag d'image (par exemple --image-tag v1.1) pour effectuer une mise à jour progressive (rolling update).

• Désinstallation de l'agent :

  # Replace <resource-name> and <namespace> with your actual values
  kubectl delete ksvc <resource-name> -n <namespace>

  Cette opération supprime uniquement le service dans Kubernetes. Elle ne supprime pas l'image de conteneur qui a été poussée vers le registre de conteneurs.