alibabacloud-data-agent-skill

metadata: author: DataAgent Team version: "1.8.5"

変更履歴

• v1.8.5 — データベース一覧の取得を ListTagMetaAsset（dms-enterprise 2018-11-01）に移行。ワークスペースの自動解決（CLI --workspace-id > 環境変数 DATA_AGENT_WORKSPACE_ID > InitDataAgentPersonalWorkspace）。db サブコマンドの --dms-instance-id / --instance-name を任意に変更。
• v1.8.4：プロジェクトの Python 仮想環境（venv/）のセットアップと有効化について記載。ASK_DATA / ANALYSIS のエンドツーエンド回帰テストの注記を追加（非同期 + attach）
• v1.8.3：db および file サブコマンドで --session-mode CLAW を受け付けるように変更
• v1.8.2：SendChatMessage がメッセージごとの Mode=CLAW に対応（SessionConfig.Mode 経由で注入）。GetActiveRouteUnit による DMSUnit の動的解決
• v1.8.1：セッション再利用の中核となる仕組みとして、attach ベースのセッション再利用を強調。ゴールデンワークフロー、機能マトリックス、使用ルールを追加
• v1.8.0：ワークスペース（共同作業スペース）対応を追加。カスタムエージェント対応を追加
• v1.7.2：明示的な AK/SK の代わりに Alibaba Cloud のデフォルト認証情報チェーンを使用。User-Agent ヘッダーを追加。RAM ポリシーのワイルドカードに関する問題を修正
• v1.7.1：CLI ls コマンドの API レスポンス解析を修正（大文字と小文字を区別しないフィールド名に対応）。SKILL ドキュメントの構成を最適化。ANALYSIS モードの仕様書を分離
• v1.7.0：API_KEY 認証に対応。ネイティブ非同期実行モード、セッション分離、強化された attach モードを追加。ログ出力を最適化

---

---

インストール

Python 環境（venv）— 必ずお読みください

🚨 必須要件：Python ≥ 3.10

macOS のシステム標準 /usr/bin/python3 は通常 3.8 または 3.9 で、match/case、TypeAlias、| によるユニオン構文などの 3.10 以降の機能を使用するこのプロジェクトを実行できません。

まずバージョンを確認してください：python3 --version。3.10 未満の場合は、Homebrew または pyenv でインストールしてください：

# Homebrew
brew install [email protected]
# または pyenv
pyenv install 3.12.4 && pyenv local 3.12.4

⚠️ venv 仮想環境を必ず使用してください。依存関係をグローバルにインストールしないでください。 システム Python に対して pip install を実行すると、環境が汚染され、権限の問題で失敗する場合があります。

既存の venv を使用（推奨）

プロジェクトには、依存関係がすべてインストール済みの venv/ ディレクトリが含まれています。可能な限りこれを使用してください：

cd alibabacloud-data-agent-skill

# Option A (recommended): activate the venv
source venv/bin/activate
python3 scripts/data_agent_cli.py ls

# Option B: invoke the venv interpreter directly (no activation needed)
venv/bin/python3 scripts/data_agent_cli.py ls

venv を再作成

venv/ がない場合や依存関係が破損している場合は、3.10 以降の Python を使って再作成してください：

python3.12 -m venv venv          # explicitly use a 3.10+ interpreter
source venv/bin/activate
pip install -r scripts/requirements.txt

ヒント：このドキュメントの例では、すべて python3 scripts/data_agent_cli.py ... と記載しています。venv が有効な場合、python3 は自動的に venv のインタープリターを参照します。有効でない場合は、先頭に venv/bin/python3 を付けてください。

認証情報の設定

この Skill では、Alibaba Cloud のデフォルト認証情報チェーン（推奨）または API_KEY 認証を使用します。

オプション 1：デフォルト認証情報チェーン（推奨）

この Skill は Alibaba Cloud SDK のデフォルト認証情報チェーンを使用して認証情報を自動的に取得します。環境変数、設定ファイル、インスタンスロールなどに対応しています。

