alibabacloud-sls-data-agent

SLS DataAgent

SLS DataAgent 是一款 AI 助手，能够自主理解自然语言，并自动完成数据获取、处理、分析和可视化。它就像你的“全自动数据分析师”：你用自然语言提出问题，它会获取、清理和分析数据，并返回结论和可视化结果。

它通过 SLS DataAgent OpenAPI 调用；会话通过 SSE 实时返回分析过程和结论。

能力

• 自然语言理解：将口语化的数据问题转化为定义明确的分析任务。
• 数据获取：自动在 SLS 项目中查找并提取相关数据（日志、指标等）。
• 数据处理：清理、聚合和转换。
• 数据分析：统计、趋势、比较、异常 / 洞察。
• 可视化：生成图表和结构化结论报告。

数字员工（agentId）

会话由“数字员工”（digital employee / agentId）处理。

• 通用且可自定义：--digital-employee <name> > SLS_DATA_AGENT_EMPLOYEE 环境变量 > 脚本默认值 apsara-ops。
• 控制台中的 assistantId 是当前使用的数字员工。

内置 Skill（能力路由）

使用 --skill 选择 DataAgent 内置 Skill；省略则使用通用能力。

Skill ID	描述
builtin.sls.sls-sql-generation	SQL 生成
builtin.sls.spl-generation	SPL 生成
builtin.sls.sls-loongcollector	LoongCollector 采集操作
builtin.sls.sls-visualization	仪表盘助手

Logstore 上下文

使用 --logstore 指定目标 Logstore，为分析明确数据源范围。

环境变量

变量	必需	描述
SLS_DATA_AGENT_PROJECT	是	SLS 项目名称（范围；也可通过 --project 传入）。
SLS_DATA_AGENT_REGION	是	SLS 项目所在地域（例如 cn-shanghai、cn-beijing）。
SLS_DATA_AGENT_EMPLOYEE	否	数字员工名称（默认值为 apsara-ops）。
SLS_DATA_AGENT_LOGSTORE	否	默认目标 Logstore（也可通过 --logstore 传入）。
SLS_DATA_AGENT_SKILL	否	内置 Skill ID（例如 builtin.sls.sls-sql-generation）。省略则使用通用能力。

凭证 — 使用 Alibaba Cloud Credentials SDK 默认链（STS / RAM 角色 / CLI 配置文件 ~/.aliyun/config.json / 环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID+ALIBABA_CLOUD_ACCESS_KEY_SECRET）。

执行前检查：

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"

如果必需值为空，请停止并询问用户；不要使用 example-project 之类的占位符代替。

调用

必须使用 --pipe：它可确保 stdout 输出 THREAD 行和 === DATA AGENT ANSWER BEGIN/END === 分隔符，以便下游可靠解析。

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

输出示例（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 ===

行为说明

1. DataAgent 调用是一项长时间运行的任务：单个会话可能触发多步内部分析，并耗时数分钟；默认超时时间为 30 分钟。
2. 一次性提供完整上下文：SLS 项目、时间范围、目标 Logstore / 字段、要分析的指标，以及预期的图表 / 结论形式。
3. 后续请求始终复用 --thread，否则上下文和中间结果会丢失。
4. 始终传入 --pipe：工具状态和中间进度会输出到 stderr；stdout 仅保留可复用的 thread id 和最终答案。
5. 结论必须基于 BEGIN / END 分隔符之间实际返回的内容：引用具体数据点，不要编造。如果答案为空，使用相同的 --thread 重试一次；如果仍为空，请明确说明 DataAgent 未返回有效数据。

故障排查

1. HTTP 401/403 — 凭证未解析为经过授权的身份。请确认默认凭证链解析出有效凭证，且该身份有权调用 SLS DataAgent OpenAPI。请参阅 references/ram-policies.md。
2. HTTP 404 — 数字员工（--digital-employee，默认值为 apsara-ops）或 SLS 项目（SLS_DATA_AGENT_PROJECT）不存在。请检查两者。
3. ConfigError: Missing required SLS DataAgent configuration — SLS_DATA_AGENT_PROJECT / SLS_DATA_AGENT_REGION 其中一个为空。
4. CredentialError — 默认凭证链未找到有效的凭证来源。
5. 空闲超时 — 在 --idle-timeout 秒内未收到 SSE 事件。如有需要，请增大该值，或使用相同的 --thread 重试。
6. ModuleNotFoundError — 请先运行 pip3 install -r scripts/requirements.txt。

API 接口

该脚本直接调用 SLS DataAgent OpenAPI（使用 ACS3-HMAC-SHA256 签名）；端点 默认为 starops.cn-beijing.aliyuncs.com，可通过 SLS_DATA_AGENT_ENDPOINT 覆盖：

• 创建会话（线程）
• 开始对话，并以流式方式传输分析过程和结论（SSE）

详情请参阅 references/api-reference.md 和 references/ram-policies.md。

可观测性

每个 HTTP 请求都会携带 user-agent 标头以便追踪：

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

• alibabacloud-sls-data-agent — 固定的技能标识符（与 name 字段一致）。
• {session-id} — 一个 32 位十六进制字符串，读取自 SKILL_SESSION_ID 环境变量。如果未设置该环境变量，脚本会改为生成 uuid.uuid4().hex。同一个 session-id 会在单次调用的所有请求（CreateThread + CreateChat）中共享，以便在服务端日志中关联 API 调用。