STAROps Skill Integration

Method 1 (Recommended): Install via npx

The npx command is bundled with Node.js. Before installing, confirm that your local environment is ready:

node -v
npx -v

If the terminal reports that node or npx is not found, download and install Node.js from the Node.js website.

Run the following command to install the alibabacloud-starops-chat Skill:

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-starops-chat

After installation, confirm that the alibabacloud-starops-chat directory exists in your skills directory, then restart the Agent to activate the Skill.

Method 2: Install Manually

Download the alibabacloud-starops-chat package from the GitHub Release page. Extract the archive and copy the files to the skills directory of your Agent.

After copying, confirm that the alibabacloud-starops-chat directory exists in your skills directory, then restart the Agent to load the Skill.

The skills installation directories for common Agents are listed below.

Configure Credentials

The Skill resolves credentials through the Alibaba Cloud Credentials SDK default chain. No Skill-specific AccessKey variables are required. We recommend configuring credentials via the Alibaba Cloud CLI — the Skill reads them automatically.

aliyun configure

aliyun sts GetCallerIdentity

# AK mode (default)
aliyun configure --mode AK

# STS Token mode (temporary credentials)
aliyun configure --mode StsToken

# RAM Role (ECS instance role)
aliyun configure --mode EcsRamRole

# RAM Role ARN (role assumption)
aliyun configure --mode RamRoleArn

export ALIBABA_CLOUD_ACCESS_KEY_ID="<YOUR-ACCESS-KEY-ID>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<YOUR-ACCESS-KEY-SECRET>"

Scenario 1: Query APM Service Count

Prompt

How many APM services are in the current workspace?

Example Agent Output

The current workspace rca-benchmark contains 49 APM services.

Language distribution overview:

| Language                   | Count                                       |
|---------------------------|---------------------------------------------|
| Java                      | Most (ad, fraud-detection, accounting, ...) |
| Go                        | Several (product-catalog, checkout, ...)    |
| Node.js                   | Several (frontend, frontend-web, ...)       |
| .NET                      | Several (cart, accounting, ...)             |
| Python/Rust/PHP/Ruby/C++  | A few each                                  |

These services cover a complete e-commerce and financial scenario, including frontend, product-catalog, cart, checkout, payment, shipping, fraud-detection, and other core microservices.

Scenario 2: View Service Distribution by Language

Prompt

Show me services grouped by programming language in the current workspace.

Example Agent Output

The current workspace rca-benchmark contains 49 APM services, grouped by programming language:

| Language  | Count | Services                                                                  |
|----------|-------|---------------------------------------------------------------------------|
| Java     | 28    | ad, fraud-detection, inventory, loyalty, review, promotion, wishlist, ... |
| Golang   | 3     | product-catalog, flagd, checkout                                          |
| Node.js  | 3     | frontend, payment, loadgenerator                                          |
| .NET     | 2     | cart, accounting                                                          |
| Python   | 1     | recommendation                                                            |
| C++      | 1     | currency                                                                  |
| Rust     | 1     | shipping                                                                  |
| PHP      | 1     | quote                                                                     |
| Ruby     | 1     | email                                                                     |
| WebJS    | 1     | frontend-web                                                              |
| Unknown  | 2     | image-provider, frontend-proxy                                            |

A total of 10 programming languages are represented. Java services are the most common (28 services).

Scenario 3: Identify Service Error Root Cause

Prompt

Identify the root cause of errors in the inventory service.

Example Agent Output

## inventory Service 5xx Error Root Cause Analysis

### Conclusion

Root cause: The inventory service timed out (5 seconds) when calling the downstream notification service, causing cascading 5xx errors.

### Evidence Chain

#### 1. Trace Analysis

61 error traces were analyzed; all errors point to the same step:

| Error Span               | Service      | Duration   | Diagnosis      |
|-------------------------|--------------|------------|----------------|
| notification POST        | notification | ~5000ms    | error_and_slow |
| checkout orders publish  | checkout     | 1366-1927ms| slow           |

Call path:
frontend-proxy -> frontend -> checkout -> inventory -> notification (5s timeout)

#### 2. Related Alerts

- [Health Rule] latency_avg_threshold_critical (CRITICAL): checkout avg latency 3.6s
- frontend slow response (CRITICAL): frontend POST avg response time > 1000ms
- Container memory > 85% (CRITICAL): kafka container memory 88.52%

#### 3. notification Service Resource Status

| Metric               | Value  | Status  |
|--------------------|--------|---------|
| Pod status           | Running| Normal  |
| Memory usage/limit   | 66.6%  | Normal  |
| Memory usage/request | 133.2% | Exceeds |

### Possible Causes

1. Kafka memory pressure (88.52%) may be delaying message processing in notification.
2. notification memory exceeds 133% of request value — likely triggering GC under load.
3. Connection pool exhaustion between inventory and notification.

### Mitigation

1. Check notification service logs and Kafka cluster status.
2. Scale up notification (increase resources.limits.memory).
3. Add a circuit breaker and appropriate timeout in inventory to prevent cascading failures.

Scenario 4: Multi-turn Investigation

The STAROps Skill supports multi-turn interactions. By continuing within the same thread, you can progressively narrow the investigation scope.

Turn 1 Prompt

Identify the root cause of errors in the inventory service.

Turn 2 Prompt (same thread)

