STAROps:Integração de Skill do STAROps

Método 1 (Recomendado): Instalar via npx

O comando npx vem integrado ao Node.js. Antes de instalar, confirme que seu ambiente local está pronto:

node -v
npx -v

Se o terminal informar que node ou npx não foi encontrado, baixe e instale o Node.js no site do Node.js.

Execute o seguinte comando para instalar a Skill alibabacloud-starops-chat:

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

Após a instalação, confirme que o diretório alibabacloud-starops-chat existe no seu diretório de skills e reinicie o Agent para ativar a Skill.

Método 2: Instalar manualmente

Baixe o pacote alibabacloud-starops-chat na página de Release do GitHub. Extraia o arquivo compactado e copie os arquivos para o diretório de skills do seu Agent.

Após a cópia, confirme que o diretório alibabacloud-starops-chat existe no seu diretório de skills e reinicie o Agent para carregar a Skill.

Os diretórios de instalação de skills para Agents comuns estão listados abaixo.

export STAROPS_AGENT_EMPLOYEE="<Digital Employee name>"
export STAROPS_AGENT_WORKSPACE="<workspace identifier>"
export STAROPS_AGENT_UID="<Alibaba Cloud account UID>"

Configurar credenciais

A Skill resolve credenciais por meio da cadeia padrão do Alibaba Cloud Credentials SDK. Nenhuma variável de AccessKey específica da Skill é necessária. Recomendamos configurar as credenciais via CLI do Alibaba Cloud — a Skill as lê automaticamente.

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

Cenário 1: Consultar contagem de serviços de APM

Prompt

How many APM services are in the current workspace?

Exemplo de saída do Agent

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.

Cenário 2: Visualizar distribuição de serviços por linguagem

Prompt

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

Exemplo de saída do Agent

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).

Cenário 3: Identificar causa raiz de erro de serviço

Prompt

Identify the root cause of errors in the inventory service.

Exemplo de saída do Agent

## 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.

Cenário 4: Investigação em múltiplos turnos

A Skill do STAROps suporta interações em múltiplos turnos. Ao continuar no mesmo thread, você pode refinar progressivamente o escopo da investigação.

Prompt do turno 1

Identify the root cause of errors in the inventory service.