Alibaba Cloud 認証情報チェーンのドキュメントを参照してください。

オプション 2：API_KEY 認証（ファイル分析のみ）

export DATA_AGENT_API_KEY=your-api-key
export DATA_AGENT_REGION=cn-hangzhou

API_KEY の取得先：Data Agent コンソール

権限要件

RAM ユーザーには AliyunDMSFullAccess または AliyunDMSDataAgentFullAccess 権限が必要です。 詳しい権限情報については、RAM-POLICIES.mdを参照してください。

デバッグモード

DATA_AGENT_DEBUG_API=1 python3 scripts/data_agent_cli.py file example.csv -q "analyze"

💡 はじめにあたってのヒント

• 初めて試す場合は、組み込みのデモデータベース internal_data_employees（従業員、部署、給与データを含む DataAgent 組み込みのテストデータベース）を使用してください
• または、ローカルファイル assets/example_game_data.csv を使ってファイル分析を試してください

Data Agent CLI — 統合コマンドラインデータ分析ツール

概要

scripts/data_agent_cli.py を使うと、データの発見 → 分析の開始 → 進捗の追跡 → 結果の取得までのワークフロー全体を実行できます。

コアコンセプト

⚠️ 重要な前提条件：Data Agent が分析できるのは、Data Agent Data Center にインポートされたデータベースのみです。

• Data Center：Data Agent のデータセンターです。ここにあるデータベースのみ分析できます
• DMS：Alibaba Cloud Data Management Service です。すべてのデータベースのメタデータを保存します
• 関係：DMS に登録されたデータベース ≠ Data Center 内のデータベース

使用手順：

1. まず ls を使用して、対象のデータベースが Data Center に存在するか確認します
2. 見つからない場合は、dms サブコマンドでデータベース情報を検索し、次に import サブコマンドでインポートします
3. インポートが成功したら、db サブコマンドを使用して分析できます

---

分析モード

• ASK_DATA（デフォルト）：同期実行で、1 秒未満で応答します。簡単な質疑応答に適しています
• ANALYSIS：詳細な分析を行います。完了まで 5～40 分かかるため、非同期実行にはサブエージェントを起動するか、--async-run パラメーターを使用する必要があります
• INSIGHT：インサイトを重視した探索を行います。ANALYSIS と同じ計画確認フローに従います
• CLAW：エージェント型の CLAW モードです。2 つのエントリーポイントがあります。
  • CLI：db --session-mode CLAW ... / file --session-mode CLAW ...（セッション単位）
  • SDK：client.send_message(...) / AsyncDataAgentClient.send_message(...) に mode="CLAW" を渡すと、SessionConfig.Mode を介して単一のメッセージのモードを上書きできます

エンドツーエンド回帰テストのリファレンス（v1.8.4 で検証済み）

ASK_DATA モードと ANALYSIS モードはどちらも、chinook データベースに対して非同期実行＋attach フローで回帰テストされています。

モード	開始方法	確認された処理の流れ	通常の所要時間
ASK_DATA	db --session-mode ASK_DATA -q "..."	非同期ワーカー → ライブ SSE → result.json={"status":"completed"}	約 15 秒
ANALYSIS	db --session-mode ANALYSIS -q "..."	非同期ワーカー → 計画 → WAIT_INPUT → attach -q "confirm" → ステップごとの実行 → Excel／Chart 成果物 → テキストレポート → 2 回目の WAIT_INPUT（ウェブページのレンダリング）	2～10 分（テキスト）；ウェブページのレンダリングを行う場合はさらに 10 分

sessions/<SESSION_ID>/progress.log で確認すべき主なチェックポイント：

• > User Query: ... — リクエストを受信
• ### Execution Plan (ID: ...) — ANALYSIS の計画が生成されました。続行するには attach -q "confirm" を使用します
• > ⚠️ Plan confirmed, continuing analysis... — 計画が承認され、実行を開始
• ## Step N/M: ... — 成果物へのリンクを含む、ステップごとの進捗
• ### Report Render + ⚠️ Please review the report rendering request. — HTML レポートのレンダリングに関する確認（任意）

