Container Service for Kubernetes:Deploy an agent application as a Knative service

Funcionamiento

El comando agentscope deploy knative simplifica el proceso complejo de empaquetar una aplicación de agente en un contenedor y desplegarla en un clúster. El flujo de trabajo principal es el siguiente:

1. Empaqueta la aplicación: agrupa el código de la aplicación de agente en Python especificada, sus dependencias (requirements.txt) y las variables de entorno.

2. Compila la imagen: construye una imagen de contenedor que incluye la aplicación de agente en su entorno local de Docker, a partir de una imagen base especificada.

3. Envía la imagen: sube la imagen compilada a un registro de imágenes de contenedor especificado, como Container Registry (ACR).

4. Despliega el servicio: genera y aplica un manifiesto de Knative Service (ksvc) en el clúster de destino. Después, Knative usa este manifiesto para crear un Deployment y Pods, y configura automáticamente el enrutamiento de red, el balanceo de carga y las políticas de auto scaling.

Antes de empezar

• Tiene deployed Knative components en el clúster.

• Tiene deployed Knative en el clúster ACS.

• Docker está instalado y en ejecución en su computadora local para compilar imágenes de contenedor.

• Instaló AgentScope Runtime con el comando pip.

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

Paso 1: Crear un proyecto de agente

Si no cuenta con una aplicación de agente, utilice la siguiente estructura de archivos y código de ejemplo.

1. Cree la estructura de directorios del proyecto:

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

2. Escriba el código del agente en el archivo app_agent.py.

   A continuación se muestra un código que crea un agente con un modelo Qwen, compatible con la ejecución de código y las conversaciones de múltiples turnos.

   # -*- 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()

Paso 2: Desplegar la aplicación de agente

Utilice el comando agentscope deploy para desplegar su aplicación de agente local como un servicio de Knative.

Paso 3: Acceder al agente desplegado

1. Obtenga la puerta de enlace de acceso.

   1. En la página ACK Clusters, haga clic en el nombre de su clúster. En el panel de navegación izquierdo, haga clic en Applications > Knative.

   2. Inicie sesión en la consola de ACS. En el panel de navegación izquierdo, haga clic en Clusters.

   3. En la página Clusters, haga clic en el nombre del clúster de destino. En el panel de navegación izquierdo, elija Applications > Knative.

   4. En la página Services o Component management, obtenga la Gateway.

      La dirección IP de Access Gateway (por ejemplo, 120.xxx.159) se encuentra en la parte inferior de la página. Antes de acceder al servicio, debe resolver el dominio del servicio hacia esta dirección IP.

2. Envíe una solicitud al servicio del agente con el comando curl.

   Sustituya 115.29.xxx.xxx por la dirección IP de la puerta de enlace de acceso y cambie el valor de Host por la URL de acceso que obtuvo anteriormente.

   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. Consulte el resultado. La respuesta transmite de forma continua el proceso de razonamiento del agente y la salida final.

Paso 4: Observar el auto scaling

• Reducción de escala: tras un periodo de inactividad, Knative reduce automáticamente a cero los Pods del servicio para ahorrar recursos. Compruebe los cambios en los Pods con el siguiente comando:

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

  Como alternativa, en la página de Knative, haga clic en Services y luego haga clic en el nombre del servicio. En la parte inferior de la página podrá consultar el estado de ejecución de los Pods de la revisión actual.

  En la pestaña Revision information, la columna Ready/requested Pods de la revisión actual muestra 0/0, lo cual confirma que los Pods se redujeron a cero.

• Aumento de escala: cuando llega una nueva solicitud, Knative inicia automáticamente nuevos Pods en cuestión de segundos para procesarla.

Recomendaciones para producción

• Persista el estado: los servicios InMemoryStateService y InMemorySessionHistoryService mencionados en el ejemplo pierden todo el estado y el historial de conversaciones cuando se reinicia un Pod, por lo que no son adecuados para producción. En los despliegues productivos, cambie a una implementación respaldada por Redis u otra solución de almacenamiento persistente.

• Gestione los secretos: no pase información confidencial como API_KEY directamente en la línea de comandos ni la incluya de forma fija en su aplicación. Utilice Kubernetes Secrets y móntelos como variables de entorno en el contenedor mediante la configuración del Knative Service.

• Planifique los recursos: según la carga de trabajo esperada, ejecute pruebas de estrés y configure parámetros como --cpu-request, --cpu-limit, --memory-request y --memory-limit para garantizar el rendimiento y la estabilidad del servicio.

• Mejore la observability: configure la recopilación de registros (como Log Service) y el monitoreo con alertas (como Application Real-Time Monitoring Service (ARMS)) para solucionar problemas y supervisar el estado del servicio.

Operaciones relacionadas

• Actualizar el agente: después de modificar el código, vuelva a ejecutar el comando agentscope deploy knative con una nueva etiqueta de imagen (por ejemplo, --image-tag v1.1) para aplicar una actualización continua.

• Desinstalar el agente:

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

  Esta operación solo elimina el servicio en Kubernetes. No elimina la imagen de contenedor que se envió al registro de contenedores.