AgentLoop:AI Agent ile uygulamaları entegre etme

# Verify CLI version >= 3.3.15
aliyun version

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

aliyun plugin update

aliyun configure

Sunucu tarafı uygulama örnekleri

K8s'deki Java uygulaması:

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

ECS'deki Java uygulaması:

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

K8s'deki Golang uygulaması:

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

AI uygulama örnekleri

K8s'deki LangChain uygulaması:

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

ECS'deki DashScope uygulaması:

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

Dify kendi kendine barındırılan dağıtım:

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

CLI üzerinden doğrulama

Aşağıdaki komutta cn-hangzhou değerini gerçek bölge ID'nizle değiştirin:

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

Başarı kriteri: Uygulama, Running durumuyla hizmet listesinde görünür.

K8s (konteyner senaryoları) üzerinden doğrulama

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"

ECS üzerinden doğrulama

# 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

Sunucu tarafı uygulamalar

AI Agent, uygulama diline ve dağıtım ortamına göre aşağıdaki entegrasyon yöntemlerinden birini otomatik olarak seçer:

K8s senaryolarındaki Java, Golang ve Python uygulamaları için ack-onepilot müdahalesiz enjeksiyon tercih edilir; bu yaklaşım uygulama kodunda veya Dockerfile'larda değişiklik gerektirmez. ECS senaryolarında entegrasyon genellikle JVM başlangıç parametrelerini değiştirerek (Java) veya prob paketlerini yükleyerek (Golang/Python) tamamlanır.

AI uygulamaları

K8s senaryolarındaki Python tabanlı AI çerçeveleri genellikle aliyun-bootstrap probunu otomatik olarak enjekte etmek için ack-onepilot kullanır. Dify gibi yerleşik OpenTelemetry desteğine sahip uygulamalar için Agent, ack-onepilot aracılığıyla enjeksiyon yapmadan OTel Exporter'ı AgentLoop Uç Noktasına işaret edecek şekilde yapılandırmanıza rehberlik eder.

cms2 komutu kullanılamıyor

Neden: CLI sürümü çok eski veya cms2 eklentisi yüklü değil.

Çözüm:

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

K8s senaryolarında Pod'lara prob enjekte edilmiyor

Neden: ack-onepilot yüklü değil, sürüm çok eski veya ARMS yetkilendirmesi tamamlanmamış.

Çözüm:

1. ack-onepilot sürümünün ≥ 5.1.0 olduğunu doğrulayın.

2. kubectl get pods -n ack-onepilot çıktısını kontrol edin.

3. Küme ARMS Addon Token veya AK/SK yetkilendirmesinin yapılandırıldığını onaylayın.

4. aliyun.com/app-language değerinin gerçek uygulama diliyle eşleştiğini onaylayın.

5. Etiketlerin Pod Şablonu düzeyinde eklendiğini onaylayın.

Entegrasyon sonrası Pod'lar CrashLoopBackOff durumuna giriyor

Neden: Prob enjeksiyonu başarısız oldu veya prob uygulama çalışma zamanı ortamıyla uyumsuz.

Çözüm:

1. Enjeksiyon hatalarını gidermek için initContainer günlüklerini kontrol edin.

2. aliyun.com/app-language değerinin gerçek uygulama diliyle eşleştiğini onaylayın.

3. Bir test ortamında başarılı bir şekilde doğrulayın ve ardından entegrasyon işlemini yeniden yürütün.

Prob yüklendi ancak konsolda veri görünmüyor

Neden: LicenseKey, Workspace veya Endpoint yapılandırması yanlış veya ağ bağlantısı sorunları var.

Çözüm:

1. Kimlik bilgilerini doğrulamak için aliyun cms2 apm configuration get komutunu çalıştırın.

2. armsPilotAppWorkspace Etiketi değerinin Workspace adıyla eşleştiğini onaylayın.

3. Kümeden veya ECS örneğinden APM Uç Noktasına ağ bağlantısını kontrol edin. VPC iç ağları için privateDomain kullanın.

4. Bir iş isteği veya LLM çağrısı tetikleyin, 2–3 dakika bekleyin ve ardından konsolu kontrol edin.

AI uygulama entegrasyonu sonrası LLM çağrı verisi yok

Neden: Prob doğru yüklenmemiş veya prob AI çerçevesini tanımıyor.

Çözüm:

1. ack-onepilot'un initContainer'ı Pod'a enjekte ettiğini onaylayın.

2. Uygulamanın aliyun-bootstrap tarafından desteklenen bir Python AI çerçevesi (LangChain veya DashScope gibi) kullandığını onaylayın.

3. Bir LLM çağrısı tetikleyin, 2–3 dakika bekleyin ve ardından konsolu kontrol edin.

4. Prob başlatma başarı mesajları için uygulama günlüklerini kontrol edin.

Entegrasyon nasıl geri alınır

K8s senaryosu: ARMS ile ilgili Etiketleri kaldırın; Pod'lar prob enjeksiyonu olmadan kademeli olarak yeniden başlatılır.

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"}
    ]'

ECS senaryosu: Başlangıç parametrelerinden -javaagent ve ilgili -Darms.* yapılandırmalarını kaldırın ve uygulamayı yeniden başlatın.