詳細については、ANALYSIS_MODE.md を参照してください

---

ワークスペース（共同作業スペース）

ワークスペースは、セッション、データソース、アクセス制御を共有してチームでデータ分析を行える共同作業スペースです。

• ワークスペースの一覧表示：workspace サブコマンドを使用して、利用可能なワークスペース（個人用または共有）を確認します
• セッションをワークスペースに関連付ける：db または file を使用して特定のワークスペースのコンテキスト内にセッションを作成するときは、--workspace-id <ID> を渡します
• ワークスペースの種類：MY（デフォルト。個人用スペース）、ALL（共有スペースを含む、アクセス可能なすべてのスペース）

注：ワークスペース内にセッションを作成すると、それ以降のすべての API 呼び出し（describe、メッセージ送信など）にワークスペースのコンテキストが自動的に引き継がれます。

ワークスペースの解決

ワークスペース ID は次の順序で自動的に解決されます。

1. CLI フラグ --workspace-id <id>
2. 環境変数 DATA_AGENT_WORKSPACE_ID
3. InitDataAgentPersonalWorkspace による個人用ワークスペースの自動作成

AK/SK と API_KEY のどちらの認証モードも、この解決順序に対応しています。

---

カスタムエージェント

カスタムエージェントは、ユーザー定義の AI エージェントです。特化した指示、ナレッジベース、データ範囲の設定を備えています。

• カスタムエージェントの一覧表示：agent サブコマンドを使用して、利用可能なカスタムエージェントを確認します（デフォルトではステータスが RELEASED のもの）。
• エージェントの詳細表示：agent describe --custom-agent-id <ID> を使用して、エージェントの設定全体を確認します。
• セッションとカスタムエージェントの紐付け：db または file の使用時に --custom-agent-id <ID> を指定すると、特定のカスタムエージェントを使用するセッションを作成できます。

注：カスタムエージェントのセッションでは、自動的に prod ステージが使用されます。カスタムエージェントの指示、ナレッジ、データ範囲が分析セッションに適用されます。

---

attach によるセッションの再利用（⭐ 中核となる仕組み）

ベストプラクティス：進行中または作成済みのセッションとやり取りする際は、attach を使用することを推奨します。同じデータ範囲について追加のやり取りを行う場合は、新しいセッションを作成せず、必ず attach を優先してください。

attach を使用する理由

db／file を呼び出してセッションを開始した後、そのセッションでの以降のやり取りはすべて attach --session-id <ID> を通じて行う必要があります。1 つのセッションはサーバー側の 1 つの会話コンテキストであり、セッションに安全に再接続する唯一の方法が attach です。

機能	コマンド	シナリオ
追加の質問	attach --session-id <ID> -q "..."	コンテキストをすべて維持して会話を続け、データ把握にかかる手間を省きます
プランの確認	attach --session-id <ID> -q "confirm"	ANALYSIS／INSIGHT モードで生成された実行プランを承認します
プランの変更	attach --session-id <ID> -q "simplify to 3 steps"	実行前にプランを調整します
進捗の監視	attach --session-id <ID>（-q なし）	長時間実行されるセッションの SSE 進捗をリアルタイムで追跡します
ネットワーク切断後の再開	attach --session-id <ID> --checkpoint <N>	中断後、N 番目のイベントから正確に復旧します
全履歴の再生	attach --session-id <ID> --from-start	イベント 0 からセッション全体を再ストリーミングします

基本のワークフロー（非同期 + attach）

長時間の分析における標準的なパターンは、非同期の db による開始 → 以降のすべての操作に attach を使用することです。

# 1) Kick off async analysis, returns SESSION_ID immediately
python3 scripts/data_agent_cli.py db \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables "employees,departments" \
    --workspace-id <workspace_id> \
    --session-mode ANALYSIS \
    -q "Analyze salary distribution"
# -> ✅ Async task started. Session ID: abc123xyz

