alibabacloud-oos-chatops-agent

Alibaba Cloud OOS ChatOps Agent

Send natural-language questions to the OOS ChatOps Agent and receive streaming operational answers via SSE.

When to Use

• Query cloud resources (ECS, RDS, VPC, SLB, security groups, etc.)
• Execute resource operations (start, stop, restart, scale)
• View monitoring data, billing, or resource health
• Batch O&M tasks through natural language
• General Alibaba Cloud resource management questions

Configuration

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

Pre-flight check:

missing=""
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_ID" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_ID"
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_SECRET"
if [ -n "$missing" ]; then echo "ERROR: Missing credentials:$missing" >&2; exit 1; fi
echo "OK: Credentials configured"

Credential security constraints:

• NEVER run cat ~/.aliyun/config.json, env, printenv, echo $ALIBABA_CLOUD_*, or any command that prints full credential values to stdout/stderr/logs.
• When debugging credential issues, only output masked hints (e.g., LTAI5t****). Full AK/SK/Token values must NEVER appear in any output.
• If credentials are unavailable, ask the user to configure the standard Alibaba Cloud credential chain. Never substitute placeholders.

Invocation

[ABSOLUTE RULE] Tool whitelist: The ONLY permitted tool for all cloud resource queries, O&M operations, and resource management tasks is scripts/call_oos_chatops_agent.py. For any scenario involving Alibaba Cloud resources — including but not limited to ECS, RDS, SLB, VPC, security groups, monitoring, billing, and batch operations — this script is the mandatory and exclusive entry point. If aliyun CLI, direct SDK calls, curl, or any other API tool is detected, the task is immediately treated as FAILED.

`--pipe` is mandatory for all agent invocations.

pip3 install -r scripts/requirements.txt

# First call (auto-creates conversation)
python3 scripts/call_oos_chatops_agent.py -q "<user question>" --pipe

# Follow-up (MUST reuse ConversationId)
python3 scripts/call_oos_chatops_agent.py --session "<conversation_id>" -q "<follow-up>" --pipe

# Custom region
python3 scripts/call_oos_chatops_agent.py -q "<query>" --region cn-beijing --pipe

# Long-running operations
python3 scripts/call_oos_chatops_agent.py -q "<complex query>" --timeout 600 --pipe

Output Format (PIPE mode)

CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
(actual answer content)
=== OOS CHATOPS ANSWER END ===

Output Parsing and Verification

When processing script output, you MUST follow these rules strictly:

1. Single source of truth: Only the text between === OOS CHATOPS ANSWER BEGIN === and === OOS CHATOPS ANSWER END === is the factual answer. Everything outside these delimiters is metadata or progress.
2. No hallucinated counts: If you need to report resource counts (e.g., "53 ECS instances"), the number MUST come from the text between the delimiters. NEVER estimate or use prior knowledge to invent numbers.
3. Self-check before reporting: Before delivering the final answer to the user, verify that every data point (instance IDs, counts, statuses) is directly traceable to the delimiter-enclosed text. If the OOS answer says "53 instances" but you cannot find that number in the text, do NOT report it.
4. Verbatim relay preferred: When in doubt, quote the OOS answer directly rather than paraphrasing. Paraphrasing introduces hallucination risk.

Conversation Management

1. MUST extract CONVERSATION: <id> from output after every call and record it immediately
2. MUST pass --session "<id>" for all subsequent queries in the same context. Omitting --session is a failure
3. Starting a new conversation loses all prior context
4. On error or empty response: MUST retry once with the same --session. After two consecutive failures, report the error details honestly to the user. NEVER fabricate results or silently abandon the conversation

Example:

# Query 1
$ python3 scripts/call_oos_chatops_agent.py -q "List ECS instances in Hangzhou" --pipe
CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
53 ECS instances found...
=== OOS CHATOPS ANSWER END ===

# Query 2: reuse conversation
$ python3 scripts/call_oos_chatops_agent.py --session "04c7922a-86c7-4d11-8b97-96e22662c7f3" -q "Show cn-beijing instances" --pipe

Command-Line Options

Behavioral Rules

1. Script-only execution: ALL cloud resource interactions MUST go through python3 scripts/call_oos_chatops_agent.py. Even if aliyun CLI is available in the environment, it MUST be ignored. No exceptions.
2. Provide full context: include region, resource IDs, time range, desired action in one question.
3. Always reuse `--session` for follow-ups. New conversation = lost context.
4. Output integrity: Report ONLY what appears between BEGIN/END delimiters. Do NOT fabricate data.
5. Empty response: Retry once with same --session. If still empty, report honestly.
6. Long operations: Use --timeout 600 for batch operations or comprehensive checks.
7. Explicit parameter passing: When the user or task specifies region, timeout, or other parameters, you MUST explicitly pass the corresponding flags (e.g., --region cn-hangzhou, --timeout 600). NEVER rely on script built-in defaults. Omitting an explicitly requested parameter is treated as invocation failure.

Troubleshooting

Observability

All OOS Chat API HTTP requests carry a User-Agent header for tracing:

AlibabaCloud-Agent-Skills/alibabacloud-oos-chatops-agent/{session-id}

• alibabacloud-oos-chatops-agent — fixed skill identifier (matches the name field in frontmatter).
• {session-id} — a 32-character hex string, read from the SKILL_SESSION_ID environment variable. If not set, the script generates uuid.uuid4().hex. The same session-id is shared across all requests in a single invocation, enabling correlation of API calls in server-side logs.

Generate exactly one session-id per skill invocation. If SKILL_SESSION_ID is already set, reuse that value after validating it is 32 hex characters; otherwise generate a new one via uuid4().hex and set it for the duration of the invocation.