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

Como funciona

O comando agentscope deploy knative encapsula o processo complexo de containerizar uma aplicação de agente e implantá-la em um cluster. O fluxo de trabalho principal é:

1. Empacota a aplicação: empacota o código da aplicação de agente Python especificada, suas dependências (requirements.txt) e variáveis de ambiente.

2. Crie a imagem: crie uma imagem de contêiner que inclui a aplicação de agente no seu ambiente Docker local, com base em uma imagem base especificada.

3. Envia a imagem: envia a imagem criada para um registro de imagens de contêiner especificado, como o Container Registry (ACR).

4. Implanta o service: gera e aplica um manifesto de Knative Service (ksvc) no cluster de destino. O Knative usa esse manifesto para criar um Deployment e Pods, além de configurar automaticamente roteamento de rede, balanceamento de carga e políticas de Auto Scaling.

Antes de começar

• Você já implantou os componentes do Knative no cluster.

• Você já implantou o Knative no cluster ACS.

• O Docker está instalado e em execução na sua máquina local para criar imagens de contêiner.

• Instale o AgentScope Runtime usando o comando pip.

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

Etapa 1: Crie um projeto de agente

Se você não tiver uma aplicação de agente, use a estrutura de arquivos e o código de exemplo a seguir.

1. Crie a estrutura de diretórios do projeto:

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

2. Escreva o código do agente no arquivo app_agent.py.

   O código a seguir cria um agente que usa um modelo Qwen e oferece suporte à execução de código e conversas de múltiplas rodadas.

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

Etapa 2: Implante a aplicação de agente

Use o comando agentscope deploy para implantar sua aplicação de agente local como um service do Knative.

Etapa 3: Acesse o agente implantado

1. Obtenha o gateway de acesso.

   1. Na página ACK Clusters, clique em no nome do seu cluster. No painel de navegação à esquerda, clique em em Applications > Knative.

   2. Faça login no console do ACS. No painel de navegação à esquerda, clique em em Clusters.

   3. Na página Clusters, clique em no nome do cluster de destino. No painel de navegação à esquerda, escolha Applications > Knative.

   4. Na página Services ou Component management, obtenha o Gateway.

      O endereço IP do Access Gateway (por exemplo, 120.xxx.159) encontra-se na parte inferior da página. Antes de acessar o service, resolva o domínio do service para este endereço IP.

2. Envie uma solicitação para o service do agente usando o comando curl.

   Substitua 115.29.xxx.xxx pelo endereço IP do gateway de acesso e substitua o valor de Host pela URL de acesso obtida 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. Visualize o resultado. A resposta transmite em fluxo o processo de raciocínio do agente e a saída final.

Etapa 4: Observe o Auto Scaling

• Redução de escala (Scale-down): após um período de inatividade, o Knative reduz automaticamente os Pods do service para zero a fim de economizar recursos. É possível observar as alterações nos Pods executando o seguinte comando:

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

  Alternativamente, na página do Knative, clique em em Services e, em seguida, clique em no nome do service. Você pode visualizar o status de execução dos Pods para a revisão atual na parte inferior da página.

  Na aba Revision information, a coluna Ready/requested Pods da revisão atual mostra 0/0, confirmando que os Pods foram reduzidos a zero.

• Aumento de escala (Scale-up): quando uma nova solicitação chega, o Knative inicia automaticamente novos Pods em segundos para processar a requisição.

Recomendações para produção

• Persistência de estado: o InMemoryStateService e o InMemorySessionHistoryService mencionados no exemplo perdem todo o estado e histórico de conversas quando um Pod reinicia, tornando-os inadequados para produção. Em ambientes produtivos, migre para uma implementação suportada por Redis ou outra solução de armazenamento persistente.

• Gerenciamento de segredos: evite passar informações sensíveis como API_KEY diretamente na linha de comando ou codificá-las rigidamente na aplicação. Utilize Kubernetes Secrets e monte-os como variáveis de ambiente no contêiner através da configuração do Knative Service.

• Planejamento de recursos: com base na carga de trabalho esperada, realize testes de estresse e configure parâmetros como --cpu-request, --cpu-limit, --memory-request e --memory-limit para garantir desempenho e estabilidade do service.

• Melhoria da observabilidade: configure coleta de logs (como Log Service) e monitoramento com alertas (como Application Real-Time Monitoring Service (ARMS)) para solucionar problemas e acompanhar a integridade do service.

Operações relacionadas

• Atualização do agente: após modificar o código, execute novamente o comando agentscope deploy knative com uma nova tag de imagem (por exemplo, --image-tag v1.1) para realizar uma atualização contínua.

• Desinstalação do agente:

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

  Esta operação exclui apenas o service no Kubernetes. Ela não remove a imagem de contêiner enviada para o registro de contêiner.