# 2) Watch progress live (Ctrl-C is safe, server keeps running)
python3 scripts/data_agent_cli.py attach --session-id abc123xyz

# 3) Confirm or modify the plan when agent enters WAIT_INPUT
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "confirm"

# 4) Ask follow-up questions (reuses context, no re-import, no re-profiling)
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "Break down by job level"

# 5) Recover precisely if the stream was cut at event #219
python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219

# 6) Fetch generated reports / charts
python3 scripts/data_agent_cli.py reports --session-id abc123xyz

attach によるセッション再利用のメリット

• コンテキストの保持 — 以前の SQL、テーブルのプロファイリング、ユーザーの意図が保持されるため、回答の一貫性を保てます。
• コストの削減 — 質問のたびにスキーマの再確認やテーブルの再プロファイリングを行う必要がありません。
• プランの管理 — ANALYSIS／INSIGHT のプランには明示的な確認が必要です。プランを続行できるのは attach -q "confirm" のみです。
• 耐障害性 — --checkpoint／--from-start を使用することで、ネットワーク切断やクライアントの再起動が発生しても、長時間のタスクを確実に継続できます。
• チームでの共同作業 — Session ID を共有すれば、チームメンバーも同じセッションに attach して進捗や結果を確認できます。

運用の目安

1. db／file でセッションを一度だけ作成し、以降の操作はすべて attach で行います。
2. セッションを開始した後に表示される Session ID を記録してください。これがセッションにアクセスする唯一の手段です。
3. ANALYSIS／INSIGHT モードでは、プランの確認に必ず attach（新しい db ではなく）を使用してください。新しいセッションを作成すると、プランが失われます。
4. セッションの成果物（進捗ログ、チェックポイント、結果、画像）は、sessions/<SESSION_ID>/ に保存されます。

attach のパラメーター一覧については COMMANDS.md を、エンドツーエンドのシナリオについては WORKFLOWS.md を参照してください。

---

クイックスタート

# 1. List available databases
python3 scripts/data_agent_cli.py ls
# Example output:
#   chinook [mysql]  dbId=abc123  instanceResourceId=rm-xxx  catalogName=chinook
#   employees [mysql]  dbId=def456  instanceResourceId=rm-yyy  catalogName=employees

# 2. Create a session for initial analysis (record the returned Session ID!)
python3 scripts/data_agent_cli.py db \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> \
    --workspace-id <workspace_id> \
    -q "Which department has the highest average salary"
# -> ✅ Async task started. Session ID: abc123xyz

# 3. ⭐ Reuse the session — follow-up questions, confirm plans, monitor progress
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "Break down by month"
python3 scripts/data_agent_cli.py attach --session-id abc123xyz -q "confirm"     # approve ANALYSIS plan
python3 scripts/data_agent_cli.py attach --session-id abc123xyz                  # tail live progress
python3 scripts/data_agent_cli.py attach --session-id abc123xyz --checkpoint 219 # resume after drop

# 4. List workspaces
python3 scripts/data_agent_cli.py workspace

# 5. Query in a specific workspace
python3 scripts/data_agent_cli.py db \
    --workspace-id <WORKSPACE_ID> \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> -q "Which department has the highest average salary"

# 6. List available custom agents
python3 scripts/data_agent_cli.py agent

# 7. Use a custom agent for analysis
python3 scripts/data_agent_cli.py db --custom-agent-id <AGENT_ID> --dms-instance-id ... -q "your question"

注意：db／file でセッションを作成するのは一度だけです。追加のやり取りはすべて attach --session-id <ID> を通じて行ってください。

📖 ワークフロー、コマンドリファレンス、ベストプラクティスの詳細については、WORKFLOWS.md と COMMANDS.md を参照してください。

---

プロジェクト構成

                          # Skill root directory
├── SKILL.md              # This document
├── scripts/              # Source code
│   ├── data_agent/       # SDK module
│   ├── cli/              # CLI module
│   ├── data_agent_cli.py # CLI entry point
│   └── requirements.txt  # Dependencies
├── sessions/             # Session data
└── references/           # Reference documents