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 env var > スクリプトのデフォルト apsara-ops。
• コンソールの assistantId は、使用中のデジタル従業員です。

組み込みスキル（機能ルーティング）

--skill を使用して DataAgent の組み込みスキルを選択します。省略すると、一般機能が使用されます。

スキル 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	いいえ	組み込みスキル 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 は必須です。標準出力に 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

出力例（パイプ）：

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 を指定してください。ツールのステータスと中間の進捗は標準エラー出力に送られ、標準出力には再利用可能なスレッド ID と最終回答だけが出力されます。
5. 結論は BEGIN／END 区切りの間にある実際の応答に基づく必要があります。具体的なデータポイントを引用し、捏造しないでください。回答が空の場合は、同じ --thread を使って一度だけ再試行してください。それでも空の場合は、DataAgent から有効なデータが返されなかったことを明確に伝えてください。

トラブルシューティング

1. HTTP 401/403 — 認証情報から認可された ID を解決できませんでした。デフォルトのチェーンで有効な認証情報が解決されること、およびその ID に 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} — SKILL_SESSION_ID 環境変数から読み取られる 32 文字の 16 進数文字列です。環境変数が設定されていない場合、スクリプトは uuid.uuid4().hex を生成して使用します。1 回の実行におけるすべてのリクエスト（CreateThread + CreateChat）で同じ session-id が共有されるため、サーバー側ログで API 呼び出しを関連付けられます。