alibabacloud-data-agent-skill

metadata: author: DataAgent Team version: "1.8.6"

変更履歴

• v1.8.6：サーバーで event: プレフィックス行が省略された場合の SSE 解析を修正（フォールバックとして JSON ペイロードから event_type を抽出）；すべての SSE ストリーミングメソッド（GetChatContent）に DMSUnit を追加；db、file、attach サブコマンドに --dms-unit CLI フラグを追加；attach サブコマンドに --workspace-id CLI フラグを追加；DMSUnit の解決では、GetActiveRouteUnit とリージョンのフォールバックより先に、環境変数／設定／CLI のオーバーライドを使用。
• v1.8.5 — データベース一覧取得を ListTagMetaAsset（dms-enterprise 2018-11-01）に移行；ワークスペースの自動解決（CLI --workspace-id > 環境変数 DATA_AGENT_WORKSPACE_ID > InitDataAgentPersonalWorkspace）；db サブコマンドの --instance-name を任意に変更。
• v1.8.4：プロジェクトの Python 仮想環境（venv/）のセットアップと有効化を文書化；ASK_DATA／ANALYSIS のエンドツーエンド回帰テストに関する注記を追加（非同期＋attach）
• v1.8.3：db と file サブコマンドで、簡略化されたモード区分の --session-mode を指定可能に変更
• v1.8.2：SendChatMessage でメッセージごとのモード上書きに対応（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 ドキュメントの構成を最適化、pro モードの仕様書を分離
• 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 を使用する（推奨）

スキルのディレクトリ（alibabacloud-data-agent-skill/）で作業してください。ビルド済みの 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 認証を使用します。

環境変数

変数	説明	デフォルト
DATA_AGENT_API_KEY	API キー認証（ファイル分析のシナリオ）	—
DATA_AGENT_REGION	リージョン ID	cn-hangzhou
DATA_AGENT_DMS_UNIT	DMSUnit の上書き（別名 DATA_AGENT_DMSUNIT）	自動解決
DATA_AGENT_WORKSPACE_ID	デフォルトのワークスペース ID	自動で個人用ワークスペースを設定
DATA_AGENT_CUSTOM_AGENT_ID	デフォルトのカスタムエージェント ID	—
DATA_AGENT_ENDPOINT	カスタムエンドポイント	自動生成
DATA_AGENT_DMS_ENTERPRISE_ENDPOINT	検出 API 用の dms-enterprise ホスト（DATA_AGENT_ENDPOINT の対象外）。VPC のみのエグレスの場合に設定	dms-enterprise.{region}.aliyuncs.com
DATA_AGENT_TIMEOUT	リクエストタイムアウト（秒）	300
DATA_AGENT_MAX_RETRY	最大再試行回数	3
DATA_AGENT_POLL_INTERVAL	ポーリング間隔（秒）	2
DATA_AGENT_MAX_POLL_COUNT	最大ポーリング回数	60
DATA_AGENT_DEBUG_API	API リクエストの詳細を表示	false

すべての変数は .env ファイルに設定するか、環境変数としてエクスポートできます。CLI フラグ（--dms-unit、--workspace-id、--custom-agent-id）は、対応する環境変数より優先されます。

オプション 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 Console

権限要件

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 サブコマンドを使用して分析できます

---

セッションモード

• auto（デフォルト）：バックエンドがインテリジェントに判断し、クエリの複雑さに応じて最適なモードを自動選択します
• lite：クイッククエリモードです。1 秒未満で応答し、簡単な質疑応答やシンプルな SQL クエリに適しています
• pro：詳細分析モードです。5～40 分かかります。非同期実行用のサブエージェントを起動するか、--async-run パラメーターを使用する必要があります
• ultra：多角的なインサイトを含む、最も徹底した分析を行います。pro と同じ計画確認フローに従います

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

lite モードと pro モードの両方で、chinook データベースを使用した async + attach フローの回帰テストを実施しています。

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

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

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

pro／ultra モードの詳細は、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 認証モードの両方で、この優先順位が適用されます。

DMSUnit の解決

DMSUnit は、次の優先順位で自動的に解決されます。

1. 環境変数 DATA_AGENT_DMS_UNIT
2. GetActiveRouteUnit による動的なルート検索
3. DATA_AGENT_REGION によるリージョンのフォールバック

テナントで特定の DMSUnit を使用する必要がある場合にのみ、DATA_AGENT_DMS_UNIT を設定してください。自動ルート検索を使用する場合は、設定しないでください。

ListTagMetaAsset によるデータ検出は引き続きリージョン単位で行われ、sys::DMS-DA::<region>::space:<workspace> などのタグで DATA_AGENT_REGION を使用します。

---

カスタムエージェント

カスタムエージェントは、ユーザーが定義する AI エージェントです。専門的な指示、ナレッジベース、データスコープ設定を備えています。

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

注：--custom-agent-id を指定する場合、データソースのパラメーター（--dms-instance-id、--dms-db-id、--db-name、--tables）は不要であり、指定しないでください。カスタムエージェントには独自のデータスコープ設定がすでにあります。必要なのは --workspace-id とセッションオプション（例：--session-mode、--plan-mode）のみです。

注：カスタムエージェントのセッションでは、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"	pro / ultra モードで生成された実行プランを承認します
プランの変更	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 --session-id <ID> --dms-unit cn-hangzhou --workspace-id <WS>	セッションのDMSUnitとワークスペースを上書きします

基本的なワークフロー（非同期＋attach）

長時間の分析における標準的なパターンは、**非同期のdb起動 → それ以外はすべてattach**です。

# 1) Kick off async analysis, returns SESSION_ID immediately
python3 scripts/data_agent_cli.py db \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables "employees,departments" \
    --workspace-id <workspace_id> \
    --session-mode pro \
    -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、テーブルのプロファイリング、ユーザーの意図が保持されるため、回答の一貫性が保たれます。
• コストの削減 — 質問のたびにスキーマの再発見やテーブルの再プロファイリングを行う必要がありません。
• プランの管理 — pro / ultra のプランには明示的な確認が必要です。実行を開始できるのはattach -q "confirm"だけです。
• 耐障害性 — --checkpoint / --from-startにより、ネットワーク切断やクライアントの再起動が発生しても、長時間のタスクを確実に継続できます。
• チームでの共同作業 — Session IDを共有すれば、チームメイトも同じセッションにattachして進捗と結果を確認できます。

基本ルール

1. db / fileでセッションを一度だけ作成し、それ以降はすべてattachで進めます。
2. 起動後に表示されるSession IDを記録します。これだけがセッションを識別する手段です。
3. pro / ultra モードでは、プランの確認に必ず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-instance-id <DMS_INSTANCE_ID> \
    --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 pro/ultra 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 \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --workspace-id <WORKSPACE_ID> \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> -q "Which department has the highest average salary"

# 5b. Query with explicit DMSUnit (e.g. cn-shenzhen region, cn-hangzhou DMSUnit)
DATA_AGENT_REGION=cn-shenzhen python3 scripts/data_agent_cli.py db \
    --dms-instance-id <DMS_INSTANCE_ID> \
    --workspace-id <WORKSPACE_ID> \
    --dms-unit cn-hangzhou \
    --dms-db-id <dbId> \
    --db-name <schemaName> \
    --tables <table1,table2> -q "your question"

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

# 7. Use a custom agent for analysis (no DB params needed)
python3 scripts/data_agent_cli.py db --custom-agent-id <AGENT_ID> --workspace-id <WS_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