Prompt do turno 2 (mesmo 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.

Prompt do turno 3 (continuar a investigação detalhada)

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

Reutilizar o mesmo threadId permite que o Agent do STAROps faça raciocínios com base nos resultados de chamadas de ferramentas acumulados anteriormente (métricas, traces, logs) sem repetir varreduras de dados.

Preciso criar um thread no console antes de usar a Skill?

Não. A Skill cria automaticamente um thread de sessão via CreateThread na primeira invocação e imprime a STAROPS_URL. Você pode usar essa URL para navegar diretamente ao console do STAROps e visualizar todas as mensagens e registros de chamadas de ferramentas desse thread.

Como configuro as credenciais da conta Alibaba Cloud?

A abordagem recomendada é executar aliyun configure para configurar credenciais via CLI do Alibaba Cloud. A Skill lê automaticamente o arquivo ~/.aliyun/config.json. Para etapas detalhadas, consulte "Configurar credenciais" acima.

Se você usar outras fontes de credenciais, a ordem de prioridade da mais alta para a mais baixa é:

1. Variáveis de ambiente: Defina ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET. Adequado para pipelines de CI e depuração temporária.

2. Arquivo de configuração da CLI do Alibaba Cloud (~/.aliyun/config.json): Recomendado. Execute aliyun configure para configurá-lo.

3. STS Token: Credenciais temporárias injetadas pela plataforma. Adequado para pipelines de CI e ambientes sandbox.

4. RAM Role: Cargas de trabalho ECS ou container obtêm credenciais dos metadados da instância.

Posso usar um endpoint personalizado?

Sim. Defina a variável de ambiente STAROPS_AGENT_ENDPOINT=<domain> para especificar um endpoint dedicado ou de rede privada.

O que devo fazer se os resultados do diagnóstico não forem específicos o suficiente?

Considere as seguintes melhorias:

• Inclua evidências-chave no seu prompt: nome do serviço, intervalo de tempo, TraceID, conteúdo de alertas e palavras-chave de erro.

• Verifique se o workspace tem fontes de dados APM, SLS e UModel conectadas. Fontes de dados ausentes impedem o Agent do STAROps de reunir evidências.

• Use --thread para continuar com perguntas de acompanhamento em múltiplos turnos, permitindo que o Agent do STAROps investigue detalhadamente a partir de conclusões existentes em vez de iniciar uma nova sessão.

• Se o STAROps retornar (No assistant answer was returned.) ou apenas uma resposta genérica, tente novamente uma vez usando o mesmo thread. Se o problema persistir, informe ao usuário que o STAROps não retornou dados de diagnóstico válidos. Não fabrique conclusões a partir de conhecimento prévio.

http 401 Unauthorized

A cadeia de credenciais não resolveu uma identidade com permissões do STAROps.

Resolução:

• Verifique se a cadeia padrão do Credentials consegue resolver pelo menos um destes: STS Token, RAM Role, perfil da CLI ou metadados de instância.

• Verifique se a política do RAM da identidade resolvida inclui starops:CreateThread e starops:CreateChat.

• Se estiver usando um STS Token, confirme que ele não expirou e que a função assumida inclui as permissões necessárias.

• Quando a autenticação falha, a Skill termina imediatamente sem tentar novamente. Conceda as permissões necessárias antes de reenviar a requisição.

http 404 Not Found

O nome do Digital Employee, o workspace ou o UID não correspondem aos recursos reais.

Resolução: Verifique se STAROPS_AGENT_EMPLOYEE, STAROPS_AGENT_WORKSPACE e STAROPS_AGENT_UID correspondem todos ao mesmo conjunto de recursos reais. O UID deve ser o UID da conta primária proprietária do workspace.

ConfigError: Missing required STAROps environment variables

Uma ou mais das variáveis STAROPS_AGENT_EMPLOYEE, STAROPS_AGENT_WORKSPACE ou STAROPS_AGENT_UID não estão definidas ou estão vazias.

Resolução: Execute o script de verificação prévia em SKILL.md para confirmar que todas as variáveis estão definidas e tente novamente.

CredentialError

O Alibaba Cloud Credentials SDK não encontrou nenhuma source de credencial disponível.

Resolução: Execute aliyun configure para configurar credenciais via CLI do Alibaba Cloud — a Skill lê automaticamente o arquivo ~/.aliyun/config.json. Você também pode fornecer credenciais via variáveis de ambiente, STS Token ou RAM Role. Para desenvolvimento local onde metadados de instância não são necessários, defina export ALIBABA_CLOUD_ECS_METADATA_DISABLED=true para reduzir atrasos por timeout.

Erro de Idle Timeout

Nenhum evento SSE foi recebido dentro da janela --idle-timeout, indicando que o Agent do STAROps pode estar travado.

Resolução: Tente novamente uma vez usando o mesmo --thread. Para tarefas complexas que devem permanecer silenciosas por períodos prolongados, aumente o valor de --idle-timeout adequadamente.

ModuleNotFoundError

As dependências do Python não estão instaladas.

Resolução: Execute pip3 install -r scripts/requirements.txt no diretório raiz da Skill. O arquivo de dependências está no subdiretório scripts/, não na raiz do projeto.

Pré-requisitos

• Pelo menos um Digital Employee foi criado.

• Sua conta recebeu a permissão cms:CreateDigitalEmployeeSkill.

Procedimento

1. Faça logon no console do STAROps.

2. No painel de navegação à esquerda, clique em Digital Employees.

3. Na lista de Digital Employees, clique no Digital Employee de destino para abrir sua página de detalhes.

4. Clique na aba Skill Management e depois clique em Add Skill.

5. Configure os parâmetros da Skill. Escolha um dos seguintes métodos:

   • Entrada direta: Preencha os seguintes parâmetros no console:

     Parâmetro	Descrição
     Skill name	O identificador exclusivo da Skill, usado para referências internas do sistema e acionamento. Use letras minúsculas e hifens, por exemplo k8s-cluster-health-inspection.
     Display name	O nome exibido para a Skill no console, por exemplo "K8s Cluster Health Inspection".
     Description	Uma descrição funcional que ajuda o Digital Employee a determinar quando ativar esta Skill. Uma descrição mais precisa melhora a precisão da correspondência automática.
     Skill design	As instruções de execução da Skill — ou seja, o conteúdo do SKILL.md. Define as etapas e restrições específicas que o Digital Employee segue após carregar esta Skill.

   • Upload: Faça upload de uma pasta local de Skill. A pasta deve conter um arquivo SKILL.md junto com quaisquer scripts e recursos de referência necessários. Após o upload, o sistema analisa automaticamente o conteúdo da pasta e muda para a visualização de entrada direta. Confirme os parâmetros e clique em Add Now para concluir a criação.

6. Clique em Add Now.