alibabacloud-sls-data-agent

name	alibabacloud-sls-data-agent
description	Invoke SLS DataAgent to autonomously perform data acquisition, processing, analysis, and visualization for Alibaba Cloud SLS (Simple Log Service). Acts as a fully automated data analyst — ask a question in natural language, get structured conclusions and charts. Use when the user asks about: 数据分析, 取数, 数据查询, 日志分析, SLS, 可视化, 图表, 数据洞察, data analysis, DataAgent, 全自动数据分析师.

SLS DataAgent

SLS DataAgent is an AI assistant that autonomously understands natural language and automatically completes data acquisition, processing, analysis, and visualization. It acts as your "fully automated data analyst": you ask a question in natural language, and it fetches, cleans, analyzes the data, and returns conclusions and visualizations.

It is invoked through the SLS DataAgent OpenAPI; the session streams the analysis process and conclusions back over SSE.

Capabilities

• Natural language understanding: turn colloquial data questions into well-defined analysis tasks.
• Data acquisition: automatically locate and pull relevant data (logs, metrics, etc.) within the SLS project.
• Data processing: cleaning, aggregation, transformation.
• Data analysis: statistics, trends, comparisons, anomalies / insights.
• Visualization: generate charts and structured conclusion reports.

Digital Employee (agentId)

A session is handled by a "digital employee" (digital employee / agentId).

• Generic and customizable: --digital-employee <name> > SLS_DATA_AGENT_EMPLOYEE env var > script default apsara-ops.
• The console assistantId is the digital employee in use.

Built-in Skill (capability routing)

Use --skill to select a DataAgent built-in skill; omit it to use the general capability.

Skill ID	Description
builtin.sls.sls-sql-generation	SQL generation
builtin.sls.spl-generation	SPL generation
builtin.sls.sls-loongcollector	LoongCollector ingestion ops
builtin.sls.sls-visualization	Dashboard assistant

Logstore context

Use --logstore to specify the target logstore, giving the analysis an explicit data source scope.

Environment Variables

Variable	Required	Description
SLS_DATA_AGENT_PROJECT	Yes	SLS project name (the scope; can also be passed via --project).
SLS_DATA_AGENT_REGION	Yes	Region where the SLS project resides (e.g. cn-shanghai, cn-beijing).
SLS_DATA_AGENT_EMPLOYEE	No	Digital employee name (default apsara-ops).
SLS_DATA_AGENT_LOGSTORE	No	Default target logstore (can also be passed via --logstore).
SLS_DATA_AGENT_SKILL	No	Built-in skill ID (e.g. builtin.sls.sls-sql-generation). Omit to use the general capability.

Credentials — uses the Alibaba Cloud Credentials SDK default chain (STS / RAM role / CLI profile ~/.aliyun/config.json / env vars ALIBABA_CLOUD_ACCESS_KEY_ID+ALIBABA_CLOUD_ACCESS_KEY_SECRET).

Pre-flight check:

missing=""
[ -z "$SLS_DATA_AGENT_PROJECT" ] && missing="$missing SLS_DATA_AGENT_PROJECT"
[ -z "$SLS_DATA_AGENT_REGION" ]  && missing="$missing SLS_DATA_AGENT_REGION"
if [ -n "$missing" ]; then echo "ERROR: Missing required environment variables:$missing" >&2; exit 1; fi
echo "OK: PROJECT=$SLS_DATA_AGENT_PROJECT REGION=$SLS_DATA_AGENT_REGION"

If a required value is empty, stop and ask the user; do not substitute a placeholder such as example-project.

Invocation

--pipe is mandatory: it guarantees stdout emits the THREAD line and the === DATA AGENT ANSWER BEGIN/END === delimiters, so downstream can parse reliably.

pip3 install -r scripts/requirements.txt

# First question (auto-creates a session; most queries need --logstore)
python3 scripts/call_sls_data_agent.py \
  --logstore my_logstore \
  --question "<full data-analysis request>" --pipe

# Follow-up (reuse the THREAD ID from the previous step to keep context)
python3 scripts/call_sls_data_agent.py \
  --thread "<thread_id>" --question "<follow-up>" --pipe

# Specify a built-in skill
python3 scripts/call_sls_data_agent.py \
  --skill builtin.sls.sls-sql-generation \
  --logstore my_logstore \
  --question "number of error logs in the last 5 minutes" --pipe

Example output (pipe):

THREAD: thread-abc123-xyz
DATA_AGENT_URL: https://starops.console.aliyun.com/chat?threadId=thread-abc123-xyz&assistantId=apsara-ops
=== DATA AGENT ANSWER BEGIN ===
(analysis conclusion / visualization description)
=== DATA AGENT ANSWER END ===

Behavioral Notes

1. A DataAgent call is a long task: a single session may trigger multi-step internal analysis and take several minutes; the default timeout is 30 minutes.
2. Provide the full context in one go: SLS project, time range, target logstore/fields, the metrics to analyze, and the expected chart/conclusion form.
3. Always reuse --thread for follow-ups, otherwise context and intermediate results are lost.
4. Always pass --pipe: tool status and intermediate progress go to stderr; stdout keeps only the reusable thread id and the final answer.
5. Conclusions must be based on the real return between the BEGIN / END delimiters: cite concrete data points, do not fabricate. If the answer is empty, retry once with the same --thread; if still empty, state plainly that DataAgent returned no valid data.

Troubleshooting

1. HTTP 401/403 — credentials did not resolve to an authorized identity. Confirm the default chain resolves valid credentials and that the identity is allowed to call the SLS DataAgent OpenAPI. See references/ram-policies.md.
2. HTTP 404 — the digital employee (--digital-employee, default apsara-ops) or the SLS project (SLS_DATA_AGENT_PROJECT) does not exist. Verify both.
3. ConfigError: Missing required SLS DataAgent configuration — one of SLS_DATA_AGENT_PROJECT / SLS_DATA_AGENT_REGION is empty.
4. CredentialError — the default chain found no valid credential source.
5. Idle timeout — no SSE event within --idle-timeout seconds. Increase the value if needed, or retry with the same --thread.
6. ModuleNotFoundError — run pip3 install -r scripts/requirements.txt first.

API Surface

The script calls the SLS DataAgent OpenAPI directly (ACS3-HMAC-SHA256 signing); the endpoint defaults to starops.cn-beijing.aliyuncs.com and can be overridden via SLS_DATA_AGENT_ENDPOINT:

• Create a session (thread)
• Start a conversation and stream the analysis process and conclusions (SSE)

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

Observability

Every HTTP request carries a user-agent header for tracing:

AlibabaCloud-Agent-Skills/alibabacloud-sls-data-agent/{session-id}

• alibabacloud-sls-data-agent — fixed skill identifier (matches the name field).
• {session-id} — a 32-character hex string, read from the SKILL_SESSION_ID environment variable. If the env var is not set, the script falls back to generating uuid.uuid4().hex. The same session-id is shared across all requests in a single invocation (CreateThread + CreateChat), enabling correlation of API calls in server-side logs.