AgentLoop:Integración de aplicaciones con AI Agent

# Verify CLI version >= 3.3.15
aliyun version

# Verify the cms2 plugin is available
aliyun cms2 --help

aliyun plugin update

aliyun configure

Ejemplos para aplicaciones de servidor

Aplicación Java en K8s:

Onboard the order-service deployment in the default namespace of my ACK cluster to AgentLoop APM, language is Java, Workspace is agentloop-2694ecf8****************1f84542d

Aplicación Java en ECS:

Help me onboard the Spring Boot application order-api on ECS instance i-bp1xxxxxxxxxx to APM monitoring, Workspace is agentloop-2694ecf8****************1f84542d

Aplicación Golang en K8s:

Help me onboard the Golang microservice payment-service in my ACK cluster to AgentLoop application monitoring, Workspace is agentloop-2694ecf8****************1f84542d

Ejemplos para aplicaciones de IA

Aplicación LangChain en K8s:

Help me onboard the LangChain application customer-support-agent in my ACK cluster to AgentLoop monitoring, Workspace is agentloop-2694ecf8****************1f84542d

Aplicación DashScope en ECS:

Help me onboard the DashScope conversational application qa-bot on ECS to AgentLoop AI observability monitoring, Workspace is agentloop-2694ecf8****************1f84542d

Despliegue autoalojado de Dify:

My Dify is deployed on K8s, help me configure OpenTelemetry reporting to AgentLoop, Workspace is agentloop-2694ecf8****************1f84542d

Verificar mediante el CLI

Reemplace cn-hangzhou en el siguiente comando por el ID real de su región:

aliyun cms2 apm service list \
    --workspace agentloop-2694ecf8****************1f84542d \
    --service-name <application-name> \
    --region cn-hangzhou

Criterio de éxito: la aplicación aparece en la lista de servicios con el estado Running.

Verificar mediante K8s (escenarios de contenedores)

kubectl rollout status deployment/<deployment-name> -n <namespace>

kubectl get pods -n <namespace> -l app=<app-label> \
  -o jsonpath='{range .items[*]}{.metadata.name}: initContainers={.spec.initContainers[*].name}{"\n"}{end}'

kubectl logs -n <namespace> -l app=<app-label> --tail=30 | grep -i "arms\|OneAgent\|bootstrap\|agent"

Verificar mediante ECS

# Java application: confirm the ARMS Agent is loaded in the process
ps aux | grep "aliyun-java-agent" | grep -v grep

aliyun sts get-caller-identity --force -o json
aliyun cs describe-clusters

aliyun cms2 apm configuration create \
    --workspace agentloop-2694ecf8****************1f84542d \
    --region cn-hangzhou

aliyun cms2 apm configuration get \
    --workspace agentloop-2694ecf8****************1f84542d \
    --region cn-hangzhou -o json

# Server-side Java application example
aliyun cms2 apm service create \
    --workspace agentloop-2694ecf8****************1f84542d \
    --region cn-hangzhou \
    --body '{"serviceName":"order-service","serviceType":"TRACE","attributes":"{\"language\":\"java\"}"}' \
    < /dev/null

# AI Python application example
aliyun cms2 apm service create \
    --workspace agentloop-2694ecf8****************1f84542d \
    --region cn-hangzhou \
    --body '{"serviceName":"customer-support-agent","serviceType":"TRACE","attributes":"{\"language\":\"python\"}"}' \
    < /dev/null

kubectl get pods -n ack-onepilot

kubectl patch deployment order-service -n default \
    --type=strategic -p '{
      "spec":{"template":{"metadata":{"labels":{
        "aliyun.com/app-language":"java",
        "armsPilotAutoEnable":"on",
        "armsPilotCreateAppName":"order-service",
        "armsPilotAppWorkspace":"agentloop-2694ecf8****************1f84542d"
      }}}}}
    }'

kubectl patch deployment customer-support-agent -n default \
    --type=strategic -p '{
      "spec":{"template":{"metadata":{"labels":{
        "aliyun.com/app-language":"python",
        "armsPilotAutoEnable":"on",
        "armsPilotCreateAppName":"customer-support-agent",
        "armsPilotAppWorkspace":"agentloop-2694ecf8****************1f84542d"
      }}}}}
    }'

labels:
  armsPilotAutoEnable: "on"
  armsPilotCreateAppName: "<application-name>"
  armsPilotAppWorkspace: "<workspace-name>"
  aliyun.com/app-language: "<language>"   # e.g., java, golang, python

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "order-service"
        armsPilotAppWorkspace: "agentloop-2694ecf8****************1f84542d"
        aliyun.com/app-language: java
    spec:
      containers:
        - name: order-service
          image: registry.example.com/order-service:latest
          ports:
            - containerPort: 8080

