/alibabacloud-starops-chat

name: alibabacloud-starops-chat
description: |
  Alibaba Cloud STAROps Agent AIOps diagnostic skill. Use this skill to help users diagnose service errors, analyze root causes, query workspace/service topology, inspect APM metrics, and troubleshoot incidents through the STAROps Agent.
  Triggers: "排查根因", "根因分析", "服务报错", "服务异常", "APM 服务", "workspace 服务", "STAROps", "AIOps 诊断", "链路追踪", "告警分析".

Alibaba Cloud STAROps Agent

Call the Alibaba Cloud STAROps Agent through STAROps OpenAPI and receive a streaming diagnostic answer.

Scenario Description

Use this skill when the user wants to:

• Diagnose service errors or exceptions (root cause analysis)
• Query workspace topology, service lists, or service metrics
• Analyze APM traces, error rates, latency, or request volume
• Triage alerts or investigate incidents
• Ask questions about their STAROps workspace or services

Configuration

The script reads STAROps connection values from environment variables and optional JSON config files. Environment variables and command-line flags override config file values.

Config files are loaded in this order:

1. User config: `~/.starops/config.json` 2. Project config: `./.starops/config.json` (overrides user config) 3. Explicit config: `--config <path>` or `STAROPS_AGENT_CONFIG` (overrides user/project config)

The three required values (`employeeId`, `workspace`, `uid`) may come from either environment variables or config files.

| Variable | Required | Description | |----------|----------|-------------| | `STAROPS_AGENT_EMPLOYEE` | Yes, unless config provides `employeeId` | Digital Employee ID in STAROps (from console → Digital Employee list → ID column) | | `STAROPS_AGENT_WORKSPACE` | Yes, unless config provides `workspace` | Workspace identifier | | `STAROPS_AGENT_UID` | Yes, unless config provides `uid` | Alibaba Cloud account UID that owns the workspace | | `STAROPS_AGENT_ENDPOINT` | No | API endpoint (default: `starops.cn-beijing.aliyuncs.com`) | | `STAROPS_AGENT_PROJECT` | No | Optional STAROps project variable forwarded with each request. Overridden by `--project` | | `STAROPS_AGENT_TIMEOUT` | No | Default value for `--timeout` (CreateChat stream total timeout in seconds; default `1800`) | | `STAROPS_AGENT_IDLE_TIMEOUT` | No | Default value for `--idle-timeout` (max seconds to wait for the next SSE event; default `60`) | | `STAROPS_AGENT_CONFIG` | No | Path to an explicit JSON config file loaded after user/project config |

Minimal config file example:

{
  "employeeId": "<your-digital-employee-id>",
  "workspace": "<your-workspace-name>",
  "uid": "<your-alibaba-cloud-account-uid>"
}

Optional fields:

{
  "endpoint": "starops.cn-beijing.aliyuncs.com",
  "project": "optional-project",
  "timeout": 1800,
  "idleTimeout": 60
}

Config files use the exact key names shown above. Do not use alternate aliases such as `employee`, `digitalEmployeeId`, `workspaceName`, or `accountUid`.

**Pre-flight check — run this before invoking the script to confirm environment or config values are available:**

missing=""
[ -z "$STAROPS_AGENT_EMPLOYEE" ] && missing="$missing STAROPS_AGENT_EMPLOYEE"
[ -z "$STAROPS_AGENT_WORKSPACE" ] && missing="$missing STAROPS_AGENT_WORKSPACE"
[ -z "$STAROPS_AGENT_UID" ] && missing="$missing STAROPS_AGENT_UID"
config_file_found=""
[ -f ".starops/config.json" ] && config_file_found=1
[ -f "$HOME/.starops/config.json" ] && config_file_found=1
[ -n "$STAROPS_AGENT_CONFIG" ] && [ -f "$STAROPS_AGENT_CONFIG" ] && config_file_found=1
if [ -n "$missing" ] && [ -z "$config_file_found" ]; then
  echo "ERROR: Missing required environment variables:$missing and no STAROps config file was found" >&2
  exit 1
fi
echo "OK: STAROps configuration is available from environment variables or config file"

If any required value is still unavailable, ask the user to provide it. Never substitute placeholder strings like `example-employee`.

The STAROps console link uses the same digital employee ID as `assistantId`.

Credentials use the Alibaba Cloud Credentials default chain. Do not define skill-specific AccessKey variables; use standard Alibaba Cloud credential sources such as environment credentials (`ALIBABA_CLOUD_ACCESS_KEY_ID` / `ALIBABA_CLOUD_ACCESS_KEY_SECRET`), profiles, STS, RAM role, or instance metadata.

Invocation

**IMPORTANT: The `--pipe` flag is MANDATORY for all invocations.** It ensures structured output with THREAD ID, STAROPS_URL, and delimited answer blocks that downstream agents can reliably parse. Never omit `--pipe`.

Install dependencies and run from this skill's root directory:

pip3 install -r scripts/requirements.txt

# First call - creates a new thread automatically
python3 scripts/call_starops_agent.py --question "<complete user context>" --pipe

# First call with an explicit config file
python3 scripts/call_starops_agent.py --config ".starops/config.json" --question "<complete user context>" --pipe

# Follow-up calls - MUST reuse the thread ID from previous response
python3 scripts/call_starops_agent.py --thread "<thread_id>" --question "<follow-up question>" --pipe

**Thread Management:**

• Extract thread ID from output
• Use the printed `STAROPS_URL` when the user needs to inspect the same thread in the STAROps console
• Always pass `--thread "<id>"` for related follow-up questions to preserve context

Example workflow:

# Query 1: Creates new thread
$ python3 scripts/call_starops_agent.py --question "Query TOP 5 error applications" --pipe
THREAD: thread-abc123-xyz
STAROPS_URL: https://starops.console.aliyun.com/chat?threadId=thread-abc123-xyz&assistantId=apsara-ops
=== STAROPS ANSWER BEGIN ===
...

# Query 2: MUST reuse thread for context
$ python3 scripts/call_starops_agent.py --thread "thread-abc123-xyz" --question "Deep dive into notification app errors" --pipe

Command-Line Options

| Flag | Description | |------|-------------| | `--question <text>` | **Required.** Natural-language quest