AgentLoop:Integração de aplicações com AI Agent

Após a integração, é possível visualizar os seguintes dados de monitoramento no console:

• Aplicações server-side: Dados de APM incluindo topologia da aplicação, chamadas de API, transações anômalas e transações lentas

• Aplicações de IA: Métricas de observabilidade de IA incluindo latência de chamadas LLM, uso de tokens, rastros de Agent e chamadas de ferramentas

Cenários aplicáveis

O AI Agent seleciona automaticamente o probe e o caminho de integração apropriados com base no tipo de aplicação:

Como funciona a integração via AI Agent

A Skill alibabacloud-agentloop-management encapsula o processo de integração da CLI do AgentLoop (aliyun cms2) em um fluxo de trabalho estruturado executável por AI Agents. As capacidades principais incluem:

• Orientado por linguagem natural — Descreva seus requisitos de integração em uma única frase, sem precisar memorizar comandos e parâmetros da CLI.

• Ciente do cenário — Seleciona automaticamente a solução de probe com base no tipo de aplicação, linguagem e ambiente de implantação (ECS, ACK/ACS).

• Orquestração automatizada — Conclui a confirmação do Workspace, inicialização do APM, obtenção de credenciais, registro de serviço e configuração do probe.

• Seguro e controlável — Executa confirmação em duas fases para operações de alteração, como Patch Deployment e modificações de parâmetros de inicialização. A execução ocorre somente após revisão do usuário.

O fluxo de trabalho típico é o seguinte:

1. Descreva os requisitos de integração (Workspace, tipo de aplicação, linguagem/framework, nome da aplicação e ambiente de implantação). Se não for fornecido um Workspace correspondente ao formato agentloop-{32-character code}, o Agent solicitará essa informação proativamente.

2. O Agent verifica o ambiente da CLI e as credenciais, e inicializa a infraestrutura de APM.

3. Um plano de execução é gerado pelo Agent, exibindo comandos, escopo de impacto e métodos de rollback.

4. Após sua confirmação, o Agent realiza a injeção do probe ou alterações nos parâmetros de inicialização.

5. Os resultados da integração são verificados pelo Agent, que então orienta você a visualizar os dados de monitoramento no console.

Pré-requisitos

Etapa 1: Instalar e configurar o ambiente da CLI

Caso ainda não tenha instalado a Alibaba Cloud CLI, consulte Instalar a Alibaba Cloud CLI para concluir a instalação.

Verifique se a versão da sua CLI é 3.3.15 ou superior e se o plugin cms2 está disponível:

# Verify CLI version >= 3.3.15
aliyun version

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

Se o comando cms2 não estiver disponível, atualize o plugin:

aliyun plugin update

Configure as credenciais de acesso. Se obter um AccessKey for inconveniente, recomendamos usar OAuth. Para mais informações, consulte Credenciais OAuth. Se você utilizar um AccessKey, execute o seguinte comando:

aliyun configure

Etapa 2: Instalar a Skill alibabacloud-agentloop-management

1. Abra a página do marketplace de Skills: alibabacloud-agentloop-management.

2. Siga as instruções na página para instalar a Skill no Cursor, Claude Code ou QoderWork.

3. Após a instalação, reinicie o assistente de IA ou confirme na conversa que a Skill foi carregada.

A tabela abaixo lista exemplos de gatilhos em linguagem natural:

Etapa 3: Iniciar a integração usando linguagem natural

Ao descrever seus requisitos de integração, inclua as informações a seguir. O Agent detectará automaticamente ou solicitará quaisquer detalhes ausentes.

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

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

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

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

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

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

Etapa 4: Confirmar o plano de execução e concluir a integração

O AI Agent utiliza um protocolo de confirmação em duas fases para todas as operações de alteração:

Comandos de somente leitura (get, list) e inicializações idempotentes (apm configuration create) não exigem confirmação — o Agent os executa diretamente.

Após sua confirmação, o Agent realiza a injeção do probe ou alterações nos parâmetros de inicialização com base no seu cenário de implantação. Todos os cambios planejados e etapas de rollback são listados pelo Agent no plano de execução antes da implementação. Para detalhes sobre os comandos típicos que o Agent executa para cada cenário, consulte Referência de execução de integração: K8s (ACK/ACS).

Depois que a integração for concluída, o Agent solicitará que você aguarde de 2 a 3 minutos e, em seguida, verifique os dados de monitoramento no console.

Etapa 5: Verificar os resultados da integração

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

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"

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

Visualizar dados de monitoramento no console

1. Faça login no console do AgentLoop.

2. Selecione o Workspace alvo.

3. No painel de navegação à esquerda, escolha All Features > Application Observability > Application Monitoring.

4. Clique no nome da aplicação alvo para visualizar os dados de monitoramento:

   • Aplicações server-side: Topologia da aplicação, chamadas de API (QPS/RT/taxa de erro), transações anômalas, transações lentas

   • Aplicações de IA: Chamadas LLM (nome do modelo, latência, taxa de sucesso), estatísticas de tokens, rastros de Agent, topologia de Tool Call, rastreamento de exceções

Referência de execução de integração: K8s (ACK/ACS)

Esta seção e as duas seguintes descrevem os comandos e operações típicos que o AI Agent executa automaticamente durante a integração. Estes passos são mostrados apenas para referência — o Agent cuida deles para você.

O exemplo a seguir utiliza o cenário K8s. O fluxo de execução do Agent é o mesmo para aplicações server-side Java e aplicações de IA Python, diferindo apenas no identificador de linguagem nos Labels.

(1) Obter informações da conta e do cluster

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

(2) Inicializar a infraestrutura de APM e obter credenciais

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

O authToken retornado é a LicenseKey, e publicDomain / privateDomain são os Endpoints para envio de dados.

(3) Registrar o serviço da aplicação

# 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

(4) Verificar o status do componente ack-onepilot

kubectl get pods -n ack-onepilot

(5) Aplicar Patch no Deployment para injetar o probe

Aplicar patch em um Deployment para adicionar Labels aciona reinicializações contínuas de Pods (rolling restarts).

Aplicação server-side Java:

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

Aplicação de IA Python (LangChain / DashScope):

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

Os Labels devem ser adicionados no nível spec.template.metadata.labels (Pod Template), e não no nível metadata.labels do Deployment. Os seguintes Labels são obrigatórios:

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

Os exemplos a seguir mostram manifests YAML completos de Deployment para referência.

Referência completa de YAML (aplicação server-side Java):

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

Referência completa de YAML (aplicação de IA Python):

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

(6) Verificar atualização contínua (rolling update)

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

Referência de execução de integração: ECS

Em cenários ECS, o Agent executa as seguintes operações na instância alvo através do Cloud Assistant ou SSH:

1. Baixe e extraia o probe da linguagem correspondente (como AliyunJavaAgent ou aliyun-bootstrap).

2. Configure as propriedades do probe (LicenseKey, AppName, Workspace).

3. Modifique os parâmetros de inicialização da aplicação ou variáveis de ambiente.

4. Reinicie a aplicação e verifique o carregamento do probe.

Exemplo de parâmetro de inicialização JVM para aplicação Java:

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

Referência de execução de integração: Dify e OTel

O Dify possui suporte nativo a OpenTelemetry. O Agent orienta você a configurar o OTel Exporter para enviar dados de Trace ao Endpoint de APM do AgentLoop (LicenseKey e Endpoint são obtidos via apm configuration get), sem necessidade de injeção através do ack-onepilot.

Soluções de probe suportadas

FAQ

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

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