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 question to send to STAROps Agent.
--thread <id>	Existing STAROps thread ID. Required for follow-up questions to preserve investigation context.
--pipe	Mandatory for agent invocations. Emit structured output with THREAD, STAROPS_URL, and === STAROPS ANSWER BEGIN/END === delimiters for reliable parsing.
--json	Emit machine-readable JSONL events. Mutually exclusive with --pipe. Do not use for agent invocations — --pipe is the supported agent format.
--config <path>	Optional JSON config file. Loaded after ~/.starops/config.json and ./.starops/config.json.
--project <name>	Optional STAROps project variable. Overrides STAROPS_AGENT_PROJECT.
--timeout <seconds>	Total CreateChat stream timeout in seconds. Overrides STAROPS_AGENT_TIMEOUT (default 1800).
--idle-timeout <seconds>	Maximum seconds to wait for the next SSE event before failing. Overrides STAROPS_AGENT_IDLE_TIMEOUT (default 60).

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.