apiVersion: apps/v1
kind: Deployment
metadata:
  name: customer-support-agent
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
      app: customer-support-agent
  template:
    metadata:
      labels:
        app: customer-support-agent
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "customer-support-agent"
        armsPilotAppWorkspace: "agentloop-2694ecf8****************1f84542d"
        aliyun.com/app-language: python
    spec:
      containers:
        - name: customer-support-agent
          image: registry.example.com/customer-support-agent:latest
          ports:
            - containerPort: 8000

kubectl rollout status deployment/<deployment-name> -n <namespace> --timeout=120s

java -javaagent:/opt/arms/AliyunJavaAgent/aliyun-java-agent.jar \
  -Darms.licenseKey=<LicenseKey> \
  -Darms.appName=order-api \
  -Darms.workspace=agentloop-2694ecf8****************1f84542d \
  -jar app.jar

Aplicaciones de servidor

El AI Agent selecciona automáticamente uno de los siguientes métodos de integración según el lenguaje de la aplicación y el entorno de despliegue:

Para aplicaciones en Java, Golang y Python dentro de escenarios de K8s, se prefiere la inyección no intrusiva de ack-onepilot, ya que no requiere modificar el código de la aplicación ni los Dockerfiles. En escenarios de ECS, la integración suele completarse modificando los parámetros de inicio de la JVM (Java) o instalando paquetes de sonda (Golang/Python).

Aplicaciones de IA

Los frameworks de IA basados en Python dentro de escenarios de K8s suelen utilizar ack-onepilot para inyectar automáticamente la sonda aliyun-bootstrap. En aplicaciones con compatibilidad nativa para OpenTelemetry, como Dify, el Agent le guía para configurar el OTel Exporter hacia el Endpoint de AgentLoop, sin inyección mediante ack-onepilot.

El comando cms2 no está disponible

Causa: la versión del CLI es demasiado antigua o el plugin cms2 no está instalado.

Solución:

aliyun upgrade -y
aliyun plugin update
aliyun cms2 --help

Los Pods no tienen la sonda inyectada en escenarios de K8s

Causa: ack-onepilot no está instalado, la versión es demasiado antigua o la autorización de ARMS no se completó.

Solución:

1. Compruebe que la versión de ack-onepilot sea ≥ 5.1.0.

2. Revise la salida del comando kubectl get pods -n ack-onepilot.

3. Confirme que el clúster tenga configurado el ARMS Addon Token o la autorización AK/SK.

4. Confirme que aliyun.com/app-language coincida con el lenguaje real de la aplicación.

5. Confirme que los Labels se agregaron en el nivel Pod Template.

Los Pods entran en CrashLoopBackOff después de la integración

Causa: la inyección de la sonda falló o la sonda no es compatible con el entorno de ejecución de la aplicación.

Solución:

1. Revise los registros del initContainer para diagnosticar los errores de inyección.

2. Confirme que aliyun.com/app-language coincida con el lenguaje real de la aplicación.

3. Verifique el proceso correctamente en un entorno de pruebas y, después, vuelva a ejecutar la integración.

La sonda se carga, pero no aparecen datos en la consola

Causa: la configuración de LicenseKey, Workspace o Endpoint es incorrecta, o existen problemas de conectividad de red.

Solución:

1. Ejecute aliyun cms2 apm configuration get para verificar las credenciales.

2. Confirme que el valor del Label armsPilotAppWorkspace coincida con el nombre del Workspace.

3. Compruebe la conectividad de red desde el clúster o la instancia ECS hasta el Endpoint de APM. Use privateDomain para redes internas de VPC.

4. Genere una solicitud de negocio o una llamada a LLM, espere entre 2 y 3 minutos y luego revise la consola.

No hay datos de llamadas a LLM tras integrar la aplicación de IA

Causa: la sonda no se cargó correctamente o el framework de IA no es reconocido por la sonda.

Solución:

1. Confirme que ack-onepilot haya inyectado el initContainer en el Pod.

2. Confirme que la aplicación utilice un framework de IA en Python compatible con aliyun-bootstrap (como LangChain o DashScope).

3. Genere una llamada a LLM, espere entre 2 y 3 minutos y luego revise la consola.

4. Revise los registros de la aplicación para buscar mensajes que confirmen la inicialización correcta de la sonda.

Cómo revertir la integración

Escenario de K8s: elimine los Labels relacionados con ARMS y los Pods se reiniciarán de forma progresiva sin la inyección de la sonda.

kubectl patch deployment <deployment-name> -n <namespace> \
    --type json \
    --patch '[
      {"op": "remove", "path": "/spec/template/metadata/labels/armsPilotAutoEnable"},
      {"op": "remove", "path": "/spec/template/metadata/labels/armsPilotCreateAppName"},
      {"op": "remove", "path": "/spec/template/metadata/labels/armsPilotAppWorkspace"}
    ]'

Escenario de ECS: quite -javaagent y las configuraciones relacionadas con -Darms.* de los parámetros de inicio, y reinicie la aplicación.