Based on the notification service timeout identified earlier, check its error logs for the last 30 minutes to determine whether the issue is internal to notification or caused by its downstream Kafka.

Turn 3 Prompt (continue drilling down)

Kafka container memory usage is at 88.52%. Provide scale-up recommendations and a temporary mitigation plan.

Reusing the same threadId allows the STAROps Agent to reason from previously accumulated tool call results (metrics, traces, logs) without repeating data scans.

Do I need to create a thread in the console before using the Skill?

No. The Skill automatically creates a session thread via CreateThread on first invocation and prints the STAROPS_URL. You can use this URL to navigate directly to the STAROps console and view all messages and tool call records for that thread.

How do I configure Alibaba Cloud account credentials?

The recommended approach is to run aliyun configure to configure credentials via the Alibaba Cloud CLI. The Skill automatically reads ~/.aliyun/config.json. For detailed steps, see "Configure Credentials" above.

If you use other credential sources, the priority order from highest to lowest is:

1. Environment variables: Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. Suitable for CI pipelines and temporary debugging.

2. Alibaba Cloud CLI configuration file (~/.aliyun/config.json): Recommended. Run aliyun configure to set it up.

3. STS Token: Temporary credentials injected by the platform. Suitable for CI pipelines and sandbox environments.

4. RAM Role: ECS or container workloads obtain credentials from instance metadata.

Can I use a custom endpoint?

Yes. Set the environment variable STAROPS_AGENT_ENDPOINT=<domain> to specify a dedicated or private network endpoint.

What should I do if the diagnostic results are not specific enough?

Consider the following improvements:

• Include key evidence in your prompt: service name, time range, TraceID, alert content, and error keywords.

• Verify that the workspace has APM, SLS, and UModel data sources connected. Missing data sources prevent the STAROps Agent from gathering evidence.

• Use --thread to continue multi-turn follow-up questions, allowing the STAROps Agent to drill down from existing conclusions instead of starting a new session.

• If STAROps returns (No assistant answer was returned.) or only a generic response, retry once using the same thread. If the issue persists, inform the user that STAROps did not return valid diagnostic data. Do not fabricate conclusions from prior knowledge.

HTTP 401 Unauthorized

The credential chain did not resolve an identity with STAROps permissions.

Resolution:

• Verify that the Credentials default chain can resolve at least one of: STS Token, RAM Role, CLI profile, or instance metadata.

• Verify that the resolved identity's RAM policy includes starops:CreateThread and starops:CreateChat.

• If using an STS Token, confirm it has not expired and the assumed role includes the required permissions.

• When authentication fails, the Skill terminates immediately without retrying. Grant the required permissions before reissuing the request.

HTTP 404 Not Found

The Digital Employee name, workspace, or UID does not match the actual resources.

Resolution: Verify that STAROPS_AGENT_EMPLOYEE, STAROPS_AGENT_WORKSPACE, and STAROPS_AGENT_UID all correspond to the same set of actual resources. The UID must be the primary account UID that owns the workspace.

ConfigError: Missing required STAROps environment variables

One or more of STAROPS_AGENT_EMPLOYEE, STAROPS_AGENT_WORKSPACE, or STAROPS_AGENT_UID is not set or is empty.

Resolution: Run the pre-flight check script in SKILL.md to confirm all variables are set, then retry.

CredentialError

The Alibaba Cloud Credentials SDK did not find any available credential source.

Resolution: Run aliyun configure to configure credentials via the Alibaba Cloud CLI — the Skill automatically reads ~/.aliyun/config.json. You can also provide credentials via environment variables, STS Token, or RAM Role. For local development where instance metadata is not needed, set export ALIBABA_CLOUD_ECS_METADATA_DISABLED=true to reduce timeout delays.

Idle Timeout Error

No SSE events were received within the --idle-timeout window, indicating the STAROps Agent may be stuck.

Resolution: Retry once using the same --thread. For complex tasks expected to be silent for extended periods, increase --idle-timeout accordingly.

ModuleNotFoundError

Python dependencies are not installed.

Resolution: Run pip3 install -r scripts/requirements.txt in the Skill root directory. The dependency file is in the scripts/ subdirectory, not the project root.

Prerequisites

• At least one Digital Employee has been created.

• Your account has been granted the cms:CreateDigitalEmployeeSkill permission.

Procedure

1. Log on to the STAROps console.

2. In the left navigation pane, click Digital Employees.

3. In the Digital Employees list, click the target Digital Employee to open its details page.

4. Click the Skill Management tab, then click Add Skill.

5. Configure the Skill parameters. Choose one of the following methods:

   • Direct entry: Fill in the following parameters in the console:

     Parameter	Description
     Skill name	The unique identifier for the Skill, used for internal system references and triggering. Use lowercase letters and hyphens, for example k8s-cluster-health-inspection.
     Display name	The name shown for the Skill in the console, for example "K8s Cluster Health Inspection."
     Description	A functional description that helps the Digital Employee determine when to activate this Skill. A more precise description improves automatic matching accuracy.
     Skill design	The execution instructions for the Skill — that is, the content of SKILL.md. Defines the specific steps and constraints the Digital Employee follows after loading this Skill.

   • Upload: Upload a local Skill folder. The folder must contain a SKILL.md file along with any required scripts and reference resources. After uploading, the system automatically parses the folder contents and switches to the direct entry view. Confirm the parameters and click Add Now to complete creation.

6. Click Add Now.