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 or STAROPS_AGENT_CONFIG (overrides user/project config)

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

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

Behavioral Notes

1. STAROps Agent calls are long-running by design. A single CreateChat stream may start multiple internal diagnostic steps and take minutes; the default timeout is 30 minutes.
2. Provide complete context in one question: cloud account or workspace context, time range, service or application names, alert text, SLS project/logstore, UModel object, region, and what decision the user needs.
3. CRITICAL: Always reuse --thread for follow-ups in the same investigation. Starting a new thread discards all prior context and findings.
4. Use this skill for Agent reasoning and diagnosis, not direct resource management. For direct ECS, OSS, RDS, SLS, or RAM mutations, use the corresponding official CLI, SDK, or specialized skill.
5. MANDATORY: Always pass --pipe. Tool-call status and streaming diagnosis-report chunks are written to stderr, while stdout keeps the reusable thread ID and final answer easy to parse. Omitting --pipe will produce unstructured output that cannot be reliably evaluated.
6. If no SSE event arrives for a while, the script fails with a clear idle-timeout error instead of silently waiting for the full task timeout. Increase --idle-timeout only when the investigation is expected to be quiet for long periods.
7. Output integrity rule: Your final report MUST be based on the actual content returned between === STAROPS ANSWER BEGIN === and === STAROPS ANSWER END ===. Specifically:
• Quote or paraphrase concrete data points from the STAROps response (HTTP status codes, service names, error paths, metrics).
• Do NOT infer or fabricate diagnostic conclusions that are not supported by the STAROps output.
• If the STAROps answer is empty ((No assistant answer was returned.)), incomplete, or only contains generic text, retry once using the same --thread. If the retry still yields no actionable data, report honestly: "STAROps did not return actionable diagnostic data. Confirm that the workspace contains relevant services and data for the requested time range."
• Never substitute your own prior knowledge for missing STAROps evidence. For example, do not claim "database connection pool exhaustion" if STAROps did not mention it.

Observability

All STAROps OpenAPI HTTP requests must use this User-Agent template declaration:

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

For this skill, the concrete template is:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}

Generate exactly one session-id per skill invocation as a 32-char hex value. If SKILL_SESSION_ID is already set, reuse that value after validating it is 32 hex characters; otherwise generate uuid4().hex, set SKILL_SESSION_ID, and reuse it for all outbound calls. The same session-id must be consistent across CLI/SDK/Terraform and direct HTTP requests made during the invocation, including both CreateThread and CreateChat; do not generate a new session-id per request. The Python script sets the HTTP User-Agent header to AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}.

Troubleshooting

When the script exits with an error, check the following in order:

1. HTTP 401 Unauthorized — The credential chain did not resolve to a valid identity with STAROps permissions. Verify that ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET (or STS / RAM role) are set and that the identity has starops:CreateThread and starops:CreateChat permissions. See references/ram-policies.md.
2. HTTP 404 Not Found — The Digital Employee ID (STAROPS_AGENT_EMPLOYEE) or workspace (STAROPS_AGENT_WORKSPACE) does not exist, or the UID (STAROPS_AGENT_UID) does not match the owning account. Double-check all three environment variables.
3. ConfigError: Missing required STAROps configuration values — One or more of employeeId, workspace, or uid is missing from both environment variables and config files.
4. CredentialError — The Alibaba Cloud Credentials SDK could not find any valid credential source. Ensure at least one credential provider is configured (environment variables, ~/.aliyun/config.json, STS, RAM role, or instance metadata).
5. Idle timeout — No SSE event was received within --idle-timeout seconds (default 60). The STAROps Agent may be stalled. Retry with the same --thread if a THREAD line was printed, or increase --idle-timeout for investigations expected to be quiet.
6. Stream interruption / network error — The HTTPS connection was reset or timed out. Retry the same request with --thread to resume context.
7. ModuleNotFoundError — Python dependency not installed. Run pip3 install -r scripts/requirements.txt before invoking the script.

API Surface

This skill directly calls STAROps OpenAPI:

• CreateThread: POST /digitalEmployee/{employeeId}/thread
• CreateChat: POST /chat

See references/api-reference.md and references/ram-policies.md.