AgentLoop:Onboard applications with AI Agent

After onboarding, you can view the following monitoring data in the console:

• Server-side applications: APM data including application topology, API calls, abnormal transactions, and slow transactions

• AI applications: AI observability metrics including LLM call latency, token usage, Agent traces, and tool calls

Applicable scenarios

The AI Agent automatically selects the appropriate probe and onboarding path based on the application type:

How AI Agent onboarding works

The alibabacloud-agentloop-management Skill encapsulates the AgentLoop CLI (aliyun cms2) onboarding process into a structured workflow executable by AI Agents. Core capabilities include:

• Natural language driven — Describe your onboarding requirements in one sentence without memorizing CLI commands and parameters.

• Scenario-aware — Automatically selects the probe solution based on application type, language, and deployment environment (ECS, ACK/ACS).

• Automated orchestration — Completes Workspace confirmation, APM initialization, credential retrieval, service registration, and probe configuration.

• Safe and controllable — Executes two-phase confirmation for change operations such as Patch Deployment and startup parameter modifications. Executes only after user review.

The typical workflow is as follows:

1. You describe the onboarding requirements (Workspace, application type, language/framework, application name, and deployment environment). If a Workspace matching the agentloop-{32-character code} format is not provided, the Agent proactively asks for it.

2. The Agent checks the CLI environment and credentials, and initializes the APM infrastructure.

3. The Agent generates an execution plan showing commands, impact scope, and rollback methods.

4. After you confirm, the Agent performs probe injection or startup parameter changes.

5. The Agent verifies the onboarding results and guides you to view monitoring data in the console.

Prerequisites

Step 1: Install and configure the CLI environment

If you have not installed Alibaba Cloud CLI, see Install Alibaba Cloud CLI to complete the installation.

Verify that your CLI version is 3.3.15 or later and that the cms2 plugin is available:

# Verify CLI version >= 3.3.15
aliyun version

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

If the cms2 command is not available, update the plugin:

aliyun plugin update

Configure access credentials. If obtaining an AccessKey is inconvenient, we recommend using OAuth. For more information, see OAuth credentials. If you use an AccessKey, run the following command:

aliyun configure

Step 2: Install the alibabacloud-agentloop-management Skill

1. Open the Skill marketplace page: alibabacloud-agentloop-management.

2. Follow the on-page instructions to install the Skill into Cursor, Claude Code, or QoderWork.

3. After installation, restart the AI assistant or confirm in the conversation that the Skill is loaded.

The following table lists natural language trigger examples:

Step 3: Initiate onboarding using natural language

When describing your onboarding requirements, include the following information. The Agent automatically detects or asks for any missing details.

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

Step 4: Confirm the execution plan and complete onboarding

The AI Agent uses a two-phase confirmation protocol for all change operations:

Read-only commands (get, list) and idempotent initializations (apm configuration create) do not require confirmation — the Agent executes them directly.

After you confirm, the Agent performs probe injection or startup parameter changes based on your deployment scenario. The Agent lists all planned changes and rollback steps in the execution plan before execution. For details about the typical commands the Agent runs for each scenario, see Onboarding execution reference: K8s (ACK/ACS).

After onboarding is complete, the Agent prompts you to wait 2–3 minutes and then check the monitoring data in the console.

Step 5: Verify onboarding results

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

View monitoring data in the console

1. Log on to the AgentLoop console.

2. Select the target Workspace.

3. In the left-side navigation pane, choose All Features > Application Observability > Application Monitoring.

4. Click the target application name to view monitoring data:

   • Server-side applications: Application topology, API calls (QPS/RT/error rate), abnormal transactions, slow transactions

   • AI applications: LLM calls (model name, latency, success rate), token statistics, Agent traces, Tool Call topology, exception tracing

Onboarding execution reference: K8s (ACK/ACS)

This section and the following two sections describe the typical commands and operations the AI Agent executes automatically during onboarding. These steps are shown for reference — the Agent handles them for you.

The following uses the K8s scenario as an example. The Agent's execution flow is the same for Java server-side and Python AI applications, differing only in the language identifier in Labels.

(1) Retrieve account and cluster information

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

(2) Initialize APM infrastructure and retrieve credentials

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

The returned authToken is the LicenseKey, and publicDomain / privateDomain are the data reporting Endpoints.

(3) Register the application service

# 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) Check ack-onepilot component status

kubectl get pods -n ack-onepilot

(5) Patch Deployment to inject the probe

Patching a Deployment to add Labels triggers Pod rolling restarts.

Java server-side application:

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

Python AI application (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"
      }}}}}
    }'

Labels must be added at the spec.template.metadata.labels level (Pod Template), not at the Deployment's metadata.labels level. The following Labels are required:

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

The following examples show complete Deployment YAML manifests for reference.

Complete YAML reference (Java server-side application):

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

Complete YAML reference (Python AI application):

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) Verify rolling update

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

Onboarding execution reference: ECS

In ECS scenarios, the Agent executes the following operations on the target instance through Cloud Assistant or SSH:

1. Download and extract the corresponding language probe (such as AliyunJavaAgent or aliyun-bootstrap).

2. Configure probe properties (LicenseKey, AppName, Workspace).

3. Modify application startup parameters or environment variables.

4. Restart the application and verify probe loading.

Java application JVM startup parameter example:

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

Onboarding execution reference: Dify and OTel

Dify has built-in OpenTelemetry support. The Agent guides you to configure the OTel Exporter to report Trace data to the AgentLoop APM Endpoint (LicenseKey and Endpoint are obtained from apm configuration get), without injection through ack-onepilot.

Supported probe solutions

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